--- name: implement description: "Canonical implementation parent command. Executes the active track task-by-task using TDD and verification gates, and routes to status, coverage, or revert when the user asks for progress, measurement, or rollback explicitly." --- # Implement Track Implement tasks from the active track's plan following the TDD workflow. `/draft:implement` is the **canonical implementation parent**. It owns the common execution loop and absorbs three adjacent commands when appropriate: - `/draft:status` - `/draft:coverage` - `/draft:revert` ## Red Flags - STOP if you're - Implementing without an approved spec and plan - Skipping TDD cycle when workflow.md has TDD enabled - Marking a task `[x]` without fresh verification evidence - Batching multiple tasks into a single commit - Proceeding past a phase boundary without running the three-stage review - Writing production code before a failing test (when TDD is strict) - Assuming a test passes without actually running it **Verify before you mark complete. One task, one commit.** ## Constraints Draft skills are designed for single-agent, single-track execution. Do not run multiple Draft commands concurrently on the same track. --- ## Parent Contract `/draft:implement` owns four execution jobs: 1. **Build the next task** → baseline `/draft:implement` 2. **Show current execution state** → `/draft:status` 3. **Measure implementation completeness via coverage** → `/draft:coverage` 4. **Undo implementation safely** → `/draft:revert` Most developers should only need `/draft:implement` in the common path. ### Explicit Child Modes If the user invokes explicit child intent, route directly: - `/draft:implement status` → follow `/draft:status` - `/draft:implement coverage` → follow `/draft:coverage` - `/draft:implement revert` → follow `/draft:revert` Examples: - `/draft:implement status` - `/draft:implement coverage src/auth` - `/draft:implement revert phase 2` Explicit child mode always wins over the baseline implementation workflow. ### Bare `/draft:implement` Without an explicit child mode, `/draft:implement` should: - continue the active track's next task - surface blocked-task conditions immediately - run review and verification gates at phase boundaries - suggest or attach coverage only when the implementation state justifies it Do not make the user remember `status` or `coverage` in the happy path just to continue safe execution. --- ## Step 0: Route Explicit Child Modes Before loading implementation context, check whether the request is really: - progress inspection - coverage measurement - rollback / undo ### Route to `/draft:status` Route when the user asks: - `status` - `progress` - `what's left` - `where am I` ### Route to `/draft:coverage` Route when the user asks: - `coverage` - `measure tests` - `how much is covered` - `coverage for ` ### Route to `/draft:revert` Route when the user asks: - `revert` - `undo` - `roll back` - `revert task` - `revert phase` - `revert track` If one of these applies, route directly to the specialist workflow and stop this baseline implementation flow. --- ## Step 1: Load Context 1. Find active track from `draft/tracks.md` (look for `[~] In Progress` or first `[ ]` track) 2. Read the track's `spec.md` for requirements 3. Read the track's `plan.md` for task list 4. Read `draft/workflow.md` for TDD and commit preferences 5. Read `draft/tech-stack.md` for technical context 6. Read `draft/guardrails.md` (if exists) for hard guardrails and learned conventions 7. **Check for architecture context:** - Project-level: `draft/.ai-context.md` (preferred) or `draft/architecture.md` (graph-primary) - Track-level design docs: `draft/tracks//hld.md` (+ `lld.md` when present) - If relevant design context exists → **Enable architecture mode** (Story, Execution State, Skeletons) - If neither exists → Standard TDD workflow 8. **Load production invariants** (if `draft/.ai-context.md` exists): - Read the `## INVARIANTS` section (and `## CONCURRENCY` if present) - Identify which invariants reference files this task will modify (same file or same module) - Keep matching invariants as **active constraints** for this task — these govern code generation, not just review - If invariants reference lock ordering, fail-closed behavior, or data integrity rules: these are non-negotiable during implementation 9. **Load graph context** (if `draft/graph/schema.yaml` exists): First resolve the bundled helpers: ```bash # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT} # is not exported into skill Bash). See core/shared/tool-resolver.md. DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools" ``` - Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — check if any files this task will modify appear as hotspots - If modifying a hotspot file (high fanIn), warn: "This task modifies {file} (fanIn={N}). Changes here affect many downstream files. Consider running a graph impact query." - Query `"$DRAFT_TOOLS/graph-impact.sh"`/`"$DRAFT_TOOLS/graph-callers.sh"` for the module(s) being modified — gives file-level dependency context - See `core/shared/graph-query.md` for on-demand query subroutines (callers, impact) 10. Update the track's entry in `draft/tracks.md` from `[ ]` to `[~]` In Progress If no active track found: - Tell user: "No active track found. Run `/draft:plan` to create or resume planned work." **Architecture / Design Mode Activation:** - Automatically enabled when `.ai-context.md`, graph-primary `architecture.md`, or track `hld.md`/`lld.md` exists. - Project-level context from `/draft:init`. - Track-level design docs from `/draft:decompose`. ## Step 1.5: Readiness Gate (Fresh Start Only) **Skip if:** Any task in `plan.md` is already `[x]` — the track is in progress, this check has already passed. Run once, before the first task of a new track: ### AC Coverage Check For each acceptance criterion in `spec.md`: - Verify at least one task in `plan.md` references or addresses it - If an AC has no corresponding task, flag it: "⚠️ AC: '[criterion]' has no task in plan.md" ### Sync Check (if `.ai-context.md` exists) Compare the `synced_to_commit` values in the YAML frontmatter of `spec.md` and `plan.md`. - **Skip if** either file has no YAML frontmatter or no `synced_to_commit` field (quick-mode tracks omit it). - If they differ: "⚠️ Spec and plan were synced to different commits — verify they are still aligned." ### Result **Issues found:** List them, then ask: ```text Readiness issues found (see above). Proceed anyway or update first? [proceed/update] ``` - `proceed` → add a `## Notes` entry in `plan.md` listing the issues, then continue to Step 2 - `update` → stop here and let the user refine spec or plan before re-running **No issues:** Print `Readiness check passed.` and continue to Step 2. ## Step 1.7: Testing Strategy Loading Before starting TDD cycle for the first task: 1. Check for testing strategy: - Track-level: `draft/tracks//testing-strategy.md` - Project-level: `draft/testing-strategy.md` or `draft/testing-strategy-latest.md` 2. If found: load coverage targets, test boundaries, and strategy into TDD context 3. If not found and TDD is enabled: suggest "Run `/draft:testing-strategy` to define test approach" ### Bug Track Test Guardrail If track type is `bugfix` (from metadata.json): ```text BEFORE writing any test file: ASK: "This is a bug fix track. Want me to write tests as part of the fix? [Y/n]" If declined: skip TDD cycle, note in plan.md: "Tests: developer-handled" ``` ## Step 2: Find Next Task Scan `plan.md` for the first uncompleted task: - `[ ]` = Pending (pick this one) - `[~]` = In Progress (resume this one) - `[x]` = Completed (skip) - `[!]` = Blocked (skip - requires manual intervention) **IMPORTANT:** If blocked task found, notify user: - "Task [task description] is marked `[!]` Blocked" - Show the blocked task details and recovery message - "Resolve the blockage manually before continuing implementation" - Do NOT attempt to implement blocked tasks If resuming `[~]` task, check for partial work. ### Implementation-State Escalations After choosing the next task, check whether baseline implementation should remain in build mode or whether it should surface another execution helper. #### Escalate to Status-Style Summary If the track has: - many blocked tasks - no obvious next runnable task - conflicting in-progress markers then present a concise status summary before proceeding so the user can see the execution state clearly. This does **not** require fully routing to `/draft:status`; it is an implementation-owned checkpoint. #### Escalate to Coverage Guidance If the implementation is at one of these points: - phase just completed - track just completed - high-risk module just changed and tests exist but coverage is unknown then `/draft:implement` should suggest coverage or auto-attach it when the workflow and user intent imply measurement is expected. Examples: ```text Implementation checkpoint: - Phase 2 is complete - Next recommended action: /draft:implement coverage - Reason: high-risk auth code changed and coverage has not been measured for this phase ``` #### Escalate to Revert Guidance If the selected task is blocked because earlier implementation appears invalid, conflicting, or partially reverted, `/draft:implement` should recommend `/draft:implement revert` explicitly rather than pushing forward blindly. ## Step 2.5: Write Story (Architecture Mode Only) **Activation:** Only runs when `.ai-context.md`, graph-primary `architecture.md`, or track `hld.md`/`lld.md` exists. When the next task involves creating or substantially modifying a code file: 1. **Check if file already has a Story comment** - If yes, skip this step 2. **Skip for trivial tasks** - Config files, type definitions, simple one-liners 3. **Write a natural-language algorithm description** as a comment block at the top of the target file ### Story Format ```text // Story: [Module/File Name] // // Input: [what this module/function receives] // Process: // 1. [first algorithmic step] // 2. [second algorithmic step] // 3. [third algorithmic step] // Output: [what this module/function produces] // // Dependencies: [what this module relies on] // Side effects: [any mutations, I/O, or external calls] ``` Adapt comment syntax to the language (`#` for Python, `/* */` for CSS, etc.). ### CHECKPOINT (MANDATORY) **STOP.** Present the Story to the developer for review. - Developer may refine, modify, or rewrite the Story - **Do NOT proceed to execution state or implementation until Story is approved** - Developer can say "skip" to bypass this checkpoint for the current task See `core/agents/architect.md` for story writing guidelines. --- ## Step 3: Execute Task ### Step 3.0: Design Before Code (Architecture Mode Only) **Activation:** Only runs when `.ai-context.md`, graph-primary `architecture.md`, or track `hld.md`/`lld.md` exists. **Skip for trivial tasks** - Config updates, type-only changes, single-function tasks where the design is obvious. #### 3.0a. Execution State Design Study the control flow for the task and propose intermediate state variables: 1. Read the Story (from Step 2.5) to understand the Input -> Output path 2. Study similar patterns in the existing codebase 3. **Check `.ai-context.md` Data Lifecycle** — Align execution state with documented state machines (valid states/transitions), storage topology (which tier data targets), and data transformation chain (shape changes at boundaries) 4. **Check `.ai-context.md` Critical Paths** — Identify where this task sits in documented write/read/async paths. Note consistency boundaries and failure recovery expectations. 5. Propose execution state: input state, intermediate state, output state, error state Present in this format: ```text EXECUTION STATE: [Task/Module Name] ───────────────────────────────────────────────────────── Input State: - variableName: Type — purpose Intermediate State: - variableName: Type — purpose Output State: - variableName: Type — purpose Error State: - variableName: Type — purpose ``` **CHECKPOINT (MANDATORY):** Present execution state to developer. Wait for approval. Developer may add, remove, or modify state variables. Developer can say "skip" to bypass. #### 3.0b. Function Skeleton Generation Generate function/method stubs based on the approved execution state: 1. Create stubs with complete signatures (all parameters, return types) 2. Include a one-line docstring describing purpose and when it's called 3. No implementation bodies — use `// TODO`, `pass`, `unimplemented!()`, etc. 4. Order functions to match control flow sequence 5. Follow naming conventions from `tech-stack.md` **CHECKPOINT (MANDATORY):** Present skeletons to developer. Wait for approval. Developer may rename functions, change signatures, add/remove methods. Developer can say "skip" to bypass. See `core/agents/architect.md` for execution state and skeleton guidelines. --- ### Step 3.0c: Production Robustness Patterns (REQUIRED) **Applies to all code generation** — architecture mode or not. These patterns are generation directives, not a post-hoc checklist. Apply them **while writing code**, not after. When your implementation hits any of these triggers, use the corresponding pattern. Do not write code that violates these and plan to "fix it later." #### Atomicity | Trigger | Required Pattern | |---------|-----------------| | Multi-step state mutation (DB + memory, multiple records) | Wrap in transaction or try/finally with rollback on failure | | File write | Write to temp file + atomic rename to target path. Never write directly to the target. | | DB write paired with in-memory state update | DB-first: persist to DB, update memory only on DB success. Never update memory optimistically. | | Resource acquisition (locks, file handles, connections, capital) | Release in `finally` / `defer` / RAII — never rely on happy-path-only cleanup | #### Isolation | Trigger | Required Pattern | |---------|-----------------| | Method mutates shared/instance state | Acquire the class's or module's existing lock before mutation | | Lifecycle operations (start/stop/reset/reconnect) | Use a dedicated lifecycle lock, separate from data locks | | Returning internal state to callers | Return a deep copy or frozen snapshot — never a mutable reference to internal state | | Acquiring a second lock while holding one | Follow documented lock ordering. If no ordering exists, do not nest locks — restructure to acquire sequentially. | | DB I/O while holding a state lock | Move DB I/O outside the lock scope. Lock only the in-memory mutation, not the I/O. | #### Durability | Trigger | Required Pattern | |---------|-----------------| | Critical state that must survive crashes | Ensure state is recoverable from DB/disk alone — no reliance on in-memory-only state for recovery | | Async DB write (fire-and-forget) | Await the write. Check return value or propagate exceptions. No fire-and-forget on data persistence. | | Event log / audit trail / fill history | Use append-only pattern where specified by architecture | #### Defensive Boundaries | Trigger | Required Pattern | |---------|-----------------| | External numeric data used in arithmetic | Guard with `isFinite()` / `isnan()` / equivalent before any calculation | | External API/webhook response consumed | Validate expected fields exist and have correct types before accessing nested properties | | SQL query with dynamic values | Parameterized queries only — zero string interpolation for values | | Dynamic column names, table names, or identifiers in SQL | Validate against an explicit allowlist — never pass user-controlled strings as identifiers | #### Idempotency | Trigger | Required Pattern | |---------|-----------------| | Operation that may be retried (network calls, queue consumers, webhook handlers) | Use a dedup key (UUID, request ID, fill ID) — check-before-write or upsert | | State transition (status changes, lifecycle events) | Validate the transition is legal from the current state. Reject terminal→terminal transitions. | | Alert / notification emission | Dedup on (alert_type, entity_id, time_window) to prevent re-firing on retries | #### Fail-Closed | Trigger | Required Pattern | |---------|-----------------| | Error path or exception handler that determines access/action | Default to the safe/restrictive/deny state — never default to permissive on error | | Missing data, null, or undefined where a decision depends on it | Treat as deny/reject/skip — not as allow/proceed | | Config or feature flag missing/unparseable | Use the restrictive default — system runs in safe mode, not open mode | #### Resilience | Trigger | Required Pattern | |---------|-----------------| | Any retry logic | Exponential backoff with jitter — never fixed-interval or immediate retries. Prevents retry storms. | | Cache population under high concurrency | Cache stampede prevention: use probabilistic early expiration or request coalescing to prevent thundering herd | | External dependency call (HTTP, RPC, DB to external service) | Circuit breaker pattern: track failure rate, open circuit on threshold, allow periodic probes to recover | | Non-critical dependency failure | Graceful degradation: return cached/default/partial result rather than failing the entire request | **Enforcement:** These patterns override convenience. If following a pattern makes the code more verbose, that's correct — the verbosity is the safety. If a pattern is genuinely N/A for the current task (e.g., no DB in a pure utility function), skip it — only apply relevant patterns. **If project invariants were loaded in Step 1:** Cross-reference them here. Project-specific invariants (lock ordering, concurrency model, consistency boundaries) take precedence over these general patterns when they conflict. --- ### Step 3.1: Implement (TDD Workflow) For each task, follow this workflow based on `workflow.md`. If skeletons were generated in Step 3.0b, fill them in using the TDD cycle below. ### Characterization Testing (Refactoring Existing Code Without Tests) When refactoring code that lacks tests, write characterization tests first to capture current behavior as a baseline. Identify seams (interfaces for test doubles, swappable imports), record actual outputs for representative inputs, then proceed with the TDD cycle for new behavior. ### If TDD Enabled **Iron Law:** No production code without a failing test first. **3a. RED - Write Failing Test** ```text 1. Create/update test file as specified in task 2. Write test that captures the requirement 3. RUN test - VERIFY it FAILS (not syntax error, actual assertion failure) 4. Show test output with failure 5. Announce: "Test failing as expected: [failure message]" ``` **Test Quality Checklist (REQUIRED for every test):** - No shared mutable state between test cases — each test sets up its own state - Assertion density: every test must have at least one meaningful assertion (not just `assertTrue(true)`) - No logic in tests: no conditionals, loops, or try/catch in test code — tests should be trivially readable - DAMP over DRY: prefer descriptive and meaningful test names and setup over deduplication - Test behavior, not implementation: verify observable outcomes, not internal method calls - One behavior per test: each test should verify exactly one logical behavior - Reference: Google SWE Book Ch. 12, Google Testing Blog "Test Behavior, Not Implementation" **Property-Based Testing Checkpoint:** After writing example-based tests, consider property-based tests for pure functions (algebraic properties, round-trip serialization, sort invariants). Not mandatory — skip if properties are not obvious. **3b. GREEN - Implement Minimum Code** ```text 1. Write MINIMUM code to make test pass (no extras) 2. RUN test - VERIFY it PASSES 3. Show test output with pass 4. Announce: "Test passing: [evidence]" ``` **Observability Prompts (consider during implementation):** Structured logging at decision points, metrics for latency-sensitive ops, tracing at service boundaries, error classification (transient vs permanent). Use engineering judgment — not mandatory for every task. **Contract Testing Checkpoint (Service Boundaries Only):** For new API endpoints or service-to-service interfaces, suggest consumer-driven contract tests. Skip for purely internal modules. **3c. REFACTOR - Clean with Tests Green** ```text 1. Review code for improvements 2. Refactor while keeping tests green 3. RUN all related tests after each change 4. Show final test output 5. Announce: "Refactoring complete, all tests passing: [evidence]" ``` **Red Flags - STOP and restart the cycle if:** - About to write code before test exists - Test passes immediately (testing wrong thing) - Thinking "just this once" or "too simple to test" - Running tests mentally instead of actually executing ### If TDD Not Enabled **3a. Implement** ```text 1. Implement the task as specified 2. Test manually or run existing tests 3. Announce: "Implementation complete" ``` ### Implementation Chunk Limit (Architecture Mode Only) **Activation:** Only when `.ai-context.md` or `architecture.md` exists (track-level or project-level). If the implementation diff for a task exceeds **~200 lines**: 1. **STOP** after ~200 lines of implementation 2. Present the chunk for developer review 3. **CHECKPOINT (MANDATORY):** Wait for developer approval of the chunk 4. Commit the approved chunk: `feat(): (chunk N)` 5. Continue with the next chunk 6. Repeat until the task is fully implemented This prevents large, unreviewable code drops. Each chunk should be a coherent, reviewable unit. --- ## Step 4: Update Progress & Commit **Iron Law:** Every completed task gets its own commit. No batching. No skipping. After completing each task: 0. **Quick robustness scan** (30-second check before committing): - Scan the code you just wrote against the Step 3.0c triggers - If any trigger is present but the pattern wasn't applied: fix it now - This is a rapid pattern-match, not a full review — you should have applied these during generation, this catches anything missed 1. Commit FIRST (REQUIRED - non-negotiable): - Stage only files changed by this task (never `git add .`) - `git add ` - Verify staged changes exist before committing: `git diff --cached --quiet`. If nothing staged, skip the commit step. - `git commit -m "type(): task description"` (Conventional Commits — see `core/shared/vcs-commands.md`) - If a Jira ticket is linked in `spec.md`, reference it in the commit body: `Refs: `. - Get commit SHA: `git rev-parse --short HEAD` - Do NOT proceed to the next task without committing - Do NOT batch multiple tasks into one commit 2. Update `plan.md`: - Change `[ ]` to `[x]` for the completed task - Add the commit SHA next to the task: `[x] Task description (abc1234)` 3. Update `metadata.json`: - Increment `tasks.completed` - Update `updated` timestamp 4. **Verify state updates (CRITICAL):** - Read back `plan.md` - confirm task marked `[x]` with SHA - Read back `metadata.json` - confirm `tasks.completed` incremented - If EITHER verification fails: - Mark task as `[!]` Blocked in plan.md - Add recovery message: "State update failed after commit . Recovery: manually edit plan.md line X to mark `[x]`, update metadata.json tasks.completed to Y" - HALT - require manual intervention before continuing 5. If `.ai-context.md` or graph-primary `architecture.md` (or track hld/lld) exists: - Update module status markers where applicable. - Fill in Story placeholders with the approved story from Step 2.5 - If updating project-level `draft/.ai-context.md`: also update YAML frontmatter and run the Condensation Subroutine to keep it in sync. ## Verification Gate (REQUIRED) **Iron Law:** No completion claims without fresh verification evidence. Before marking ANY task/phase/track complete: 1. **IDENTIFY:** What command proves this claim? (test, build, lint) 2. **RUN:** Execute the FULL command (fresh, complete run) 3. **READ:** Full output, check exit code 4. **VERIFY:** Does output confirm the claim? - If **NO**: Keep task as `[~]`, state actual status - If **YES**: Show evidence, then mark `[x]` **Red Flags - STOP if you're thinking:** - "Should pass", "probably works" - Satisfaction before running verification - About to mark `[x]` without fresh evidence from this session - "I already tested earlier" - "This is a simple change, no need to verify" --- ## Step 5: Phase Boundary Check When all tasks in a phase are `[x]`: 1. Announce: "Phase N complete. Running three-stage review." ### Three-Stage Review (REQUIRED) **Stage 1: Automated Validation** - Fast static checks: architecture conformance, dead code, circular dependencies, performance anti-patterns. Review for common security anti-patterns (OWASP top 10). For automated checks, use language-specific tools (e.g., `npm audit` for JS, `bandit` for Python, `cargo audit` for Rust). - **If critical issues found:** List them, return to implementation **Stage 2: Spec Compliance** (only if Stage 1 passes) - Load track's `spec.md` - Verify all requirements for this phase are implemented - Check acceptance criteria coverage - **If gaps found:** List them, return to implementation **Stage 3: Code Quality** (only if Stage 2 passes) - Verify code follows project patterns (tech-stack.md) - Check error handling is appropriate - Verify tests cover real logic - Classify issues: Critical (must fix) > Important (should fix) > Minor (note) See `core/agents/reviewer.md` for detailed review process. ### Quick Review Alternative At phase boundaries, offer the lightweight alternative: ```text "Phase {N} complete. Review options: 1. Full three-stage review (recommended) — spec compliance + security + quality 2. /draft:quick-review — lightweight 4-dimension check (faster) Choose [1/2, default: 1]:" ``` If quick-review chosen, invoke `/draft:quick-review` with the phase's changed files. 2. Run verification steps from plan (tests, builds) 3. Present review findings to user 4. If review passes (no Critical issues): - Update phase status in plan - Update `metadata.json` phases.completed - **Refresh blast-radius memory** (see "Impact Memory" subsection below) - Proceed to next phase 5. If Critical/Important issues found: - Document issues in plan.md - Fix before proceeding (don't skip) ### Impact Memory (blast-radius snapshot) After a phase passes review, refresh `metadata.json.impact` so future tracks can detect overlap with this work. 1. **Compute touched files:** From `plan.md`, find the first commit SHA recorded for this track (earliest `[x]` line with `()`). Run: ```bash git diff --name-only ^..HEAD ``` That is the `files_touched` list. Derive `modules_touched` as the unique top-level path segments (e.g. `auth/login.go` → `auth`). 2. **Compute downstream blast radius (graph-aware, optional):** If `draft/graph/schema.yaml` exists, for each file in `files_touched` query (this runs in its own Bash session — re-resolve the helpers): ```bash DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools" "$DRAFT_TOOLS/graph-impact.sh" --repo . --file ``` Aggregate across all files: `downstream_files` = total unique downstream files (deduped), `downstream_modules` = union of `affected_modules`, `max_depth` = max across queries, `by_category` = sum of each query's `by_category`. If the graph is absent, leave these fields as zeros / empty arrays — the snapshot still records the directly-touched files. 3. **Write metadata.json** with the populated `impact` block and `computed_at` set to the current timestamp. This snapshot is consumed by `/draft:new-track` to surface overlap warnings when a new track touches the same modules as a recently completed track. ## Step 6: Track Completion When all phases complete: 1. **Run review (if enabled):** - Read `draft/workflow.md` review configuration - Check if auto-review enabled: ```markdown ## Review Settings - [x] Auto-review at track completion ``` - If enabled, run `/draft:review track ` - Check review results: - If block-on-failure enabled AND critical issues found → HALT, require fixes - Otherwise, document warnings and continue 2. Update `plan.md` status to `[x] Completed` 3. Update `metadata.json` status to `"completed"` 4. Update `draft/tracks.md`: - Move from Active to Completed section - Add completion date 5. **Verify completion state consistency (CRITICAL):** - Read back `plan.md` - confirm status `[x] Completed` - Read back `metadata.json` - confirm status `"completed"` - Read back `draft/tracks.md` - confirm track in Completed section with completion date - If ANY file shows inconsistent state: - ERROR: "Track completion partially failed" - Report: "plan.md: , metadata.json: , tracks.md:
" - Provide recovery: "Manually complete updates: [list specific edits needed]" - Do NOT announce completion until all three files verified consistent 6. Announce: "Track completed! Summary: - Phases: N/N - Tasks: M/M - Duration: [if tracked] [If review ran:] Review: PASS | PASS WITH NOTES | FAIL Report: draft/tracks//review-report-latest.md All acceptance criteria from spec.md should be verified. Next: Run `/draft:status` to see project overview." ## Error Handling **If blocked:** - Mark task as `[!]` Blocked - Add reason in plan.md - **REQUIRED:** Follow systematic debugging process (see `core/agents/debugger.md`) 1. **Investigate** - Read errors, reproduce, trace (NO fixes yet) 2. **Analyze** - Find similar working code, list differences 3. **Hypothesize** - Single hypothesis, smallest test 4. **Implement** - Regression test first, then fix - Do NOT attempt random fixes - Document root cause when found **Recommended:** Instead of inline debugging, invoke `/draft:debug` skill for a structured session: ```text "Task blocked: {description}. Run /draft:debug for structured investigation? [Y/n]" ``` The debug skill provides: Reproduce → Isolate → Diagnose → Fix methodology with debug report output. **If test fails unexpectedly:** - Don't mark complete - Follow systematic debugging process above - Announce failure details with root cause analysis - Show evidence when resolved **If unsure about implementation:** - Ask clarifying questions - Reference spec.md for requirements - Don't proceed with assumptions ## Tech Debt Log During implementation, track technical debt decisions in the track's plan.md: When you encounter a shortcut, workaround, or known-imperfect solution during implementation: 1. Add an entry to the `## Tech Debt` section at the bottom of plan.md 2. Use this format: ```markdown ## Tech Debt | ID | Location | Description | Severity | Payback Trigger | |----|----------|-------------|----------|-----------------| | TD-1 | `src/api/handler.ts:45` | Hardcoded timeout instead of config | Low | When adding config system | | TD-2 | `src/auth/session.ts:12` | In-memory session store | Medium | Before horizontal scaling | ``` **Severity levels:** - **Low** — Cosmetic or minor maintainability issue - **Medium** — Will cause problems at scale or in specific scenarios - **High** — Actively impeding development or risking production issues **Payback Trigger** — The condition or event that should trigger debt repayment (e.g., "before launch", "when adding feature X", "before scaling past N users"). Only log genuine debt — intentional shortcuts with known consequences. Not everything imperfect is debt. --- ## Progress Reporting After each task, report: ```yaml Task: [description] Status: Complete Phase Progress: N/M tasks Overall: X% complete ``` --- ## Cross-Skill Dispatch ### At Track Completion (Step 6) After announcing track completion, suggest relevant follow-ups based on context: **If track modifies production code:** ```text "Track complete! Consider: → /draft:deploy-checklist — Pre-deployment verification" ``` **If track added new APIs/services/components:** ```text → /draft:documentation — Update documentation for new components" ``` **If implementation contains TODO/FIXME/HACK comments:** ```text → /draft:tech-debt — Catalog any new technical debt introduced" ``` **If new patterns or dependencies not in tech-stack.md:** ```text → /draft:adr — Document this design decision" ``` ### Jira Sync at Completion If Jira ticket linked, sync via `core/shared/jira-sync.md`: - Post comment: "[draft] implementation-complete: All {n} tasks done. Ready for review." ### Bug Track with rca.md If implementing a bug track and `draft/tracks//rca.md` exists: - Load rca.md as context for the implementation - Reference root cause, blast radius, and prevention items during fix - After fix: update rca.md "Proposed Fix" section with actual fix details