# Close Spec

When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned...

- Repository: https://github.com/dzhng/skills (1394 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dzhng/skills --skill close-spec -g -a claude-code -y`
Codex: `npx skills add dzhng/skills --skill close-spec -g -a codex -y`
Cursor: `npx skills add dzhng/skills --skill close-spec -g -a cursor -y`
Gemini CLI: `npx skills add dzhng/skills --skill close-spec -g -a gemini-cli -y`

## Description

When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale, the why, the principles, the invariants, pointing back to the real code for the how. Use when implementation has landed and the plan no longer matches what shipped, or the user says a feature/spec is finished. Pairs with [write-spec](../write-spec/SKILL.md) (the plan this closes) and [review](../review/SKILL.md) (run before closing).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Close Spec

A spec is a **build plan** while you're building and a **rationale record**
once you've shipped. Closing flips it from one to the other. The plan was a
ladder of slices and predictions; the record is the layer of meaning the code
can't hold, why this exists, what it must never break, what you tried that
failed. The code is the single source of truth for *how*; the closed spec is
the source of truth for *why*, and a map into the code.

Do not summarize the implementation. Anyone can read the code. If a paragraph
restates what a function does, cut it and point at the function instead.

## Workflow

1. **Confirm it shipped.** The feature is merged or working in-tree and its
   tests/screenshot gates are green. If slices remain unverified, it isn't
   done, finish or [review](../review/SKILL.md) first.

2. **Diff plan against reality.** Read the spec's README and slices, then read
   what actually landed. Note every place the build diverged from the plan:
   dropped slices, renamed seams, a mechanic that turned out different, an
   assumption that broke. The divergences are the most valuable thing to
   record, they're exactly what a future reader would otherwise re-derive.

3. **Move it.** `specs/<feature>/` → `specs/done/<feature>/` (use `git mv`).
   Single-file specs: `specs/<feature>.md` → `specs/done/<feature>.md`.

The rest: https://github.com/dzhng/skills/blob/HEAD/skills/engineering/close-spec/SKILL.md