Implement

implement — turn the task list into tested code

You have a spec, a plan, and an ordered task list (from specify → plan → tasks), and the analyze gate has cleared. This skill does the building: it walks the tasks in order, writes each one test-first, stops to show its work after every task, and records the decisions it makes along the way. It is the intent → shipped code engine's hands — verify is the gate that comes after, not part of this skill.

This is a process skill. It owns the discipline (red → green → refactor, checkpoints, decision logging, constitution adherence). It does not own the test tooling — pytest fixtures, go test table-drivers, Vitest/Playwright, flutter test — those belong to the stack skill, and you call into them rather than reinventing them.

Before you write a line of code

Run this short gate. Skipping it is the most common way an implement session goes sideways. This gate is a hard refuse, not a checklist to feel good about: if it fails you stop and route back — you do not write feature code anyway.

1. The spec + plan must exist AND be approved. Open the spec (02-DOCS/wiki/sdd/specs/<slug>.md), the plan (02-DOCS/wiki/sdd/plans/<slug>.md, which holds the task list), and the constitution (02-DOCS/wiki/sdd/constitution.md). If any is missing, you are not allowed to implement — route back: no spec → specify; no plan → plan; no task list inside the plan → tasks; unresolved analyze findings → resolve them first. If a spec/plan exists but the user has not actually seen and approved it, get that approval first. Never "start coding to discover the plan as you go", and never accept "just build it, skip the spec" on a non-trivial feature — name the gate in one friendly line and route to specify. (Only a true one-line, low-risk change earns a skip, and you say so.)
2. Read the SDD runtime config. Open 02-DOCS/wiki/sdd/config.yaml. If it is missing on non-trivial work, stop and route to sdd-init. Use testing.strict_tdd, testing.commands.apply, testing.commands.verify, sdd.review_budget and sdd.registry_path. Do not choose a different test command from memory while config exists.
3. Read the skill registry. Open .rsc/skill-registry.json if present. Select only the relevant stack/process skills for this task, then digest them into compact rules. If the registry is missing, run or recommend npx @ericrisco/rsc registry refresh and record the fallback.
4. Read the accompaniment dial. Open 02-DOCS/wiki/harness/user-profile.md and read the technical + accompaniment level. It sets how loud you are at each checkpoint (see the dial table below). No profile yet → assume non-technical, narrate more, and ask before any irreversible step.
5. Confirm isolation. Implementation happens on a feature branch or worktree, never directly on the default branch. If you are on main/master, stop and hand to worktrees before the first commit.
6. Scan the tasks for independence. Mark which tasks share files/state and which are disjoint. Disjoint clusters are candidates for parallel; everything else runs in order.

The loop — one task at a time

For each task in the list, in order (or dispatched per the parallel rule below):

RED      → write the smallest failing test that encodes the task's done-check. Run it. Watch it FAIL
           for the right reason (assertion, not import error). A test that was never red proves nothing.
GREEN    → write the least code that makes that test pass. No extra features, no "while I'm here".
           Run the test. Watch it PASS.
TRIANGULATE → add the smallest edge-case test that proves the behavior is not hard-coded
           (only when config.testing.strict_tdd is true and the task has meaningful edge cases).
REFACTOR → with the test green, clean up names/duplication/shape. Re-run; still green. Only now.
CHECK    → re-read the task's done-check. Met? Constitution still honored? Decision worth logging?
PROGRESS → append task/test/blocker/decision state to 02-DOCS/wiki/sdd/progress/<slug>.md.
COMMIT   → commit this task as one logical unit (authorship = Eric; see ship for the rule).
REVIEW   → dispatch a fresh reviewer subagent over THIS task's commits (see "Per-task review gate").
           Fold its Critical/Important findings back in before you move on; Minor can wait.
CHECKPOINT → stop and show: what changed, test output, review verdict, the next task. Wait per the dial.

The order is load-bearing. Red before green is not a suggestion — a test you write after the code tells you nothing about whether it can fail. Refactor only on green keeps every cleanup reversible against a passing bar. Checkpoint after each task is what makes this resumable and reviewable instead of a 2000-line surprise diff.

Four things you may never do to reach green

The loop only means anything if green cannot be manufactured. These are absolute, and each one is a way people reach green without fixing anything:

1. Never weaken a test to make it pass. Not broadening an assertion, not adding a skip, not raising a tolerance, not deleting it. A test that looks wrong is a spec conversation — surface it, don't bury it.
2. Never edit a test and the implementation in the same step to reach green. Change one, run, then the other. Simultaneous edits let you redefine correctness to match your bug without noticing you did it.
3. Never mock the unit under test, or mock so much that the test only exercises the mocks. Mock boundaries you don't own — network, clock, filesystem, third-party SDK — never the logic you are being paid to verify.
4. Never chase the coverage number. Coverage detects untested code; it is not a target. A test added to touch lines, with no meaningful assertion, is gaming — and mutation testing exists precisely to catch it (../testing-py/SKILL.md, ../testing-web/SKILL.md, ../testing-go/SKILL.md).

The done-check is the contract

Each task carries a done-check from the tasks phase ("returns 409 on duplicate email", "list renders empty state when zero items"). That sentence is your first failing test. Do not invent a looser check, and do not mark a task done because the code "looks right" — done means the done-check's test is green and the relevant acceptance criterion in the spec is satisfied.

Delegating the test tooling (do not reinvent it)

Write the intent of the test here; get the mechanics from the stack skill. The discipline is yours; the fixtures, runners and idioms are theirs.

If the feature spans two stacks (a Next.js front-end calling a FastAPI back-end), each task names its stack and pulls that stack's testing reference — you do not mix idioms inside one task.

Skill digestion and resolution

When a task or subagent needs skill context, use the registry path from config:

.rsc/skill-registry.json

Select the smallest set of skills that match the task. Digest each selected skill into 4-5 compact rules that affect this task. A task brief or checkpoint includes:

Selected skills: fastapi, postgresdb, implement
Compact rules:
- Use the configured apply command from config.yaml.
- Red test first; verify it fails for the right reason.
- Keep DB migrations expand-contract when touching production tables.
Skill resolution:
- used: [...]
- missing: [...]
- fallback: [...]

If a skill is referenced but unavailable, say so and record the fallback. Do not silently pretend it was used.

Apply progress

Maintain an append-only progress file:

02-DOCS/wiki/sdd/progress/<slug>.md

Entry shape:

## T004 — 2026-06-02
- status: complete
- red: `pytest tests/auth/test_login.py::test_bad_password_returns_401` failed for expected missing route
- green: same test passed
- triangulation: blank title returns 422
- files: app/auth.py, tests/auth/test_login.py
- decision: none
- blocker: none

This file is what makes resumes and archive reliable. Never rewrite old entries; append corrections as new entries.

Resume & recovery — trust the ledger, not memory

The progress file is the source of truth across compaction and restarts:

• A task recorded status: complete here is DONE — never re-dispatch it. Re-running completed tasks (re-implementing, re-committing) is the single most expensive recovery failure: it rebuilds work that already exists and can clobber later commits.
• After a compaction or a fresh session, reconstruct state from this ledger + git log, not from memory. Read the progress entries and the commit history first; resume at the first task not marked complete. If the ledger and the working tree disagree, believe the tree and append a correction entry — do not silently re-run.

Running independent tasks in parallel

When two or more tasks are genuinely disjoint — no shared files, no shared state, no ordering dependency — fan them out with parallel rather than serializing. The rule of thumb:

• Serialize when a later task imports, edits, or asserts against an earlier task's output, or when they touch the same file.
• Parallelize when each task could be done by a different person who never talks to the others (e.g. "add the users repository" and "add the invoices repository" in separate modules).

Each parallel branch still runs its own full red → green → refactor loop and reports back its diff + test output. You merge the branches, then run the combined test suite before the next checkpoint — green-in-isolation is not green-together. Hand the orchestration to parallel; keep the TDD discipline inside each branch.

Dispatch implementation work to the developer subagent. rsc installs a developer agent pinned to the balanced tier (Sonnet by default, chosen at onboarding, never light). When you delegate a task or fan out via parallel, dispatch it to that agent (e.g. Claude Code subagent_type: developer) so the bulk of TDD execution runs on the cheaper-but-capable model while you stay on the session model to orchestrate. Full rationale: ../sdd/references/model-routing.md.

The dispatch contract (carriers, statuses, escalation)

A dispatched worker is context-isolated — it sees only what you hand it, not your session. Make each dispatch self-sufficient and make its return machine-checkable:

• Carry the task, not your context. Hand the worker its task brief, its Interfaces block (Consumes/Produces, exact signatures — from tasks), and the plan's §0 Global Constraints. Anything not in those three is invisible to it. Prefer file paths over pasted text (use scripts/task-brief and scripts/review-package, below) — pasted briefs and diffs stay resident in your context and get re-read every turn.
• Model is REQUIRED on every dispatch. Always set the subagent's model explicitly (the developer agent already pins balanced). An omitted model silently inherits the session's model — usually the most expensive one — which is the quiet way fan-out cost explodes.
• The worker reports one of four statuses (it does not guess when unsure):
  • DONE — done-check green, Produces contract met.
  • DONE_WITH_CONCERNS — green, but it flagged a risk/assumption for you to adjudicate.
  • BLOCKED — cannot proceed (failing dependency, contradiction, missing access). Stops; does not hack around it.
  • NEEDS_CONTEXT — a Consumes/constraint it needed was not in the brief. Stops; names what's missing.
• Never force the same model to retry unchanged. On BLOCKED/NEEDS_CONTEXT you must change something before re-dispatching: add the missing context/interface, fix the dependency, or escalate the tier (balanced → heavy) for a genuinely hard sub-problem. Re-running an identical prompt on an identical model is how a loop burns budget without progress.

Per-task review gate

After a task is committed and before its checkpoint, run a small, fresh-eyes review of that task alone — catching over-/under-building while it is one commit cheap to fix, instead of waiting for the whole-branch review when it is buried in a large diff. It is a mid-build gate, not the finish line (see the boundary below).

How to run it:

1. Package the diff as a file, not a paste. scripts/review-package <BASE> <HEAD> where BASE is the task's recorded base sha (never HEAD~1 — that drops every commit but the last of a multi-commit task). It writes the commit list + --stat + full diff to one file.
2. Dispatch a fresh reviewer subagent (context-isolated — it must NOT inherit your session reasoning). Hand it: the review-package path, the task's done-check, the task's Interfaces → Produces contract, and the plan's §0 Global Constraints. With routing on, balanced is the floor; escalate to heavy for a risky/security-touching task. The frozen brief lives in references/per-task-review.md.
3. It returns two verdicts in one pass: spec compliance (missing / extra / misunderstood vs the done-check + Produces) and code quality — every finding tagged severity (Critical/Important/Minor) with file:line evidence.
4. Fold Critical/Important back in now; Minor may wait for the end-of-branch review.

Anti-pre-judging (hard rule). The dispatch must never tell the reviewer what not to flag, pre-rate a finding's severity, or explain why a choice is fine ("the plan chose X, treat as Minor"). A stated rationale never downgrades a finding — that is laundering your own bias through the reviewer. Hand it the evidence and the contract; let it judge.

Boundary — this does not replace the end gates. verify still runs the whole suite and the acceptance criteria once at the end, and review still reads the whole diff adversarially once before ship. The per-task gate is the cheap early pass; the broad reviews remain. Skip the per-task gate on a genuinely trivial task (a one-line change), like the rest of the chain.

Model tier — balanced (opt-in routing)

This phase's default model tier is balanced — it is the bulk of TDD execution: cost-sensitive, with quality balanced handles well. Routing is off unless models.enabled: true in 02-DOCS/wiki/sdd/config.yaml. When on: resolve this phase's tier (models.overrides wins over models.phases), map it to a model via models.tiers, and apply per ../sdd/references/model-routing.md — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any Task/parallel subagents on that model (this is where routing pays off most — fan-out runs on balanced while a hard sub-problem can be escalated to heavy). Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.

The accompaniment dial — how loud at each checkpoint

Read the level from 02-DOCS/wiki/harness/user-profile.md and match it. Same work, different volume.

The dial changes verbosity and question count — it never changes the engineering. TDD, the done-checks, the constitution and decision logging hold at every level, including L0.

Logging decisions (the 02-DOCS trail)

When you make a choice the plan did not fully specify — a library, a data shape, an error contract, a deviation from the plan — append it to 02-DOCS/wiki/sdd/decisions.md (append-only; create it if absent and index it in 02-DOCS/wiki/index.md (the Knowledge map; root CLAUDE.md keeps only a short pointer) under the sdd/ topic). One entry:

## YYYY-MM-DD — <short title>  (feature: <slug>, task: <n>)
Context   — what forced the choice
Options    — the 2–3 real alternatives weighed
Decision   — what you chose
Why        — the trade-off that decided it

Log the non-obvious ones — the choices a reviewer would otherwise have to reverse-engineer from the diff. Do not log "named the variable count". If a decision contradicts the constitution, you do not get to log your way around it: stop (see red flags).

Staying inside the constitution

02-DOCS/wiki/sdd/constitution.md holds the project's non-negotiables (stack canon, quality bars, naming, security posture). Every task you implement must honor it. If a task can only be done by breaking a constitutional rule, that is a contradiction the analyze phase should have caught — surface it and stop; do not quietly violate the constitution to make a test pass. The constitution outranks the plan, and the plan outranks your in-the-moment preference.

Anti-patterns → STOP

Red flags — stop and re-route

• No plan or no task list → you cannot implement intent you haven't planned. Route to plan / tasks.
• Unresolved analyze findings (contradiction between constitution ↔ spec ↔ plan ↔ tasks) → resolve them before any code; they will only get more expensive after the diff exists.
• A task forces a constitution violation → surface it, stop, kick it back to analyze/plan.
• You're on the default branch → stop before the first commit; hand to worktrees.
• A test won't go red (wrong reason — import error, syntax) → fix the test before trusting it.
• The combined suite is red after a parallel merge → do not checkpoint as done; debug with debug before continuing.
• You're tempted to disable/skip a failing test to "make progress" → that's the bug talking. Diagnose with debug; never ship around a red test.

Checklist (copy per task)

- [ ] Read the task's done-check; it is my first test's assertion
- [ ] RED: smallest test written, run, fails for the RIGHT reason
- [ ] GREEN: least code to pass; test now green
- [ ] REFACTOR: cleaned up on green; still green
- [ ] Constitution honored; no banned pattern introduced
- [ ] Non-obvious decision (if any) logged to 02-DOCS/wiki/sdd/decisions.md
- [ ] Apply progress appended to 02-DOCS/wiki/sdd/progress/<slug>.md
- [ ] Skill resolution recorded (used/missing/fallback/compact rules)
- [ ] Committed as one logical unit (authorship = Eric)
- [ ] Checkpoint shown at the dial's level; next task named

Result envelope

End every implementation checkpoint or completed batch with:

{
  "status": "complete",
  "executive_summary": "Implemented task(s) with red/green/triangulate/refactor evidence.",
  "artifact": "02-DOCS/wiki/sdd/progress/<slug>.md",
  "next_recommended": "implement|verify",
  "risk": "low|medium|high",
  "skill_resolution": {
    "used": ["implement"],
    "missing": [],
    "fallback": [],
    "compact_rules": ["Use config testing commands.", "Append progress after every task."]
  },
  "evidence": ["red test output", "green test output", "progress entry path"]
}

What this skill is NOT

• Not the lint/type/audit gate. Per-task tests prove the task; the whole-suite run plus lint/type/security audit and acceptance-criteria sign-off is verify's job. Don't claim the feature is done here — that claim belongs to verify, on evidence.
• Not spec or plan writing. If you find the plan is wrong mid-build, stop and amend it via plan; don't silently re-architect inside a commit.
• Not the deep-debug protocol. When a test fails for a reason you don't understand, switch to debug (reproduce → isolate → hypothesize → fix → verify) instead of guessing.

Where you are in the chain

constitution → specify → clarify → plan → tasks → analyze → implement → verify → review → ship. On-demand from here: debug (a test fails mysteriously), worktrees (need isolation), parallel (independent tasks to fan out).

Next: when every task's done-check is green and committed, go to verify — run the stack skill's scripts/verify.sh, confirm the spec's acceptance criteria, and let evidence (not assertion) declare the feature done.

Orientación (siempre)

Cierra cada turno con el bloque-brújula (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de 02-DOCS/wiki/harness/user-profile.md. Nunca termines en seco. Protocolo completo: skill orient → skills/orient/references/orientation-contract.md. (Defiere a suggest el "¿instalo la skill que falta?".)