--- name: dw-05-plan description: "Use when deep-work Phase 4 structure outline is complete. Expands the outline into a detailed implementation plan with exact file paths, code patterns, tests, and validation commands." --- # Phase 5: Plan Expand the structure outline into a fully detailed implementation plan. Every task has exact file paths, function signatures, code patterns, test cases, and validation commands. The implementing agent executes mechanically — no architectural decisions remain. Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well. **Announce at start:** "Starting deep-work Phase 5: Plan." ## Setup 1. Run `"$SKILL_BASE_DIR/setup.sh" "$ARGUMENTS"` and parse stdout for `REPO`, `TOPIC_SLUG`, `ARTIFACT_DIR`. `$SKILL_BASE_DIR` is the "Base directory for this skill" path shown at the top of this prompt. - If the script exits 2 (`MISSING_SLUG` on stderr), ask user via AskUserQuestion for the topic slug, then re-run with the slug. ## Pre-flight Validation - `00-ticket.md` exists → if not: "Ticket not found. Complete Phases 1-4 first." **Stop.** - `02-research.md` exists → if not: "Research not found. Complete Phases 1-4 first." **Stop.** - `03-design-discussion.md` exists → if not: "Design decisions not found. Complete Phases 1-4 first." **Stop.** - `04-structure-outline.md` exists → if not: "Outline not found. Complete Phases 1-4 first." **Stop.** ## Process ### Step 1: Load context 1. Read `00-ticket.md` — initial prompt and context on the changes we're making 2. Read `03-design-discussion.md` — the primary source for: - Decided design questions and their implementation implications - **Patterns to Follow** — use these as the authoritative pattern references for tasks (preferred over raw research patterns, since these were explicitly chosen during design discussion) - Current State / Desired End State — frames the overall goal - Constraints — hard limits on implementation 3. Read `02-research.md` — file:line references and detailed code context (supplement patterns from design artifact, don't override them) 4. Read `04-structure-outline.md` — phase structure and file map ### Step 2: Expand phases into tasks For each phase in the outline, create tasks covering ONE file change (or tightly coupled pair). **Every task MUST include:** 1. **File:** Exact path, action (NEW/MODIFY), line range for modifications 2. **Pattern:** Research finding to follow with file:line ref (e.g., "Follow `pkg/handlers/user.go:30-55` pattern from Q2") 3. **What to create/modify:** Exact names, signatures, fields — enough detail that the implementer makes no design decisions 4. **Tests:** Test function names, cases with inputs/expected outputs, reference test patterns from research 5. **Validation:** Exact command and expected result 6. **Commit:** Files to include and suggested message **Task granularity:** 2-5 minutes each. Pattern: write failing test → run (expect fail) → implement → run (expect pass) → commit. Ideallly each task in a phase of the plan should be independent enough to execute in its own context window. Try to create discrete small tasks that can be chained together. **You MUST follow the outline** #### Task Structure ````markdown ### Task N: [Component Name] **Files:** - Create: `exact/path/to/file.py` - Modify: `exact/path/to/existing.py:123-145` - Test: `tests/exact/path/to/test.py` **Step 1: Write the failing test** ```python def test_specific_behavior(): result = function(input) assert result == expected ``` **Step 2: Run test to verify it fails** Run: `pytest tests/path/test.py::test_name -v` Expected: FAIL with "function not defined" **Step 3: Write minimal implementation** ```python def function(input): return expected ``` **Step 4: Run test to verify it passes** Run: `pytest tests/path/test.py::test_name -v` Expected: PASS **Step 5: Commit** ```bash git add tests/path/test.py src/path/file.py git commit -m "feat: add specific feature" ``` ```` ### Step 3: Phase success criteria Per phase: automated criteria (commands that must pass) + manual criteria. ### Step 4: Scope guards Per phase: "This phase does NOT include [X]" and "Do NOT modify [file] in this phase." ### Step 5: Address risks Include specific task or checkpoint for each risk from the outline's register. ### Step 6: Write artifact Write `05-plan.md` to the artifact directory. Include plan header: ````markdown # Implementation Plan **Goal:** **Architecture:** **Tech Stack:** ```` Followed by an **Execution Progress** section (before the phase details), then full phase/task detail in standard plan format. ### Step 7: Add execution progress tracker Insert an `## Execution Progress` section between the plan header and Phase 1. This enables independent phase execution — an implementing agent in a fresh conversation reads this section first to know exactly where to resume. Include three subsections: #### 7a: Phase Progress table ````markdown ### Phase Progress | # | Phase | Status | Validation Command | Result | |---|-------|--------|--------------------|--------| | 1 | | `[ ] NOT STARTED` | `` | — | | ... | ... | ... | ... | ... | **Status legend:** `[ ] NOT STARTED` | `[~] IN PROGRESS` | `[x] DONE` | `[!] BLOCKED` ``` One row per phase. The validation command is the same command from the phase's success criteria. The `Result` column is updated with PASS/FAIL + timestamp when validation runs. #### 7b: Task Completion table ````markdown ### Task Completion | Task | Description | Status | Committed | Deviations | |------|-------------|--------|-----------|------------| | **Phase 1** | | | | | | 1.1 | | `[ ]` | — | | | ... | ... | ... | ... | ... | **Task status legend:** `[ ]` pending | `[~]` in progress | `[x]` done | `[!]` blocked | `[-]` skipped ```` One row per task, grouped under phase header rows. Description is a terse summary (e.g., "`ApiDateCriteriaView` record"). Committed column gets the short SHA when committed. Deviations column notes any changes from the plan. #### 7c: Deviation Log ````markdown ### Deviation Log > Record any deviations from the plan here. Include: task ID, what changed, why, and > impact on downstream tasks. This is critical for maintaining plan integrity across > sessions. _No deviations recorded._ ```` This is a free-form section. The implementing agent appends entries here when a task requires changes from the plan. Format: `**Task X.Y:** — — `. --- End the artifact with the YAML frontmatter block: ```yaml --- phase: plan date: topic: repo: git_sha: input_artifacts: [00-ticket.md, 02-research.md, 03-design-discussion.md, 04-structure-outline.md] total_phases: total_tasks: status: complete --- ``` ### Step 8: Adversarial plan review (subagent) After writing the plan artifact, dispatch an **Opus subagent** to perform an adversarial review. This replaces the former standalone `/dw-05b-plan-review` skill. 1. Read the file `plan-review-prompt.md` from **this skill's directory** (same directory as this SKILL.md) 2. Dispatch a **foreground** Agent with: - `model: "opus"` - `description: "Adversarial plan review"` - `prompt:` the contents of `plan-review-prompt.md`, prepended with: ``` ARTIFACT_DIR= TOPIC_SLUG= REPO= ``` 3. When the subagent completes, read the `05b-plan-review.md` it wrote to the artifact directory 4. Present the review verdict and findings to the user ## Completion 1. Present the plan review results to the user 2. Update `.state.json` with `current_phase: 5, completed_phases: [1, 2, 3, 4, 5, "plan_review"]` 3. Based on the review verdict: - **APPROVED:** "Plan and review complete. No blocking issues. Proceed with `/dw-06-implement ` in a fresh conversation." - **APPROVED WITH CONDITIONS:** "Plan review found Important issues that should be addressed. Review the findings above and update `05-plan.md`, then proceed to implementation." - **REVISE:** "Plan review found Critical issues. Address the findings above and update `05-plan.md` before proceeding. Re-run `/dw-05-plan ` after revisions."