Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jorgeferrando/sdd-skills/llms.txt

Use this file to discover all available pages before exploring further.

/sdd-archive closes the SDD cycle for a change. It merges the change’s delta specs into the project’s canonical specs so they reflect the current system state, updates the domain index, captures non-obvious decisions and anti-patterns in a learnings file, and moves the change folder to the archive for future reference. Run /sdd-archive after /sdd-verify has passed and the PR has been created.

​
Usage

/sdd-archive                   # Archive the active change
/sdd-archive {change-name}     # Archive a specific change

​
Prerequisites

  • /sdd-verify completed — all checks green
  • PR created (done during /sdd-verify)
  • All tasks in tasks.md marked [x]

​
What it does

1

Verify state

Confirms the change is actually complete before touching any canonical files:
# Should return 0 (no unchecked tasks remaining)
grep -c "\[ \]" openspec/changes/{change-name}/tasks.md
Checks that /sdd-verify passed and a PR exists. Stops if any condition is not met.
2

Merge delta specs into canonical specs

The change specs at openspec/changes/{change-name}/specs/ contain deltas — only the behaviors that changed. This step merges them into the canonical specs at openspec/specs/.For each openspec/changes/{change-name}/specs/{domain}/spec.md:
  1. Reads the current canonical spec at openspec/specs/{domain}/spec.md
  2. Reads the change delta
  3. Merges: updates the canonical with new behaviors, rules, and decisions
  4. Updates the canonical metadata (version, date)
If no canonical spec exists for the domain yet, creates it:
mkdir -p openspec/specs/{domain}
cp openspec/changes/{change-name}/specs/{domain}/spec.md openspec/specs/{domain}/spec.md
3

Update openspec/INDEX.md

Keeps the domain index synchronized with the canonical specs.If openspec/INDEX.md does not exist and openspec/specs/ contains domains, bootstraps a full index by reading each domain spec and generating one entry per domain:
## {domain} (`specs/{domain}/spec.md`)
{1-2 line summary of what this domain covers}
**Entities:** {Symbol1}, {function()}, {ClassName}
**Keywords:** {kw1}, {kw2}, {kw3}
If openspec/INDEX.md exists, updates the entries for domains modified by this change: refreshes summaries, adds new entities, and adds new keywords. If this change introduces a new domain, appends a new entry. Verifies that every directory in openspec/specs/ has a corresponding entry.
4

Move the change to archive

Moves the active change folder to the archive with a datestamp:
DATE=$(date +%Y-%m-%d)
CHANGE={change-name}
mv "openspec/changes/${CHANGE}" "openspec/changes/archive/${DATE}-${CHANGE}"
5

Verify post-archive structure

Confirms the directory structure is correct after the move:
ls openspec/changes/          # change should be gone from active
ls openspec/changes/archive/  # change should appear here
ls openspec/specs/            # canonical specs updated
6

Update learnings

Appends a new entry to openspec/steering/learnings.md (creates the file if it does not exist). Captures only what is non-obvious and would help future changes — no boilerplate. Looks at discarded alternatives, re-opened tasks, unexpected domain couplings, and corrected conventions.
## {YYYY-MM-DD} — {change-name}

**Domains touched:** {domain1}, {domain2}

**Decisions:**
- {What was decided and why — especially if it contradicts what someone might naturally do}

**Discarded alternatives:**
- {Alternative} — {reason it was rejected}

**Unexpected couplings:**
- {module A} ↔ {module B}: {why they turned out to be linked}

**Anti-patterns confirmed:**
- {What not to do here} — {observed consequence}

**Open questions:**
- {Something deferred or left unresolved}
Sections with nothing meaningful to say are omitted.

​
Output

ArtifactResult
openspec/specs/{domain}/spec.mdUpdated with merged delta
openspec/INDEX.mdUpdated with new/modified domain entries
openspec/changes/archive/{date}-{change-name}/Full change history preserved
openspec/steering/learnings.mdNew entry appended

​
Completion summary

ARCHIVE COMPLETE: {change-name}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Archived at:
  openspec/changes/archive/{date}-{change-name}/

Canonical specs updated:
  openspec/specs/{domain}/spec.md ✓

Learnings updated:
  openspec/steering/learnings.md ✓

Active changes remaining: N
After archive, the canonical specs are the source of truth for what the system currently does. Future /sdd-explore runs will find the decisions made in this change — both what was chosen and what was discarded — through the learnings.md file and the archived change folder.

​
Handling bugs found after archive

If a bug is discovered after the change has been archived:
  1. Document it in the archived tasks.md under ## Bugs post-archive
  2. Implement the fix and commit atomically
  3. Mark [x] with the commit message
## Bugs post-archive

- [x] **BUG01** `path/file` — short symptom description
  - Found: {context}
  - Fix: {description}
  - Commit: `{commit message}`

​
Skill metadata

PropertyValue
model_hinthaiku
requiresopenspec/changes/{change}/tasks.md, openspec/changes/{change}/specs/*/spec.md
producesopenspec/specs/*/spec.md, openspec/INDEX.md, openspec/changes/archive/, openspec/steering/learnings.md
openspec/ is local by default and is not committed to the repository unless your project opts in. The archive lives on your machine as historical context for the AI, not as source control history.

Build docs developers (and LLMs) love

Get started for freeTalk to us