ec5c91c8e4
- Add next_steps TEXT column to sessions table via migration 034 - Add include_outcome_notes, include_next_steps, max_step_index to SessionExport - Add next_steps to SessionUpdate, SessionResponse, SessionComplete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
446 lines
13 KiB
Markdown
446 lines
13 KiB
Markdown
# GitHub Issues Migration Instructions
|
|
|
|
> **For Claude Code:** Use these instructions to set up GitHub Issues for Patherly
|
|
> **Repository:** github.com/patherly/patherly
|
|
> **Date:** February 2, 2026
|
|
|
|
---
|
|
|
|
## Status Snapshot (Updated February 12, 2026)
|
|
|
|
Live GitHub status (`patherly/patherly`):
|
|
- Total issues: 54
|
|
- Closed: 38
|
|
- Open: 16
|
|
|
|
### Completed So Far (Closed Issues)
|
|
|
|
- Foundation and initial Phase 2.5 set:
|
|
- `#2` to `#14` closed
|
|
- `#15` to `#19` closed
|
|
- Historical bug backlog:
|
|
- `#20` to `#23` closed
|
|
- Additional cleanup and UX/quality work:
|
|
- `#25`, `#28`, `#29`, `#30`, `#31`, `#33`, `#34`, `#35`, `#36`, `#37`, `#38` closed
|
|
- Recent quick wins delivered:
|
|
- `#51` Session timer
|
|
- `#52` Keyboard-first navigation
|
|
- `#53` Repeat last session
|
|
- `#54` Session draft auto-recovery
|
|
- `#55` Copy individual step to clipboard
|
|
|
|
### Current Open Feature Queue
|
|
|
|
- `#56` to `#71` remain open (newer strategic feature set, created February 10, 2026)
|
|
|
|
Note: This file remains the original migration/setup checklist; the section above is the current progress snapshot.
|
|
|
|
---
|
|
|
|
## Step 1: Create Labels
|
|
|
|
Create the following labels in the repository:
|
|
|
|
| Label | Color (hex) | Description |
|
|
|-------|-------------|-------------|
|
|
| `bug` | `d73a4a` | Something isn't working |
|
|
| `feature` | `0e8a16` | New functionality |
|
|
| `enhancement` | `a2eeef` | Improvement to existing feature |
|
|
| `documentation` | `0075ca` | Documentation updates |
|
|
| `backend` | `7057ff` | FastAPI/Python work |
|
|
| `frontend` | `fbca04` | React work |
|
|
| `database` | `b60205` | PostgreSQL/schema changes |
|
|
| `priority: high` | `d93f0b` | Do this soon |
|
|
| `priority: medium` | `fbca04` | Important but not urgent |
|
|
| `priority: low` | `c5def5` | Nice to have |
|
|
|
|
---
|
|
|
|
## Step 2: Create Milestones
|
|
|
|
| Milestone | Description | Due Date |
|
|
|-----------|-------------|----------|
|
|
| Phase 2 Completion | Tree editor polish, deployment | (leave open) |
|
|
| Phase 2.5 | Personal branching, step library | (leave open) |
|
|
| Backlog | Ideas not yet scheduled | (no due date) |
|
|
|
|
---
|
|
|
|
## Step 3: Create Issues
|
|
|
|
### Phase 2 Remaining (3 issues)
|
|
|
|
**Issue 1:**
|
|
- Title: Tree Editor Validation - required fields and orphan detection
|
|
- Labels: `feature`, `frontend`, `priority: high`
|
|
- Milestone: Phase 2 Completion
|
|
- Body:
|
|
```
|
|
Add validation to the tree editor:
|
|
- [ ] Required fields validation (name, at least one node)
|
|
- [ ] Orphan node detection (nodes not reachable from root)
|
|
- [ ] Circular reference detection
|
|
- [ ] Show validation errors before save
|
|
- [ ] Prevent save if validation fails
|
|
```
|
|
|
|
**Issue 2:**
|
|
- Title: User Preferences - export format default setting
|
|
- Labels: `feature`, `frontend`, `priority: medium`
|
|
- Milestone: Phase 2 Completion
|
|
- Body:
|
|
```
|
|
Add export format preference to user settings:
|
|
- [ ] Add "Default Export Format" dropdown in settings (Markdown/Text/HTML)
|
|
- [ ] Persist preference in localStorage
|
|
- [ ] Use preference as default in export dialog
|
|
- [ ] Dark mode toggle already complete ✅
|
|
```
|
|
|
|
**Issue 3:**
|
|
- Title: Deploy to Railway - CI/CD pipeline setup
|
|
- Labels: `feature`, `priority: high`
|
|
- Milestone: Phase 2 Completion
|
|
- Body:
|
|
```
|
|
Set up production deployment on Railway Pro:
|
|
- [ ] Configure Railway project with 3 services (PostgreSQL, backend, frontend)
|
|
- [ ] Set up environment variables
|
|
- [ ] Configure custom domains (patherly.com, api.patherly.com)
|
|
- [ ] Set up PR environments for testing
|
|
- [ ] Document deployment process
|
|
```
|
|
|
|
---
|
|
|
|
### Phase 2.5 Features (15 issues)
|
|
|
|
**Issue 4:**
|
|
- Title: Step Categories - database table and seed data
|
|
- Labels: `feature`, `backend`, `database`, `priority: high`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Create step_categories table for organizing the step library:
|
|
- [ ] Create Alembic migration for step_categories table
|
|
- [ ] Add SQLAlchemy model
|
|
- [ ] Seed default categories (Citrix/VDI, Active Directory, Microsoft 365, Networking, etc.)
|
|
- [ ] Create API endpoints for category CRUD (admin only)
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 5:**
|
|
- Title: Step Library - database schema and migrations
|
|
- Labels: `feature`, `backend`, `database`, `priority: high`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Create step_library table for reusable troubleshooting steps:
|
|
- [ ] Create Alembic migration
|
|
- [ ] Add SQLAlchemy model with fields: title, step_type, content (JSONB), visibility, category_id, tags, ratings aggregates
|
|
- [ ] Add indexes for search and filtering
|
|
- [ ] Add step_ratings table for user ratings/reviews
|
|
- [ ] Add step_usage_log table for "Verified Use" tracking
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 6:**
|
|
- Title: Step Library - CRUD API endpoints
|
|
- Labels: `feature`, `backend`, `priority: high`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Create API endpoints for step library:
|
|
- [ ] GET /api/v1/steps - List steps with filters (visibility, category, tags, rating)
|
|
- [ ] GET /api/v1/steps/{id} - Get step details
|
|
- [ ] POST /api/v1/steps - Create new step
|
|
- [ ] PUT /api/v1/steps/{id} - Update step
|
|
- [ ] DELETE /api/v1/steps/{id} - Soft delete
|
|
- [ ] GET /api/v1/steps/search - Full-text search
|
|
- [ ] GET /api/v1/steps/tags/popular - Popular tags
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 7:**
|
|
- Title: Step Library - rating and review system
|
|
- Labels: `feature`, `backend`, `priority: medium`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Implement step rating and review system:
|
|
- [ ] POST /api/v1/steps/{id}/rate - Rate a step (1-5 stars + optional review)
|
|
- [ ] PUT /api/v1/steps/{id}/rate - Update rating
|
|
- [ ] DELETE /api/v1/steps/{id}/rate - Remove rating
|
|
- [ ] POST /api/v1/steps/{id}/helpful - Vote helpful (yes/no)
|
|
- [ ] GET /api/v1/steps/{id}/reviews - Get reviews
|
|
- [ ] Track "Verified Use" when step is actually used in a session
|
|
- [ ] Calculate and update aggregated ratings on step_library table
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 8:**
|
|
- Title: Add Custom Step button in tree navigation
|
|
- Labels: `feature`, `frontend`, `priority: high`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Add ability to insert custom steps during active troubleshooting:
|
|
- [ ] Add "+ Add Custom Step" button at each decision node
|
|
- [ ] Button opens modal with two tabs: "Type My Own" and "Browse Library"
|
|
- [ ] Custom steps inserted into session only (not original tree)
|
|
- [ ] Visual indicator showing step is custom/user-added
|
|
- [ ] Custom steps included in session export
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 9:**
|
|
- Title: Custom step creation modal
|
|
- Labels: `feature`, `frontend`, `priority: high`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Create modal for adding custom steps:
|
|
- [ ] Tab 1: "Type My Own" - form to create step (type, title, description, commands)
|
|
- [ ] Tab 2: "Browse Library" - search and select from step library
|
|
- [ ] Option to save custom step to personal library
|
|
- [ ] Validate step before insertion
|
|
- [ ] Insert step into current session
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 10:**
|
|
- Title: Step library browser component
|
|
- Labels: `feature`, `frontend`, `priority: medium`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Create UI component for browsing step library:
|
|
- [ ] Search input with full-text search
|
|
- [ ] Category filter dropdown
|
|
- [ ] Tag filter (show popular tags as chips)
|
|
- [ ] Minimum rating filter
|
|
- [ ] Sort options (recent, popular, rating)
|
|
- [ ] Step cards showing title, type, rating, usage count
|
|
- [ ] Step preview/detail modal
|
|
- [ ] Insert button to add to session
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 11:**
|
|
- Title: User Trees - database schema
|
|
- Labels: `feature`, `backend`, `database`, `priority: medium`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Create user_trees table for personal/forked trees:
|
|
- [ ] Create Alembic migration
|
|
- [ ] Fields: user_id, forked_from_tree_id, name, tree_content (JSONB), visibility, share_token
|
|
- [ ] Add session_custom_steps table to track custom steps per session
|
|
- [ ] Add indexes for user lookup and share token
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 12:**
|
|
- Title: Tree forking API endpoint
|
|
- Labels: `feature`, `backend`, `priority: medium`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Create API for forking trees:
|
|
- [ ] POST /api/v1/user-trees/fork/{tree_id} - Fork an official tree
|
|
- [ ] Deep copy tree structure to user_trees
|
|
- [ ] Track lineage (forked_from_tree_id, forked_at_version)
|
|
- [ ] Increment fork_count on original tree
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 13:**
|
|
- Title: User Trees - CRUD endpoints
|
|
- Labels: `feature`, `backend`, `priority: medium`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Create API endpoints for user tree management:
|
|
- [ ] GET /api/v1/user-trees - List user's custom trees
|
|
- [ ] GET /api/v1/user-trees/{id} - Get custom tree
|
|
- [ ] POST /api/v1/user-trees - Create new custom tree
|
|
- [ ] PUT /api/v1/user-trees/{id} - Update custom tree
|
|
- [ ] DELETE /api/v1/user-trees/{id} - Soft delete
|
|
- [ ] PUT /api/v1/user-trees/{id}/share - Update sharing settings
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 14:**
|
|
- Title: My Trees dashboard page
|
|
- Labels: `feature`, `frontend`, `priority: medium`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Create "My Trees" page for managing personal trees:
|
|
- [ ] List user's forked/custom trees
|
|
- [ ] Show original tree reference (if forked)
|
|
- [ ] Last used date, usage count
|
|
- [ ] Quick actions: start session, edit, share, delete
|
|
- [ ] Fork button on tree detail view
|
|
- [ ] Notification when original tree updated (basic)
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 15:**
|
|
- Title: Tree sharing via link
|
|
- Labels: `feature`, `frontend`, `backend`, `priority: medium`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Allow sharing trees via link:
|
|
- [ ] Generate unique share token for tree
|
|
- [ ] GET /api/v1/shared/{share_token} - Access shared tree (no auth required)
|
|
- [ ] Share modal with visibility options (private, link, team, public)
|
|
- [ ] Copy link button
|
|
- [ ] Option to allow/disallow forking
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 16:**
|
|
- Title: Save session as custom tree
|
|
- Labels: `feature`, `frontend`, `backend`, `priority: low`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
After completing a session with custom steps, offer to save as tree:
|
|
- [ ] POST /api/v1/sessions/{id}/save-as-tree endpoint
|
|
- [ ] Prompt user after session completion (if custom steps were added)
|
|
- [ ] Create user_tree from session path + custom steps
|
|
- [ ] Allow user to name and edit before saving
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 17:**
|
|
- Title: Admin - category management UI
|
|
- Labels: `feature`, `frontend`, `priority: low`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Admin interface for managing step categories:
|
|
- [ ] List categories with step counts
|
|
- [ ] Create new category
|
|
- [ ] Edit category name/description
|
|
- [ ] Archive category (soft delete)
|
|
- [ ] Reorder categories (display_order)
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
**Issue 18:**
|
|
- Title: Rate/review modal after using a step
|
|
- Labels: `feature`, `frontend`, `priority: low`
|
|
- Milestone: Phase 2.5
|
|
- Body:
|
|
```
|
|
Prompt users to rate steps after using them:
|
|
- [ ] After session completion, show steps used from library
|
|
- [ ] Rating modal with 1-5 stars
|
|
- [ ] Optional written review (max 500 chars)
|
|
- [ ] "Was this helpful?" quick vote
|
|
- [ ] Mark rating as "Verified Use"
|
|
|
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
|
```
|
|
|
|
---
|
|
|
|
### Known Bugs (create as closed issues for history)
|
|
|
|
**Issue 19:**
|
|
- Title: [FIXED] DateTime timezone handling causing Internal Server Errors
|
|
- Labels: `bug`, `backend`
|
|
- State: CLOSED
|
|
- Body:
|
|
```
|
|
**Problem:** Mixing timezone-aware and timezone-naive datetime objects caused errors in session completion.
|
|
|
|
**Solution:**
|
|
- Updated all SQLAlchemy models to use `DateTime(timezone=True)`
|
|
- Changed all default datetime factories to `lambda: datetime.now(timezone.utc)`
|
|
|
|
**Files affected:** All models with timestamp fields
|
|
|
|
Fixed: January 28, 2026
|
|
```
|
|
|
|
**Issue 20:**
|
|
- Title: [FIXED] bcrypt/passlib version compatibility
|
|
- Labels: `bug`, `backend`
|
|
- State: CLOSED
|
|
- Body:
|
|
```
|
|
**Problem:** Password hashing failed with newer bcrypt versions.
|
|
|
|
**Solution:** Pin bcrypt version in requirements.txt:
|
|
- bcrypt==4.0.1
|
|
- passlib[bcrypt]==1.7.4
|
|
|
|
Fixed: January 2026
|
|
```
|
|
|
|
**Issue 21:**
|
|
- Title: [FIXED] Email validation rejecting .local domains
|
|
- Labels: `bug`, `backend`
|
|
- State: CLOSED
|
|
- Body:
|
|
```
|
|
**Problem:** Seed script failed with email validation error when using `.local` TLD.
|
|
|
|
**Cause:** email-validator library correctly rejects `.local` as reserved per RFC 6761.
|
|
|
|
**Solution:** Use standard domains like `example.com` for seed/test users.
|
|
|
|
Fixed: January 29, 2026
|
|
```
|
|
|
|
**Issue 22:**
|
|
- Title: [FIXED] httpx not installed for seed scripts
|
|
- Labels: `bug`, `backend`
|
|
- State: CLOSED
|
|
- Body:
|
|
```
|
|
**Problem:** Running seed_trees.py failed with ModuleNotFoundError for httpx.
|
|
|
|
**Solution:** Install httpx before running seed scripts:
|
|
```
|
|
pip install httpx
|
|
```
|
|
|
|
Fixed: January 29, 2026
|
|
```
|
|
|
|
---
|
|
|
|
## Step 4: Verify
|
|
|
|
After creating all issues:
|
|
1. Check that labels appear correctly
|
|
2. Check that milestones have correct issues assigned
|
|
3. Verify closed issues show in closed state
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- Issues 4-18 are Phase 2.5 features from PHASE-2.5-PERSONAL-BRANCHING.md
|
|
- Issues 19-22 are historical bugs documented in LESSONS-LEARNED.md (create as closed)
|
|
- Long-term feature ideas are in BACKLOG.md (not GitHub Issues yet)
|