first commit
This commit is contained in:
205
implementing-roadmap-phases/SKILL.md
Normal file
205
implementing-roadmap-phases/SKILL.md
Normal file
@@ -0,0 +1,205 @@
|
||||
---
|
||||
name: implementing-roadmap-phases
|
||||
description: Use when asked to review a roadmap document and implement a specific phase or phase range, e.g. "implement phase 3" or "implement phases 1-3 from the roadmap"
|
||||
---
|
||||
|
||||
# Implementing Roadmap Phases
|
||||
|
||||
## Overview
|
||||
|
||||
Structured workflow for implementing phases from roadmap documents. Ensures clarifying questions are always asked before coding, and the roadmap is always updated after each phase completes.
|
||||
|
||||
**Core principle:** Never implement blind — always parse, explore, ask, then build. Never leave the roadmap stale — always update after completing a phase.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User says "implement phase N" or "implement phases N-M" referencing a roadmap doc
|
||||
- User asks to "review this roadmap and build the next phase"
|
||||
- Any task driven by a phased planning document
|
||||
|
||||
**When NOT to use:** One-off feature requests not tied to a roadmap document.
|
||||
|
||||
## Workflow
|
||||
|
||||
```dot
|
||||
digraph roadmap_flow {
|
||||
rankdir=TB;
|
||||
parse [label="1. Parse Roadmap" shape=box];
|
||||
explore [label="2. Explore Referenced Patterns" shape=box];
|
||||
ask [label="3. Ask Clarifying Questions" shape=box];
|
||||
brief [label="4. Write Implementation Brief" shape=box style=bold];
|
||||
compact [label="4.5. Clear Context\n(/compact + re-read brief)" shape=box style=bold color=blue];
|
||||
implement [label="5. Dispatch Implementation\n(fresh context)" shape=box style=bold];
|
||||
verify [label="6. Verify & Fix" shape=box style=bold color=red];
|
||||
pass [label="All checks\npass?" shape=diamond];
|
||||
fix [label="Fix errors\n(max 3 attempts)" shape=box];
|
||||
escalate [label="Escalate to user" shape=box];
|
||||
update [label="7. Update Roadmap" shape=box];
|
||||
more [label="More phases\nin range?" shape=diamond];
|
||||
done [label="Done" shape=doublecircle];
|
||||
|
||||
parse -> explore -> ask -> brief -> compact -> implement -> verify -> pass;
|
||||
pass -> update [label="yes"];
|
||||
pass -> fix [label="no"];
|
||||
fix -> verify [label="retry"];
|
||||
fix -> escalate [label="max retries"];
|
||||
escalate -> update [label="user resolves"];
|
||||
update -> more;
|
||||
more -> parse [label="yes — next phase"];
|
||||
more -> done [label="no"];
|
||||
}
|
||||
```
|
||||
|
||||
### Step 1: Parse the Roadmap
|
||||
|
||||
Read the full document. Identify:
|
||||
- Target phase(s) and their requirements
|
||||
- Conventions section (naming, patterns, tech choices)
|
||||
- Dependency graph (what prior phases built that this phase needs)
|
||||
- Referenced patterns (e.g. "Follow `scans.py` pattern")
|
||||
- For ranges (e.g. "phases 1-3"): validate sequential order, note inter-phase dependencies
|
||||
|
||||
### Step 2: Explore Referenced Patterns
|
||||
|
||||
Read existing code files mentioned in implementation notes. Understand:
|
||||
- File structure and naming conventions used in referenced examples
|
||||
- How similar features were built (routes, services, DB queries, templates)
|
||||
- Conventions section requirements applied to real code
|
||||
|
||||
### Step 3: Ask Clarifying Questions (MANDATORY)
|
||||
|
||||
**Always ask at least one round of questions before implementing.** Categories:
|
||||
|
||||
- **Ambiguous requirements** — Anything in the phase spec that could be interpreted multiple ways
|
||||
- **Open design decisions** — Choices the roadmap left to the implementer
|
||||
- **Scope confirmation** — "Phase says X; should I also handle Y?"
|
||||
- **Dependency status** — "Phase references table Z from Phase 2; is that already migrated?"
|
||||
|
||||
Use `AskUserQuestion` tool with structured options where possible.
|
||||
|
||||
### Step 4: Write Implementation Brief (MANDATORY)
|
||||
|
||||
**Purpose:** Distill everything from steps 1-3 into a concise brief so implementation can run with clean context.
|
||||
|
||||
After clarifying questions are answered, write a brief to a temporary file (e.g. `/tmp/phase-N-brief.md`) containing:
|
||||
|
||||
1. **Phase goal** — One sentence summary of what to build
|
||||
2. **Files to create/modify** — Exact paths from the roadmap
|
||||
3. **Conventions** — Naming patterns, tech choices, coding patterns to follow
|
||||
4. **Design decisions** — Answers from clarifying questions
|
||||
5. **Reference patterns** — Key file paths explored in Step 2 that the implementer should read (NOT the content — just the paths, so the subagent reads them fresh)
|
||||
6. **Constraints** — Anything that must be true (e.g. "all queries filter by organization_id")
|
||||
|
||||
**Keep the brief under 100 lines.** This is the ONLY context the implementation subagent receives.
|
||||
|
||||
### Step 4.5: Clear Context (MANDATORY)
|
||||
|
||||
**Purpose:** Steps 1-3 read many files and fill the context with exploration noise. The brief captures everything needed — the exploration context is now dead weight that will degrade implementation quality.
|
||||
|
||||
**After writing the brief, you MUST:**
|
||||
|
||||
1. Tell the user: "Planning complete. Brief written to `/tmp/phase-N-brief.md`. Compacting context before implementation."
|
||||
2. Run `/compact` to compress the conversation history
|
||||
3. After compaction, **re-read only the brief file** (`/tmp/phase-N-brief.md`) to restore working context
|
||||
4. Then proceed to Step 5
|
||||
|
||||
**Why this matters:** Without compaction, the main agent carries thousands of tokens of file contents, dead-end explorations, and question/answer exchanges that are already distilled into the brief. This pollutes the context for verification (Step 6) and roadmap updates (Step 7), and can cause the agent to lose track of what was actually decided.
|
||||
|
||||
**Do NOT skip this step.** The brief is the single source of truth after planning. Everything else is noise.
|
||||
|
||||
### Step 5: Dispatch Implementation (Fresh Context)
|
||||
|
||||
**Use the Task tool** to spawn a subagent for implementation. This gives the implementer a clean context window free of exploration noise.
|
||||
|
||||
The Task prompt should:
|
||||
- Reference the brief file: "Read `/tmp/phase-N-brief.md` for full requirements"
|
||||
- Reference the roadmap file for additional detail if needed
|
||||
- List the specific files to create/modify
|
||||
- Instruct the subagent to read the reference pattern files listed in the brief before writing code
|
||||
|
||||
**For multi-phase ranges:** Complete Step 6 (update roadmap) before starting the next phase's Step 1.
|
||||
|
||||
**Subagent type:** Use `general-purpose` for phases that involve multiple file types (API + UI + migrations). Use `Bash` only for pure migration/script phases.
|
||||
|
||||
### Step 6: Verify & Fix (MANDATORY)
|
||||
|
||||
**Purpose:** Catch runtime errors, test failures, and schema mismatches before marking the phase complete. Never update the roadmap for broken code.
|
||||
|
||||
**Run these checks in order (stop at first failure):**
|
||||
|
||||
1. **App loads** — Run the app import/startup check (e.g. `uv run python -c "from src.main import get_app; app = get_app()"`) for each affected service
|
||||
2. **Tests pass** — Run the test suite for each affected service (e.g. `uv run pytest`)
|
||||
3. **Smoke test** — If the phase added API routes, verify they're registered (check route list or import the router)
|
||||
|
||||
**If any check fails:**
|
||||
|
||||
1. Read the full error output — identify root cause (missing column default, bad import, wrong type, etc.)
|
||||
2. Fix the issue directly — don't re-dispatch to a subagent for small fixes
|
||||
3. Re-run the failing check to confirm the fix
|
||||
4. Continue to the next check
|
||||
|
||||
**Retry limit:** Maximum 3 fix attempts per check. If a check still fails after 3 attempts:
|
||||
- Summarize what was tried and what the error is
|
||||
- Show the user the error output
|
||||
- Ask the user how to proceed (skip, manual fix, or abort)
|
||||
|
||||
**What NOT to fix in this step:**
|
||||
- Pre-existing lint warnings (ruff I001, E402, etc.) — only fix lint errors in new code
|
||||
- Pre-existing test failures — only new failures caused by this phase
|
||||
|
||||
### Step 7: Update the Roadmap (MANDATORY)
|
||||
|
||||
Mark the completed phase with a checkmark and replace its content with a compact summary using this template:
|
||||
|
||||
```markdown
|
||||
### Phase N: Title ✅
|
||||
|
||||
**Completed:** YYYY-MM-DD
|
||||
|
||||
**Summary:** [1-2 sentences describing what was built]
|
||||
|
||||
**Key files:**
|
||||
- `path/to/file.py` — [role]
|
||||
|
||||
**Endpoints created:** (if applicable)
|
||||
- `POST /resource` — [purpose]
|
||||
- `GET /resource/{id}` — [purpose]
|
||||
|
||||
**Key details:**
|
||||
- [Implementation decisions, enum values, constraints, patterns applied]
|
||||
- [Anything future phases need to know]
|
||||
```
|
||||
|
||||
Preserve enough detail that future phases can reference what was built without reading all the code.
|
||||
|
||||
## Red Flags — STOP If You Catch Yourself Thinking This
|
||||
|
||||
| Thought | Reality |
|
||||
|---------|---------|
|
||||
| "The requirements are clear, I'll skip questions" | Requirements always have ambiguity. Ask at least one round. |
|
||||
| "I'll update the roadmap later" | You'll forget. Update immediately after each phase. |
|
||||
| "I'll implement all phases first, then update" | Multi-phase ranges require update between each. One at a time. |
|
||||
| "The roadmap update is just bookkeeping" | Future phases depend on accurate roadmap state. It's not optional. |
|
||||
| "I already know the codebase patterns" | Read the referenced files anyway. Patterns evolve. |
|
||||
| "This phase is simple, no questions needed" | Simple phases still have scope and design decisions. Ask. |
|
||||
| "The brief is extra overhead, I'll just implement" | The brief IS the value — it forces you to crystallize decisions and gives the subagent clean context. |
|
||||
| "I can implement in the same context" | Exploration context pollutes implementation. Fresh context = fewer mistakes. |
|
||||
| "I don't need to compact, the brief is enough" | The brief helps the subagent. Compaction helps YOU — verification and roadmap updates need clean context too. |
|
||||
| "The subagent can just read the roadmap" | The roadmap has ambiguity — that's why you asked questions. The brief captures resolved decisions. |
|
||||
| "The subagent said it's done, must be fine" | Subagents don't always verify. Run the checks yourself. |
|
||||
| "It compiled so it works" | Import success != runtime success. Run tests and smoke checks. |
|
||||
| "I'll skip verification, it's a small phase" | Small phases cause NOT NULL violations and broken DI. Always verify. |
|
||||
| "The error is pre-existing, not my problem" | Confirm it's pre-existing before ignoring. Check git diff. |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Step | Required? | Key Action |
|
||||
|------|-----------|------------|
|
||||
| 1. Parse | Yes | Read full doc, identify target + dependencies |
|
||||
| 2. Explore | Yes | Read referenced code files |
|
||||
| 3. Ask | **MANDATORY** | At least one round of clarifying questions |
|
||||
| 4. Brief | **MANDATORY** | Write implementation brief to `/tmp/phase-N-brief.md` |
|
||||
| 4.5. Clear Context | **MANDATORY** | Run `/compact`, then re-read only the brief file |
|
||||
| 5. Implement | Yes | Dispatch subagent via Task tool with fresh context |
|
||||
| 6. Verify & Fix | **MANDATORY** | App loads + tests pass + smoke test; fix loop with 3 retries |
|
||||
| 7. Update | **MANDATORY** | Replace phase content with summary template |
|
||||
Reference in New Issue
Block a user