Skip to main content
The reconcile skill compares existing SDD artifacts (requirements, specifications) against the current codebase to detect divergences. It classifies each divergence into one of six types, auto-resolves safe divergences, and asks the user for decisions on unsafe cases.

​
What it does

Compares specs to code

Compares existing SDD artifacts against the current codebase to detect divergences.

Classifies divergences

Classifies each divergence into one of 6 types using deterministic rules with clear evidence.

Auto-resolves safe cases

Automatically resolves new functionality, removed features, and refactoring by updating SDD artifacts.

Flags unsafe cases

Flags behavioral changes, potential bugs, and ambiguous cases for user decision.
The reconcile skill never modifies source code. It only updates SDD artifacts to match the code. Source code in src/ and tests/ is read-only and serves as the source of truth for current behavior.

​
Invocation modes

# Full reconciliation (default)
/sdd:reconcile

# Dry run — detect and classify only, do not apply changes
/sdd:reconcile --dry-run

# Scope to specific paths
/sdd:reconcile --scope=src/api,src/models

# Code wins — all divergences resolved toward code (no user prompts)
/sdd:reconcile --code-wins
ModeBehaviorUse Case
defaultClassify, auto-resolve safe types, ask user for unsafe typesNormal reconciliation
--dry-runClassify and report only, no modificationsAssessment before committing to changes
--scope=pathsOnly compare specified paths against their specsPartial reconciliation
--code-winsAll divergences resolved by updating specs to match codePost-release sync where code is authoritative

​
Eight phases

The reconcile skill executes eight phases to detect and resolve drift:

​
Phase 1: Context loading

Loads all SDD artifacts and establishes comparison baseline:
  • Verifies SDD artifacts exist: requirements/REQUIREMENTS.md, spec/ directory
  • Verifies source code exists: src/ or equivalent
  • Loads pipeline-state.json and checks for stale stages
  • Loads previous reconciliation/RECONCILIATION-REPORT.md for delta comparison
  • Parses all requirements: extracts REQ IDs, EARS statements, traceability references
  • Parses all specifications: use cases, workflows, API contracts, domain model, NFRs
  • Builds a spec artifact index
Reconcile requires both SDD artifacts and source code to exist. If SDD artifacts are missing, use /sdd:reverse-engineer to generate them first.

​
Phase 2: Code scan

Analyzes current code to build a feature inventory:
  • Scans all source files in scope
  • Extracts endpoints/routes with their handlers
  • Extracts entities/models with their fields
  • Extracts business logic: validations, state transitions, calculations
  • Scans test files to understand tested behavior
  • Builds a code feature index
  • Maps code features to spec artifacts via Refs: comments, naming conventions, and endpoint paths
Code intelligence enrichment (if SDD MCP server available):
  • Queries sdd_context for each artifact to get implementing symbols with callers/callees
  • Uses symbol table for precise line ranges and types
  • Uses call graph to distinguish behavioral change vs refactoring
  • Scales to any codebase size via structured MCP data

​
Phase 3: Spec-code comparison

Compares spec artifacts against code features to find divergences:
1

Find matching code

Uses the mapping from Phase 2 to locate code implementing each spec artifact.
2

Compare behavior

  • API contracts: method, path, params, request/response shape, status codes
  • Business rules: validation conditions, thresholds, error messages
  • State machines: states, transitions, guards
  • Domain model: entity fields, types, relationships, constraints
3

Detect divergences

  • Spec items without code (spec says it exists, code doesn’t have it)
  • Code without spec (code has it, spec doesn’t mention it)
  • Behavioral differences (both exist but behave differently)

​
Phase 4: Divergence classification

Classifies each divergence using deterministic rules:
TypeSignalResolution
NEW_FUNCTIONALITYCode exists without spec; has tests or is actively usedAuto: Update specs (code wins)
REMOVED_FEATURESpec exists without code; no recent commits touching itAuto: Deprecate in specs (code wins)
BEHAVIORAL_CHANGEBoth exist but behavior differsAsk user: Is code correct or is it a bug?
REFACTORINGStructure changed but behavior is equivalent (tests still pass)Auto: Update technical specs only
BUG_OR_DEFECTCode behavior contradicts spec AND tests fail or are missingAsk user: Fix code or update spec?
AMBIGUOUSCannot determine type with confidenceAsk user: Classify manually
Classification confidence:
  • HIGH: Clear match to one type based on signals
  • MEDIUM: Likely match but some counter-signals
  • LOW: Multiple types could apply → classify as AMBIGUOUS

​
Phase 5: Reconciliation plan

Builds the reconciliation plan before applying any changes:
  • NEW_FUNCTIONALITY: Draft new requirements (EARS syntax) and spec entries
  • REMOVED_FEATURE: Mark specs as deprecated with removal date
  • REFACTORING: Update technical references, file paths, method names

​
Phase 6: User review

Presents the reconciliation plan and gets user decisions: 
Reconciliation Summary:
━━━━━━━━━━━━━━━━━━━━━━
Auto-resolve (code wins):
  • NEW_FUNCTIONALITY: 12 items → update specs
  • REMOVED_FEATURE: 3 items → deprecate in specs
  • REFACTORING: 5 items → update technical refs

Requires your decision:
  • BEHAVIORAL_CHANGE: 4 items
  • BUG_OR_DEFECT: 2 items
  • AMBIGUOUS: 1 item

Pipeline impact: stages {spec-auditor, test-planner} will become stale
For each item requiring decision: 
DIVERGENCE #1: User authentication timeout changed
  Spec says: Session timeout SHALL be 30 minutes
  Code does: Session timeout is 60 minutes
  Tests: Pass with 60-minute timeout

  Options:
  (A) Code is correct → update spec to match code
  (B) Spec is correct → flag code as defect (create task)
  (C) Both need changes → create change request
  (D) Skip for now → leave divergence documented
In --code-wins mode, this phase is skipped and everything is auto-resolved toward code. In --dry-run mode, the summary is presented but no decisions are requested.

​
Phase 7: Apply changes

Applies the reconciliation decisions to SDD artifacts:
  • Add new requirements to requirements/REQUIREMENTS.md
  • Add new use cases to spec/use-cases.md
  • Add new API contracts to spec/contracts.md (if applicable)
  • Mark as [RECONCILED] with source reference
  • Mark requirement as [DEPRECATED] with date and reason
  • Update use case status to “deprecated”
  • Add removal note to spec documents
  • Do NOT delete — preserve for traceability
  • Update file paths and method references in specs
  • Update API contract if endpoint structure changed
  • Update architecture references in plan documents
  • Update requirement EARS statement
  • Update use case description and acceptance criteria
  • Add ADR if the change is architecturally significant
  • Create a defect task entry (but do NOT modify code)
  • Flag in reconciliation report for future /sdd:task-implementer action
All changes are applied atomically (all or nothing per divergence) to maintain consistency.

​
Phase 8: Pipeline state update

Updates pipeline state to reflect reconciliation:
  • Recalculates hashes for modified artifact directories
  • Marks affected stages as needing re-run:
    • If requirements/ changed → spec-auditor and downstream become stale
    • If spec/ changed → test-planner and downstream become stale
    • If plan/ changed → task-generator and downstream become stale
  • Updates pipeline-state.json with new hashes and stale markers
  • Generates reconciliation/RECONCILIATION-REPORT.md

​
Output format

The reconcile skill generates a comprehensive reconciliation report at reconciliation/RECONCILIATION-REPORT.md: Key sections:
  • Executive summary with divergence counts by type
  • Detailed divergence listing with classification evidence
  • Actions taken (auto-resolved and user-decided)
  • Pending items (deferred decisions, defect tasks created)
  • Pipeline cascade impact
  • Traceability chain changes
The reconciliation report provides a complete audit trail of all decisions made during reconciliation. Keep this report for future reference.

​
Six divergence types

The reconcile skill classifies divergences into six types:

NEW_FUNCTIONALITY

Code exists without spec. Has tests or is actively used. Auto-resolved: Update specs to match code.

REMOVED_FEATURE

Spec exists without code. No recent commits touching it. Auto-resolved: Deprecate in specs.

BEHAVIORAL_CHANGE

Both exist but behavior differs. User decision: Is code correct or is it a bug?

REFACTORING

Structure changed but behavior is equivalent. Tests still pass. Auto-resolved: Update technical specs only.

BUG_OR_DEFECT

Code contradicts spec AND tests fail or are missing. User decision: Fix code or update spec?

AMBIGUOUS

Cannot determine type with confidence. User decision: Classify manually.

​
Relationship to other skills

Onboarding skill

Onboarding recommends reconcile for SDD drift scenario (scenario 3).

Reverse engineer skill

Use reverse-engineer when NO SDD artifacts exist. Reconcile requires existing specs.

Req-change skill

For intentional changes, use req-change. Reconcile handles unintentional drift.

Traceability check

Run after reconcile to verify chain integrity after updates.

​
Constraints

  1. Source read-only: Never modifies files in src/ or tests/. These are the source of truth for current behavior.
  2. Requires SDD artifacts: Cannot run without existing requirements/ and spec/. Aborts if missing.
  3. Summary first: Always presents the reconciliation summary before applying changes, even for auto-resolvable items.
  4. Atomic per divergence: Each divergence is resolved independently. A failure in one does not block others.
  5. Deprecate, don’t delete: Removed features are marked deprecated, never deleted from specs (traceability preservation).
  6. Evidence-based: Every classification must cite the code location, spec reference, and test status.
  7. No cascading execution: Reconcile updates artifacts and marks stages stale but does NOT invoke downstream skills.

Build docs developers (and LLMs) love

Get started for freeTalk to us