sdd-sync

name	sdd-sync
description	Use when merging delta specs from a change into the main baseline specs. Triggers: "sync specs", "merge delta specs", "update main specs", "apply the spec changes", "sync the change".

SDD Sync

Merge delta specs from a change directory into the main baseline specs. Applies each delta marker intelligently, preserving existing content not mentioned in the delta.

SPECS_ROOT is resolved by the sdd router before this skill runs. Replace .specs/ with your project's actual specs root in all paths below.

Invocation Notice

• Inform the user when this skill is being invoked by name: sdd-sync.

When to Use

• After sdd-verify passes with no blocking findings — implementation is confirmed correct
• After sdd-verify reports only blockers that are explicitly overridden per references/sdd-change-formats.md
• Ready to finalize the change and update the source-of-truth specs

When Not to Use

• Delta specs don't exist for this change — nothing to sync
• Implementation isn't verified — run sdd-verify first
• Blocking findings remain from sdd-verify

Soft Gate

If no delta specs exist in .specs/changes/<name>/specs/, warn:

"No delta specs to sync."

Stop unless the user confirms to proceed.

Before syncing, confirm verification status and any recorded override trail:

1. sdd-sync consumes the latest sdd-verify outcome; it does not reconstruct verification from design.md.
2. If the latest verify result is not in context, stop and tell the user to run sdd-verify first.
3. If sync is proceeding under override, read .specs/changes/<name>/design.md for ## Verification Overrides and confirm each applicable entry has all required fields (finding, stage, reason, constraints, follow-up task, approved by, recorded). Stop if any required field is missing.
4. Any blocker from the current verify result that is not covered by a recorded override remains blocking. Stop and tell the user which blockers remain uncovered.

Process

Phase 1: Identify What to Sync

1. Confirm the active change (ask if multiple active changes exist)
2. List all delta spec files in .specs/changes/<name>/specs/
3. For each delta spec, identify the corresponding main spec in .specs/specs/
4. If sync is proceeding under override, load the matching override entries and the referenced unchecked tasks from tasks.md

Phase 2: Apply Each Delta

For each delta spec, read both files:

• Delta: .specs/changes/<name>/specs/<capability>/spec.md
• Main: .specs/specs/<capability>/spec.md (may not exist for new capabilities)

Apply delta markers:

Delta marker	Action
ADDED requirements	Insert as new ### Requirement: entries in the main spec
MODIFIED requirements	Find the matching requirement by name and replace it — apply the MODIFIED preservation guard first
REMOVED requirements	Find the matching requirement by name and delete it
RENAMED capabilities	Rename the capability directory and update the spec header

Preservation rule: Content in the main spec not mentioned in the delta is never touched.

Strip delta-only annotations: When writing any requirement into a baseline spec — inserting an ADDED requirement, replacing a MODIFIED one, or creating a new capability (Phase 3) — strip its delta-only lines: the > Previously: … provenance line and any Serves: backlink. Baseline specs carry contracts, not change provenance or value backlinks; the value layer (user stories and Serves: links) is change-scoped and stays in the change directory.

MODIFIED preservation guard: The preservation rule operates at requirement granularity — a MODIFIED requirement is replaced as a whole, so scenarios its delta block omits are not preserved. Before replacing, compare the baseline requirement's scenarios and sub-clauses against the MODIFIED delta block. If the delta omits any baseline scenario that the change did not deliberately remove (no rationale in design.md), stop and surface it:

"MODIFIED <name>: baseline scenario(s) <…> are absent from the delta block and will be deleted on sync. Restore the full post-change requirement, or confirm the removal is intentional."

Replace only after the omission is confirmed intentional, and strip the delta-only > Previously: … and Serves: lines — they do not belong in the baseline (see Strip delta-only annotations).

A mechanical backstop ships with the skill for the dropped-scenario half of this guard: run scripts/check_modified_completeness.py <specs-root> --change <name> (a uv script; deps are declared inline). It compares scenario names only and exits non-zero when a MODIFIED delta drops a baseline scenario — sub-clause and body-text preservation is not mechanically checked, so keep verifying that by reading. Mark intentional scenario drops with a <!-- modified-removes: ScenarioName --> comment inside the delta block.

Idempotency rule: Applying the same delta twice produces the same result as applying it once. For ADDED: check whether the requirement already exists by name before inserting — skip if already present. For RENAMED: check whether the new directory name already exists before renaming — skip if already renamed.

RENAMED processing order: When a delta spec contains RENAMED alongside other markers, process the rename first (directory rename + spec header update), then apply any ADDED/MODIFIED/REMOVED markers against the already-renamed main spec. The delta spec is always identified by the old capability name — look it up before renaming.

Phase 3: Handle New Capabilities

If a delta spec covers a capability with no corresponding main spec:

1. Create .specs/specs/<capability>/ directory
2. Create spec.md in baseline format (no delta markers)
3. Strip the ## ADDED, ## MODIFIED, ## REMOVED section headings and keep the ### Requirement: entries beneath them as plain requirements

See references/sdd-spec-formats.md for the baseline spec format.

If the delta spec contains only RENAMED and the old capability does not exist in main specs, create the capability under the new name using the ADDED requirements as baseline content.

Phase 4: Update Schema Snapshots (if schemas configured)

If .specs/.sdd/schema-config.yaml exists and schemas/after/ is present in the change directory:

1. Copy each schema file from .specs/changes/<name>/schemas/after/<schema-type> to .specs/schemas/<schema-type> (overwrite).

2. Update .specs/schemas/.schema-sources.yaml with the generation date and change name.

3. If the repo contains a committed authored schema (e.g., docs/openapi.yaml), surface a reminder — do not auto-update it:

   "Authored schema at <path> may need updating to match the implementation. Reference: .specs/changes/<name>/schemas/after/"

If no schema config exists but .specs/schemas/ contains files and no schemas/after/ directory exists in the change, emit a visible warning:

WARNING: Schema baseline exists at .specs/schemas/ but this change has no after-snapshot. The schema baseline may be stale. Run sdd-derive or create .specs/.sdd/schema-config.yaml to enable schema tracking.

If no schema config exists and .specs/schemas/ is empty or absent, skip silently.

Phase 5: Validate Output

• All ADDED requirements appear in the main spec
• All MODIFIED requirements reflect the updated behavior (old version removed) with no baseline scenario dropped unintentionally
• All REMOVED requirements are gone from the main spec
• No delta markers (ADDED/MODIFIED/REMOVED/RENAMED), > Previously: provenance lines, or Serves: backlinks remain in main specs
• Content not mentioned in deltas is unchanged

Phase 6: Report

List each capability synced:

Synced:
- auth/          → 2 requirements added, 1 modified
- payments/      → 1 requirement removed
- notifications/ → new capability created (3 requirements)
Schema snapshots updated:
- openapi.yaml   → 2 endpoints added, 1 model modified
- Reminder: authored docs/openapi.yaml may be stale (schema sync did not update it)

Synced under overrides:
- `pip audit` failure for `litellm` → stage: `verify`; reason: upstream fix unavailable in current environment; constraints: no ignore added; follow-up remains open in `tasks.md`

Common Mistakes

• Replacing the entire main spec instead of merging selectively
• Leaving delta markers (ADDED/MODIFIED/REMOVED) in the main spec after sync
• Touching content not mentioned in the delta
• Replacing a MODIFIED requirement without first checking that its delta block preserves the baseline's still-applicable scenarios — the wholesale replace silently deletes any scenario the delta did not restate
• Carrying the delta-only > Previously: … provenance line into the baseline spec
• Carrying a delta-only Serves: backlink into the baseline spec — like > Previously:, it is change-scoped and must be stripped at sync
• Reconstructing the verify outcome from design.md instead of consuming the latest sdd-verify result plus any recorded overrides
• Syncing before sdd-verify clears all blockers, whether by a clean pass or a recorded override
• Treating a blocker as non-blocking without a recorded design.md override and an unchecked remediation task in tasks.md

References

• references/sdd-spec-formats.md — baseline spec format for new capabilities created during sync
• references/sdd-change-formats.md — change directory artifact formats (proposal, design, tasks)
• references/sdd-schema.md — schema lifecycle policy (§ 4) and .schema-sources.yaml format (§ 3)
• scripts/check_modified_completeness.py — mechanical dropped-scenario check (scenario names only, not body sub-clauses); exits non-zero on dropped baseline scenarios, wireable as a pre-commit/CI gate