| name | sdd-changelog |
| description | Archives completed roadmap phases from specs/roadmap.md into specs/changelog.md, compressed to title, completion date, and a one-sentence outcome with a link back to the spec directory. Use when phases are finished and the roadmap should track only open/upcoming work, or when asked to "update the changelog" / "move completed phases out of the roadmap." |
Changelog Skill
Keeps specs/roadmap.md focused on open and upcoming work by moving every completed
phase into specs/changelog.md. The blow-by-blow task lists stay in each phase's spec
directory and in git history — the changelog is the compressed index of what shipped.
What counts as "completed"
A phase is completed if its heading carries the [x] COMPLETE marker, including phases
marked [x] COMPLETE (implementation; manual QA / stakeholder sign-off pending). The header
marker is authoritative — move it regardless of leftover [ ] verification checkboxes.
When a moved phase still has open items, do not drop them silently:
- Note the pending state in its one-sentence outcome (e.g. "implementation complete, manual QA pending").
- If a later open phase depends on that sign-off, leave a one-line breadcrumb in the roadmap's priority list pointing to the changelog.
Process
Step 1: Read the roadmap
Read specs/roadmap.md. Identify every phase heading with the [x] COMPLETE marker. List the
spec directories under specs/ so each completed phase can be matched to its folder.
Step 2: Confirm the QA-pending judgment call
If any completed phase has open [ ] items (manual QA, stakeholder sign-off, operational
TODOs), use AskUserQuestion once to confirm handling. Default offered options:
- Move all COMPLETE phases — header marker is authoritative; note QA-pending in the outcome.
- Keep QA-pending in roadmap — move only fully verified phases.
- Move, but flag open items — move all, but carry leftover
[ ] items into a short "Open follow-ups" list at the top of the roadmap.
Skip the question if every completed phase is fully verified.
Step 3: Create or update specs/changelog.md
If specs/changelog.md does not exist, create it with this header:
# <Project> Changelog (for the project name, see `AGENTS.md` # Project section)
Completed roadmap phases, compressed to title, completion date, and outcome. Full
task-level detail lives in each phase's spec directory (linked where one exists) and in
git history. Open and upcoming work stays in [roadmap.md](roadmap.md).
Ordered newest phase first.
---
Append one entry per completed phase, newest phase first (descending phase number;
place replanning checkpoints in their chronological slot). Entry format:
## Phase <N> — <Title>
**Completed:** <date> [· **Spec:** [specs/<dir>/](<dir>/)]
<One sentence describing the outcome — what shipped and why it mattered.>
Rules for each entry:
- Completion date — use the explicit date if the phase states one ("Completed: 2026-04-30"); otherwise the release it shipped in ("April 2026 (v1.0.8)") or the month. Never invent a precise date; a spec-folder creation date is a proxy, not a completion date.
- Spec link — link to
specs/<dir>/ only where a directory exists (paths are relative to the specs/ folder, so omit the leading specs/ in the link target). Several phases may share one spec dir (e.g. a batched hotfix); link each to the same folder. If no spec dir exists, omit the link.
- One sentence — outcome, not task list. Compress mercilessly; the detail is in the spec dir.
Step 4: Trim the roadmap
Remove every completed phase block from specs/roadmap.md. Keep:
- The title and intro (add a line: "Completed phases have moved to changelog.md — this file tracks only open and upcoming work.").
- The "Implementation Order" priority list — but strip references to phases now in the changelog and update its date.
- The "Current State" snapshot, "Future Considerations", and "Implementation Notes" sections (orientation, not phases).
- All open / upcoming phase blocks, untouched.
Step 5: Verify
cd specs
grep -c "\[x\] COMPLETE" roadmap.md
grep "^## Phase" roadmap.md
grep -c "^## Phase\|^## Replanning" changelog.md
Confirm no open phase was dropped and no completed phase was left behind.
Hand off
Stage the changes to specs/changelog.md and specs/roadmap.md with git add and propose a commit message — do not run git commit. Per AGENTS.md ## Commits / ## PRs, the user commits and opens the PR (yes, even for changelog/roadmap-only updates on the stable branch).
Usage
/sdd-changelog
Output
specs/changelog.md — created or appended, one compressed entry per completed phase. Staged for the user to commit.specs/roadmap.md — trimmed to open/upcoming phases, pointing at the changelog. Staged for the user to commit.
