ss-archive

Archive Change

Promote a completed change into the project's permanent knowledge layout: the active change folder moves under changes/archive/, and the capability it implemented gets a machine-validatable spec.md plus a human-readable overview.md under specs/<capability>/.

Announce at start: "I'm using the ss-archive skill to archive this change and capture its architectural knowledge."

The source change folder is preserved under changes/archive/ — this is a move, not a delete. The artifact you produce is a distilled companion to the formal spec, not a copy of design/plan.

Input

Optionally specify the change identifier (e.g. 2025-03-25-auth-refactor). If omitted, list active change folders under changes/ (excluding archive/); if multiple, ask the user. If none, abort.

Process

Step 1: Read Change Artifacts

From changes/<change-name>/:

• design.md — architectural design and motivation
• plan.md — implementation plan
• tasks.md — completion status
• specs/<capability>/spec.md — the capability spec

Extract the capability name from the specs/<capability>/ path. If the change spans multiple capabilities, ask the user which to archive — each capability gets its own overview.

Partial artifacts are fine — work with what's there.

Step 1a: Completion Check

Before drafting, confirm the change is actually done.

Task completion. If tasks.md exists, count - [ ] (incomplete) vs - [x] (complete) entries. If any tasks are still - [ ]:

• List the incomplete tasks (subject lines, not full text)
• Use AskUserQuestion to confirm:
  • Archive anyway — the remaining tasks were dropped on purpose; archive as-is
  • Stop — finish the remaining tasks first, then re-run ss-archive

If tasks.md is missing entirely, note it and proceed without a task check.

Artifact presence. If design.md, plan.md, or the capability spec.md is missing, list what's missing and confirm via AskUserQuestion before continuing.

Don't block on warnings; just inform and confirm. The user is the source of truth on whether the change is ready to freeze.

Step 2: Draft the Overview

Write a single overview document per capability. Target 400–600 words.

Structure:

# <Capability Name> — Overview

Human-readable companion to [`spec.md`](spec.md). Start here to understand **why** the capability exists and **how** the pieces fit together; read `spec.md` for the exact requirements and scenarios.

## Purpose

Why does this capability exist? What friction did it remove? Describe the concrete user scenarios it enables — not abstract goals.

## Architecture & Key Design

Components, interactions, data flow. Each bolded paragraph captures one significant design choice — what was chosen, written as a statement about the shipped system.

## Scope & Boundaries

What this capability does and does NOT cover. Non-goals called out so future work doesn't accidentally stretch the contract.

## Integration Points

External services, other repos, infra dependencies. Enough detail to trace "if X breaks, what in our system breaks".

## Notes for Future Work

Forward-looking gotchas for anyone extending or operating this system. Frame as "when you touch X, remember Y" — not "we had a bug and fixed it".

---

**Provenance:** link to the archived change folder.

Writing rules (important):

• Describe the shipped system, not history. Never write "Alternatives considered / rejected" sections. Never frame lessons as "we made a mistake in PR #N". Those narratives belong in git history, not the overview.
• Prioritise WHY over WHAT. spec.md already enumerates WHAT; the overview exists to convey intent.
• Be concrete. Use actual file paths, function names, env var names, PR numbers. Vague prose ages badly.
• No "alternatives rejected" block. If a past decision is load-bearing, fold it into the architecture prose as a current-state statement ("X is a safety net, not a tenant boundary").

Step 3: Promote the Spec

Make sure specs/<capability>/ exists; create it if needed.

New capability (no existing specs/<capability>/spec.md): the change's spec becomes the capability's spec. Copy the content over. Skip the delta preview below.

Existing capability (spec.md already there): the change's spec is a delta to the existing one. Before merging, do a delta preview:

1. Read both files
2. Summarise what the merge would change, grouped by category:
   • Add — new requirements introduced by the delta
   • Modify — existing requirements whose text changes
   • Remove — requirements deleted by the delta
   • Rename — requirements moved or renamed
3. Show the summary as a short bulleted list (one line per requirement; refer by section/heading, not full text)
4. Use AskUserQuestion to confirm:
   • Merge now (recommended) — apply the delta as previewed
   • Edit first — pause so the user can adjust the delta before merging
   • Skip merge — archive the change without touching the canonical spec

If you can't determine the diff cleanly (e.g., the delta uses informal markers you don't recognise), surface that and ask the user how to proceed instead of guessing.

After the user confirms, merge respecting whatever add/modify/remove markers the change's spec uses.

Make sure the final specs/<capability>/spec.md has a concrete Purpose section — if it's empty or placeholder text, fill it with 2–3 sentences paraphrased from the overview's Purpose.

Step 4: Write the Overview

Write the drafted overview to specs/<capability>/overview.md. If the file already exists (the capability is being revised, not created), ask the user whether to overwrite or merge — overview.md evolves with the capability.

Step 5: Move the Source Folder

Move changes/<change-name>/ to changes/archive/<YYYY-MM-DD>-<change-name>/ where <YYYY-MM-DD> is today's date. This preserves the full decision trail (design, plan, tasks, spec delta) as a frozen historical record.

Update the Provenance footer in overview.md to point at the new archived-folder path.

Step 6: Report

## Archive Complete

**Change:** <change-name> → changes/archive/<YYYY-MM-DD>-<change-name>/
**Spec:** specs/<capability>/spec.md — <N> requirements
**Overview:** specs/<capability>/overview.md

File Roles

Path	Role	Evolves?
specs/<capability>/spec.md	Machine-validatable contract	Yes — new changes add/modify requirements
specs/<capability>/overview.md	Human-readable companion	Yes — updated in place by future archives
changes/archive/<prefixed-name>/	Frozen source packet (design / plan / tasks / spec delta)	No — historical

Future changes touching the same capability should UPDATE overview.md rather than create a second one. Don't accumulate per-change archive docs under specs/.

Guardrails

• No "alternatives rejected" narratives. Describe shipped state. If a rejected alternative is still load-bearing context, fold it into architecture prose as current-state.
• No backward-looking lessons framing. "Notes for Future Work" is forward-looking — "when you do X, remember Y", not "we made mistake Z".
• Archive = move, not delete. The source change folder is preserved under changes/archive/, not removed. Full history stays accessible.
• Ask before overwriting. If spec.md or overview.md already exists in specs/<capability>/, don't silently clobber — ask the user how to handle it.

Integration

Called by:

• ss-subagent-driven-development and ss-executing-plans suggest this after all tasks complete.
• User directly via /superspec:ss-archive or /ss-archive.

Reads from:

• Active change artifacts under changes/<change-name>/ (design.md, plan.md, tasks.md, specs/<capability>/spec.md).

Writes to:

• specs/<capability>/spec.md — promoted from the change's spec (created or merged).
• specs/<capability>/overview.md — newly drafted digest.
• Moves changes/<change-name>/ to changes/archive/<prefixed-name>/.

Common Mistakes

Mistake	Fix
Missing or placeholder Purpose in specs/<capability>/spec.md	Fill with 2–3 sentences from the overview. Don't ship with an empty or TBD Purpose.
Writing a "Decisions → Alternatives → Rationale" bullet list for every choice	Fold decisions into prose. The overview is a digest, not a decision log.
Running the skill before all tasks are complete	The completion check in Step 1a catches this — confirm with the user before proceeding.
Silently overwriting an existing specs/<capability>/spec.md with the delta	Use the delta preview in Step 3: summarise add/modify/remove/rename and confirm before merging.
Creating overview.md in a capability folder that already has one	Ask first. The existing overview likely carries context from prior changes that shouldn't be silently overwritten.
Deleting the source change folder instead of moving it	Archive is a move to changes/archive/, not a delete. The full decision trail must stay accessible.