Vibe Spec Sync

vibe-spec-sync

Code changes. Specs don't update themselves. This skill closes the loop.

When to Use This Skill

• Audit mode: implementation of a spec or design doc is claimed complete, after a major refactor, or when debugging behavior that may not match the spec
• Sync mode: before committing, to detect spec drift from staged changes
• Sync mode: after approving decisions (from vibe-decision-journal), to sync them back to the spec
• Periodically, to confirm the spec still reflects reality

When NOT to Use This Skill

• No spec exists (write one first, or use vibe-doc-quality-gate to bootstrap)
• Prototype/spike code with no spec commitment
• Spec is explicitly labeled as aspirational/future-state
• Code was intentionally diverged, with the reasons documented

Modes

/vibe-spec-sync            # Sync mode: staged changes vs spec (default)
/vibe-spec-sync --audit    # Audit mode: full spec vs implementation, no edits

Prerequisites

The project must have:

• A specification document (markdown) — configured in step 1
• Implementation code that the spec describes
• Optionally: a test suite with requirement traceability markers (# req:[ID])

Steps

Step 1: Locate Spec and Code (both modes)

1. Find the spec — Look for:

   • spec.md, SPEC.md, *_spec.md in project root or docs/
   • Design docs in docs/design/, docs/architecture/
   • Ask user if ambiguous: "Which document is the authoritative spec?"

2. Find the implementation — The code files the spec describes

3. Find the decision log — docs/decisions/decisions.jsonl (from vibe-decision-journal)

Audit Mode (--audit)

Read-only. Nothing is edited.

1. For each requirement or section in the spec, find the corresponding code and check whether it matches exactly.
2. Record each divergence as a gap:
   • ID: GAP-[SECTION]-[NNN] (e.g., GAP-AUTH-001)
   • Type: Missing (spec says X, code has nothing) / Incorrect (spec says X, code does Y) / Extra (code does X, spec is silent)
   • Severity: Critical / High / Medium / Low
   • Evidence: the spec quote and the code file:line
3. Report using the Audit Report format below. For 10+ gaps, hand them to vibe-gap-closure-loop. To accept an Extra or Incorrect item as the new intended behavior, run sync mode on it.

Sync mode (default) continues with Steps 2–5 below.

Step 2: Extract Drift from Staged Changes

Run git diff --cached and analyze what changed relative to the spec:

1. Categorize each change:

   • Spec-aligned: Change matches what the spec says → no action
   • Spec-extending: Change adds behavior the spec doesn't mention → spec needs new section
   • Spec-modifying: Change alters behavior the spec describes differently → spec needs update
   • Spec-contradicting: Change violates what the spec explicitly forbids → flag for review

2. For each drift item, produce:

   DRIFT-[NNN]:
     Type: extending | modifying | contradicting
     Spec section: "## [Header]"
     Current spec says: "[quoted text]"
     Code now does: "[description of new behavior]"
     Suggested spec update: "[proposed new text]"

3. Present drift items to the user for a decision (use the harness's structured question tool if it has one; otherwise ask in plain text and wait):

   • Approve update — update the spec to match the code
   • Approve with edits — user refines the proposed spec text
   • Reject — the code is wrong; flag for fix (do NOT update spec)
   • Defer — not ready to decide; skip for now

Step 3: Apply Spec Updates

For each approved drift item:

1. Find the target section in the spec:

   • Match by exact header first
   • Fall back to normalized match (case-insensitive, whitespace-collapsed)
   • If no matching section, determine correct placement by reading surrounding sections

2. Apply the update:

   • For modifying: Replace the relevant paragraph/sentence within the section. Use search-and-replace with the old text and new text. Preserve surrounding content.
   • For extending: Add new content to the appropriate existing section, or create a new section if the content doesn't fit anywhere.
   • For contradicting (approved): Same as modifying — replace the contradicted text.

3. Preserve spec structure:

   • Don't rewrite sections that weren't affected
   • Maintain existing formatting, header hierarchy, and ordering
   • Add a brief inline note if a section was significantly changed: <!-- Updated: [date] per DEC-[NNNN] -->

4. Stage the spec changes: git add [spec file]