resolutionflow/docs/GITHUB-ISSUES-MIGRATION.md

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)