dw-05-plan

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

### 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:

# <Topic> Implementation Plan

**Goal:** <from outline>
**Architecture:** <key decisions>
**Tech Stack:** <relevant tech>

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

### Phase Progress

| # | Phase | Status | Validation Command | Result |
|---|-------|--------|--------------------|--------|
| 1 | <phase name> | `[ ] NOT STARTED` | `<exact validation command from phase>` | — |
| ... | ... | ... | ... | ... |

**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 | <short description> | `[ ]` | — | |
| ... | ... | ... | ... | ... |

**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

### 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:** <what changed> — <why> — <downstream impact>.

---

End the artifact with the YAML frontmatter block:

---
phase: plan
date: <today>
topic: <topic-slug>
repo: <repo>
git_sha: <HEAD>
input_artifacts: [00-ticket.md, 02-research.md, 03-design-discussion.md, 04-structure-outline.md]
total_phases: <N>
total_tasks: <N>
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=<the artifact directory from setup>
     TOPIC_SLUG=<topic slug>
     REPO=<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 <topic-slug> 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 <topic-slug> after revisions."