Task: Reconcile SPEC and Top-Level Design with Implementation

Task: Reconcile SPEC and Top-Level Design with Implementation

Objective

Produce a RECONCILIATION.md that records every discrepancy between a unit's SPEC.md and what was actually built — and apply the resulting edits directly. The output document is an audit log; the side outputs are surgical edits to units/<area>/u<NN>/SPEC.md, edits to top-level design artifacts at the project root where discoveries qualify as general truth about the system (DOMAIN.md, ARCHITECTURE.md, INTERFACES.md, DATA.md, BEHAVIOR.md, ERRORS.md, QUALITY.md, SECURITY.md, OPERATIONS.md, USE_CASES.md, surface IAs), and frontmatter-only edits to the trigger artifact(s) (roadmap/<NNN>-<slug>/ROADMAP.md or issues/<NNN>-<slug>/ISSUE.md — status transitions and promoted_to_units) plus any peer units this unit's SPEC declares supersedes (superseded_by reciprocity). The defining test of "done" is the user's stated criterion: if the implementation were deleted and the pipeline re-run from the updated SPEC, the implementation would be reproducible without surprises. Updated SPEC + updated top-level docs = sufficient design context. If after reconcile a fresh implementation would still hit the same surprises, the reconcile was incomplete.

This skill is the most destructive in the pipeline. It rewrites design documents that every future unit will read. Get it wrong and the design suite drifts into an implementation snapshot — the opposite of design. Get it right and the design suite stays trustworthy after every implementation cycle.

Inputs

1. SPEC.md (required, primary subject) — units/<area>/u<NN>/SPEC.md. The unit's spec, which will be edited in place.
2. IMPLEMENTATION.md (required) — units/<area>/u<NN>/IMPLEMENTATION.md. The build report. Authoritative source for what was actually built and why deviations from the plan occurred.
3. CODE_REVIEW.md (required, all rounds) — units/<area>/u<NN>/CODE_REVIEW.md plus CODE_REVIEW_R2.md, CODE_REVIEW_R3.md if present. Findings and their resolution status.
4. VERIFICATION.md (required) — units/<area>/u<NN>/VERIFICATION.md. Acceptance evidence. Source for confirmed behavior.
5. Trigger artifact(s) (required) — roadmap/<NNN>-<slug>/ROADMAP.md and/or issues/<NNN>-<slug>/ISSUE.md named in the unit's SPEC frontmatter trigger.roadmap / trigger.issues. Used for scope boundaries and acceptance criteria. The trigger frontmatter (status, promoted_to_units) is updated as part of reconcile's side outputs.
6. Implementation source code (required, accessed via codebase read tools) — the actual files listed in the SPEC's File Manifest. The ultimate source of truth for what exists. Read every file the SPEC claims this unit owns; spot-check internals where IMPLEMENTATION.md or CODE_REVIEW.md hint at deviations.
7. Top-level design artifacts (required, accessed selectively) — DOMAIN.md, ARCHITECTURE.md, INTERFACES.md, DATA.md, BEHAVIOR.md, ERRORS.md, QUALITY.md, SECURITY.md, OPERATIONS.md, USE_CASES.md, surface IAs. Read on demand based on what the unit touched. The unit's "Design References" subsection in SPEC.md § 1 names the candidate artifacts.
8. Dependency unit SPECs and dependent unit SPECs (required, auto-discovered) — units/<area>/u<MM>/SPEC.md for every unit named in this unit's dependency list and every unit that lists this unit as a dependency. Read to verify scope-leak classifications (so a discovery isn't silently absorbed into this unit's SPEC when it actually belongs to a sibling).

Read-set size: 4–5 per-unit artifacts + 1–2 trigger artifacts + 0–4 top-level artifacts (only those the unit touched) + dependency SPECs as needed. Within the ADD read-set budget.

Workflow

Reconciliation runs as a single agent in four phases. Do not dispatch subagents at any point. Every read, every classification, every edit is performed by this agent directly.

Phase 1 — Gather and Classify (Discrepancy Discovery)

Read all required inputs end-to-end before classifying anything. The order:

1. SPEC.md (cover to cover — every section, every constant, every signature).
2. IMPLEMENTATION.md (especially "Deviations from Plan" and "Notes for Downstream Work").
3. CODE_REVIEW.md and any later rounds (focus on findings that were resolved by changing the code rather than fixing the spec).
4. VERIFICATION.md (any scenario whose "actual" diverged from "expected" but was deemed acceptable is a discrepancy).
5. The trigger artifact(s) and the unit's frontmatter (depends_on, supersedes, related) plus the SPECs of related units the orchestrator supplied or that the unit references.
6. Source files listed in the SPEC's File Manifest.