| name | gc |
| description | Project entropy control (gc) — reconcile docs against code, clear dead code and stale docs, archive specs, scan friction, and generate architecture-improvement proposals. Use to clean up a project, when docs have drifted from reality, to find refactor directions, after a large feature merges (scoped), or for periodic maintenance (global). |
GC
Entropy control. The price of keeping feature work focused is that structural and doc drift accumulate; this skill periodically pulls it back.
The core rule is separate discovery from execution: do the safe things directly (gate-protected), and for anything that touches structure, only propose — don't act.
Scope
- scoped: triggered after a large feature merges, looking only at the changed area.
- global: triggered periodically (weekly suggested), across the whole repo.
When the user doesn't specify, judge from the trigger context and state which scope you're running.
Actions
1. Reconcile (execute directly, gate-protected)
- Move
done-but-unarchived specs in docs/specs/ into archive/; flag long-stale active / proposed ones (including stale claims — an owner whose Progress log has gone quiet) for the user, don't delete on your own.
- Reconcile
CONTEXT.md against code entry by entry: code is the single source of truth for "what is"; where they don't match, fix the doc.
- Mark ADRs overturned by newer decisions
superseded, don't delete.
- Dead code, references to deleted files, stale TODOs: only counts once the full automated gate suite is green after removal.
2. Scan (record only, don't modify)
- Duplicate patterns (abstraction opportunities where the rule of three is met), shallow modules, tests that drag the feedback loop.
- Mine the friction notes in spec Progress logs first: where the agent retried, got confused, or got stuck on slow tests — wherever the agent worked hardest is where a refactor pays most. This beats abstract aesthetic judgment.
3. Propose (don't act)
- Write architecture-level changes as
proposed-status specs in docs/specs/: motivation (cite specific friction or scan evidence), expected benefit, acceptance criteria.
- Proposals queue for a human to pick; a picked one goes through the normal shape → implement flow.
Red lines
- Don't mix in feature changes; every change this skill makes leaves behavior unchanged.
- Run the gates after each cleanup step; if red, roll that step back.
- When you can't judge whether something is stale, ask — don't delete.
Completion criteria
- Reconciliation changes are landed and all gates green.
- Every proposal has a motivation, evidence, and acceptance criteria, ready for shape / implement to pick up.
- Output a short report: what was cleaned, what was found, what was proposed, and what's left for the user to decide.
