sdd-clean

/sdd-clean — Context Cleanup

Persistent markdown is a paid resource: every line it holds loads into future context windows. This workflow keeps it at as little as possible, as much as necessary — maximum useful information per token, judged by semantic usefulness, never by raw size alone. It is manually invokable at any time; other workflows may recommend it, but cleanup never happens as a silent side effect. The user may name one file after the command; then only that file is analyzed and compacted. All dialogue and reports in DocLanguage; compacted files keep the language they are written in.

Scope and write authority

Analyze all FeatherSpec-managed markdown; write only where this command has authority:

Files	Authority
.memory-bank/*.md	analyze + compact here
.architecture/*.md maps	analyze + compact here (≤ 40-line budget per .claude/rules/architecture-map.md)
architecture: snapshot in AGENTS.md	analyze only; observed drift hands over to /sdd-architecture-update — its gate stays the snapshot's only write path
.specs/** specs and plans	analyze, report findings only — their commands and rules own edits; AC- and T- IDs are never cleanup material
Wiring (.claude/, .github/, AGENTS.md prose)	out of scope — template-owned

Phase 1 — Analyze (read-only)

Read each in-scope file against its declared purpose (AGENTS.md Memory Bank list, .claude/rules/memory-bank.md with its routing table, .claude/rules/architecture-map.md for maps) and ask, in this order:

1. Misplaced? Content in the wrong file moves to its declared home per the routing table — moving is not deleting.
2. Duplicate? A fact stated in several files keeps exactly one canonical home; the others link or drop it.
3. Stale? Spot-check claims against the repository — named paths, technologies, assumptions. A named file, script or command target must exist: verify each with a cheap check (path exists, script is in the manifest) and carry the checked items into the Phase-2 plan — "nothing to verify" is itself a claim and needs that list to back it. Stale content is updated or removed; git history is the archive, the live file represents the current useful state.
4. Rediscoverable? Inventories an agent can derive from the code in seconds (file lists, obvious signatures) go. Intent, boundaries, constraints, conventions and traps stay — the Memory Bank holds knowledge, not a second copy of the repository.
5. Historical? activeContext.md is the current working state, not a diary: finished episodes leave; decisions that still matter move, dated, to systemPatterns.md.
6. Verbose? Compact prose into facts without losing meaning. Reasoning stays when it binds future decisions ("new persistence tech needs architecture approval"), goes when it only narrates the past.
7. Over budget? activeContext.md against its size limit in AGENTS.md; maps against their 40 lines. Over budget triggers the checks above — never blind truncation.
8. Against the constitution? A statement that contradicts an AGENTS.md invariant — a plan file described as deleted, a "preference" that is not a bullet in AGENTS.md — is a finding, never a fact to preserve: inside this command's write scope, correct the text to plain facts stripped of the invalid justification; outside it, report it with the quote.