Wf Spec Drift

Spec-Implementation Drift

Compare what a dispatched task actually built against what the spec asked for. This is the non-deterministic layer 2 of the task completion feedback loop — it goes beyond the mechanical status flip (layer 1) to assess whether the implementation truly satisfies the spec's intent.

Step 0: Parse arguments

$ARGUMENTS has the form: <spec-file.md> [commit-range]

• The first token is the spec file path.
• The optional second token is a git commit range (e.g., abc123..HEAD).

Step 1: Load the spec

1. Read the spec file in full. Parse YAML frontmatter — extract title, status, depends_on, affects, effort, dispatched_task_id.
2. Verify dispatched_task_id is non-null. If null, the spec was not dispatched. It may instead have been implemented directly in-session (no task UUID, but real commits on the affects files). In that case:
   • To finalize it (Outcome + status + README), use /wf-spec-wrapup, which is lifecycle-aware and reconstructs the Outcome from the git history of the affects files. That is the canonical Outcome writer for the direct path.
   • To only review the implementation against the spec (no Outcome write), use /wf-spec-review-impl, which works without a dispatch link.
   • You may still run this skill's divergence analysis on a direct-implement spec if the user passes an explicit [commit-range] (Step 2 then uses it instead of the task UUID) — but do not also write ## Outcome here if wrap-up already owns it (see Step 6).
3. Extract the acceptance criteria from the spec body:
   • Design specs: items from Options (chosen option), Components, Architecture
   • Task specs: items from "What to do", "Goal", "Tests"
   • Any numbered or bulleted requirements
4. If the spec is non-leaf, read child specs recursively and aggregate their criteria.

Step 2: Load the implementation

1. If a commit range was provided, use it directly.
2. Otherwise, infer the range: find commits associated with the dispatched task. Look for the task UUID in commit messages, or use the task's worktree diff via GET /api/tasks/{id}/diff where a task board exposes one; otherwise from git history over the spec's affects paths.
3. Get the diff: git diff <range> --stat for file list, git diff <range> for full changes.
4. Get commit messages: git log <range> --oneline.

Use Agent subagents (Explore type) to parallelize diff analysis across independent packages if the change spans many files.

Step 3: Classify each spec item

For every acceptance criterion or deliverable in the spec:

• Satisfied — the diff contains clear evidence of implementation. The code matches what the spec described (types, functions, behavior).
• Diverged — the item was addressed but the implementation differs from what the spec specified. Note what the spec said vs what was built and why the divergence may have occurred (common reasons: runtime constraints, API changes, simpler approach found).
• Not implemented — no evidence in the diff. The item was skipped or deferred.
• Superseded — the item was replaced by a different approach that achieves the same goal. Note the replacement.

For each classification, cite specific files, functions, and diff hunks as evidence.

Step 4: Identify unspecified work

Scan the diff for changes not traceable to any spec item:

• New files, types, or functions not mentioned in the spec
• Refactoring of existing code beyond what the spec required
• Test additions beyond what the spec's "Tests" section listed

Classify each as:

• Necessary scaffolding — required to make the spec work (e.g., imports, helper types, error handling)
• Improvement — reasonable enhancement discovered during implementation
• Scope creep — work that belongs in a different spec or wasn't requested

Step 5: Assess overall drift

Compute a drift summary:

• Satisfaction rate: N of M spec items satisfied (percentage)
• Divergence count: how many items were implemented differently
• Unimplemented count: how many items were skipped
• Unspecified count: how many changes weren't in the spec

Based on these numbers, determine the drift level:

• Minimal (>90% satisfied, ≤1 divergence) — spec is accurately complete
• Moderate (70-90% satisfied, or 2-3 divergences) — spec is mostly complete but the Outcome section should document the deviations
• Significant (<70% satisfied, or major divergences) — the spec should transition to stale rather than complete, as it no longer accurately describes what was built