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 — implementation is confirmed correct
• 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

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.

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/

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
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.

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)
• All REMOVED requirements are gone from the main spec
• No delta markers (ADDED/MODIFIED/REMOVED/RENAMED) 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)

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
• Syncing before sdd-verify passes

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)