git:20260615.4c8d2a3 to git:20260616.41b2070

---

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 <module/path>`

### 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/<id>/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):

- 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."

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

```

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/<id>/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):

```

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

```

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

```

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

```

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

```

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

```

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

```

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(<track_id>): <task description> (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 <specific files>`

- Verify staged changes exist before committing: `git diff --cached --quiet`. If nothing staged, skip the commit step.

- `git commit -m "type(<track_id>): 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: <JIRA_ID>`.

- 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 <SHA>. 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:

```

"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 `(<sha>)`). Run:

```bash

git diff --name-only <first_sha>^..HEAD

```

That is the `files_touched` list. Derive `modules_touched` as the unique top-level path segments (e.g. `auth/login.go` → `auth`).

```bash

```

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 <track_id>`

- 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: <status>, metadata.json: <status>, tracks.md: <section>"

- Provide recovery: "Manually complete updates: [list specific edits needed]"

- Do NOT announce completion until all three files verified consistent

6. Announce:

"Track <track_id> completed!

Summary:

- Phases: N/N

- Tasks: M/M

- Duration: [if tracked]

[If review ran:]

Review: PASS | PASS WITH NOTES | FAIL

Report: draft/tracks/<track_id>/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:

```

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

```

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

```

"Track complete! Consider:

→ /draft:deploy-checklist — Pre-deployment verification"

```

**If track added new APIs/services/components:**

```

→ /draft:documentation — Update documentation for new components"

```

**If implementation contains TODO/FIXME/HACK comments:**

```

→ /draft:tech-debt — Catalog any new technical debt introduced"

```

**If new patterns or dependencies not in tech-stack.md:**

```

→ /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/<id>/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