Work Packages: Merge Preflight Documentation
Inputs: Design documents from /kitty-specs/018-merge-preflight-documentation/ Prerequisites: plan.md (required), spec.md (user stories) Mission: documentation
Tests: Not applicable - documentation feature
Organization: Fine-grained subtasks (Txxx) roll up into work packages (WPxx). Each work package must be independently deliverable and testable.
Prompt Files: Each work package references a matching prompt file in /tasks/ generated by /spec-kitty.tasks. Lane status is stored in YAML frontmatter (lane: planned|doing|for_review|done).
Work Package WP01: Merge Guide (Priority: P1) 🎯 MVP
Goal: Create comprehensive merge workflow guide for users completing workspace-per-WP features. Independent Test: A new user can follow the guide to successfully merge a multi-WP feature. Prompt: /tasks/WP01-merge-guide.md
Included Subtasks
- ✅ T001 [P] Extract CLI flags and help text from
src/specify_cli/cli/commands/merge.py - ✅ T002 [P] Extract pre-flight validation checks from
src/specify_cli/merge/preflight.py - ✅ T003 [P] Capture dry-run output example by running
spec-kitty merge --dry-run - ✅ T004 Write
docs/how-to/merge-feature.mdfollowingaccept-and-merge.mdstyle - ✅ T005 Add merge strategies section (merge/squash/rebase)
- ✅ T006 Add pre-flight validation section with interpretation guidance
- ✅ T007 Add dry-run and conflict forecasting section with example output
- ✅ T008 Add cleanup options section (--keep-branch, --keep-worktree)
Implementation Notes
1. Read merge.py to extract all CLI flags and their descriptions 2. Read preflight.py to understand validation checks 3. Run actual merge --dry-run to capture real output 4. Structure doc following accept-and-merge.md pattern 5. Include both agent command and terminal command for each action
Parallel Opportunities
- T001, T002, T003 can proceed in parallel (different source files)
- T005-T008 can be written in parallel once T004 establishes structure
Dependencies
- None (starting package)
Risks & Mitigations
- Stale examples if code changes → Use actual command output, not fabricated examples
Work Package WP02: Troubleshooting Guide (Priority: P1)
Goal: Create problem-solution guide for merge recovery and conflict resolution. Independent Test: A user with an interrupted merge can follow the guide to recover within 5 minutes. Prompt: /tasks/WP02-troubleshooting-guide.md
Included Subtasks
- ✅ T009 [P] Extract error messages from merge.py and executor.py
- ✅ T010 [P] Document MergeState structure from
src/specify_cli/merge/state.py - ✅ T011 [P] Document status file auto-resolution from
src/specify_cli/merge/status_resolver.py - ✅ T012 Write
docs/how-to/troubleshoot-merge.mdwith decision tree - ✅ T013 Add --resume usage section with partial merge state examples
- ✅ T014 Add --abort usage section with when-to-use guidance
- ✅ T015 Add conflict resolution section (status files vs code files)
- ✅ T016 Add pre-flight failure section with each failure type and fix
- ✅ T017 Add error message reference table
Implementation Notes
1. Grep for console.print with "Error" or "red" in merge code 2. Read state.py to understand JSON structure 3. Create decision tree: "Merge failed?" → branches to different solutions 4. Each error message gets: exact text, cause, solution steps
Parallel Opportunities
- T009, T010, T011 can proceed in parallel (different source files)
- T013-T017 can be written in parallel once T012 establishes structure
Dependencies
- None (can proceed in parallel with WP01)
Risks & Mitigations
- Missing edge cases → Test each recovery scenario manually
Work Package WP03: CLAUDE.md Reference Update (Priority: P2)
Goal: Add developer reference section for merge patterns to enable contributors and AI agents. Independent Test: A contributor can use CLAUDE.md to understand merge state management without reading source code. Prompt: /tasks/WP03-claude-md-reference.md
Included Subtasks
- ✅ T018 [P] Extract MergeState dataclass fields and methods from state.py
- ✅ T019 [P] Extract PreflightResult structure from preflight.py
- ✅ T020 [P] Extract key function signatures from merge subpackage
- ✅ T021 Write "Merge & Preflight Patterns" section for CLAUDE.md
- ✅ T022 Add merge state persistence subsection with JSON example
- ✅ T023 Add pre-flight validation subsection with integration points
- ✅ T024 Add programmatic access code examples
Implementation Notes
1. Location: After "Workspace-per-Work-Package Development" section in CLAUDE.md 2. Include actual JSON example from merge-state.json format 3. Code examples should be copy-pasteable Python snippets 4. Reference actual function names and module paths
Parallel Opportunities
- T018, T019, T020 can proceed in parallel (different source files)
- T022-T024 can be written in parallel once T021 establishes section
Dependencies
- None (can proceed in parallel with WP01 and WP02)
Risks & Mitigations
- Section placement ambiguity → Explicitly specify "after Workspace-per-WP" section
Work Package WP04: Integration & Cross-References (Priority: P3)
Goal: Integrate new docs into site structure and add cross-references. Independent Test: All links work, new pages appear in navigation, style is consistent. Prompt: /tasks/WP04-integration-cross-references.md
Included Subtasks
- ✅ T025 Update
docs/toc.ymlto add new pages in how-to section - ✅ T026 Add cross-references to merge-feature.md (link to troubleshoot, accept-and-merge, etc.)
- ✅ T027 Add cross-references to troubleshoot-merge.md (link to merge-feature, workspace-per-wp)
- ✅ T028 Update accept-and-merge.md to link to new merge-feature.md
- ✅ T029 Verify all command examples are copy-pasteable and functional
- ✅ T030 Final style consistency check across all new docs
Implementation Notes
1. Follow toc.yml structure for adding new entries 2. Cross-reference pattern: Command Reference, See Also, Background, Getting Started sections 3. Test each command example in terminal 4. Compare style against accept-and-merge.md
Parallel Opportunities
- T025-T028 can proceed in parallel (different files)
- T029, T030 must wait for WP01-WP03 content
Dependencies
- Depends on WP01, WP02, WP03 (needs content to cross-reference and verify)
Risks & Mitigations
- Broken links → Verify with relative path resolution
Dependency & Execution Summary
- Sequence: WP01, WP02, WP03 can run in parallel → WP04 after all complete
- Parallelization: 3 of 4 work packages can execute simultaneously
- MVP Scope: WP01 (Merge Guide) is the minimum viable documentation
Subtask Index (Reference)
| Subtask ID | Summary | Work Package | Priority | Parallel? |
|---|---|---|---|---|
| T001 | Extract CLI flags from merge.py | WP01 | P1 | Yes |
| T002 | Extract preflight checks | WP01 | P1 | Yes |
| T003 | Capture dry-run output | WP01 | P1 | Yes |
| T004 | Write merge-feature.md structure | WP01 | P1 | No |
| T005 | Merge strategies section | WP01 | P1 | Yes |
| T006 | Pre-flight validation section | WP01 | P1 | Yes |
| T007 | Dry-run forecasting section | WP01 | P1 | Yes |
| T008 | Cleanup options section | WP01 | P1 | Yes |
| T009 | Extract error messages | WP02 | P1 | Yes |
| T010 | Document MergeState structure | WP02 | P1 | Yes |
| T011 | Document status auto-resolution | WP02 | P1 | Yes |
| T012 | Write troubleshoot-merge.md structure | WP02 | P1 | No |
| T013 | --resume usage section | WP02 | P1 | Yes |
| T014 | --abort usage section | WP02 | P1 | Yes |
| T015 | Conflict resolution section | WP02 | P1 | Yes |
| T016 | Pre-flight failure section | WP02 | P1 | Yes |
| T017 | Error message reference | WP02 | P1 | Yes |
| T018 | Extract MergeState fields | WP03 | P2 | Yes |
| T019 | Extract PreflightResult structure | WP03 | P2 | Yes |
| T020 | Extract function signatures | WP03 | P2 | Yes |
| T021 | Write CLAUDE.md section structure | WP03 | P2 | No |
| T022 | Merge state persistence subsection | WP03 | P2 | Yes |
| T023 | Pre-flight validation subsection | WP03 | P2 | Yes |
| T024 | Programmatic access examples | WP03 | P2 | Yes |
| T025 | Update toc.yml | WP04 | P3 | Yes |
| T026 | Cross-refs in merge-feature.md | WP04 | P3 | Yes |
| T027 | Cross-refs in troubleshoot-merge.md | WP04 | P3 | Yes |
| T028 | Update accept-and-merge.md links | WP04 | P3 | Yes |
| T029 | Verify command examples | WP04 | P3 | No |
| T030 | Final style consistency check | WP04 | P3 | No |
<!-- status-model:start -->
Canonical Status (Generated)
<!-- status-model:end -->
- WP01: done
- WP02: done
- WP03: done
- WP04: done