Sweep All Specs for Gaps
Estate-wide health. Individual spec skills go deep on one feature; this goes wide and finds what nobody maintained.
Reports only. Fixing is
.
Format authority:
references/spec-format.md
. Spec root:
.
When to use
- Periodic review — monthly or quarterly.
- "What state are our specs in?"
- Deciding where to spend maintenance effort.
- Finding which open questions are actually blocking work.
Not this skill: auditing one spec against code (
), fixing anything (
).
What to look for
1. Roll-up statuses that disagree with their behaviours
Recompute every front-matter
from the behaviour badges and report mismatches. A spec marked
containing a 🔵 behaviour is the common case, and it's how an estate starts overstating itself.
2. Partial behaviours with no note
Every 🟡 requires a one-line note on what's missing. A 🟡 without one is work nobody is tracking, described nowhere else.
The note is the requirement; a ticket reference is optional, and absent entirely when
is
.
Where a provider
is configured, also flag 🟡 behaviours whose ticket is closed. With
, resolve it properly —
is authenticated, so this is a real check rather than a guess. With
,
, or
, attempt it only if credentials exist and
say plainly when you couldn't; an unresolvable ticket is evidence of nothing.
A closed ticket means the badge is
worth verifying and nothing more. Report it as such and hand to
, which requires the code and the test before promoting anything. Never infer a badge from tracker state — the spec owns intent, the tracker owns scheduling, and collapsing the two puts the estate back to being optimistic.
A closed ticket with a long thread is also the best candidate for
: that's where decisions were made that the spec never absorbed.
3. Ageing future behaviours
🔵 behaviours that have sat untouched for a long time. Report age from git history rather than guessing.
Old 🔵 behaviours are not automatically a problem — a design record is allowed to sit. But a cluster of them in one spec usually means the feature was designed far beyond what anyone intends to build, and the spec would read better with them moved to Future Considerations.
4. Open Questions, split by kind
- questions — these are the ones that matter. Each is a behaviour that cannot proceed until someone decides something. List them with the behaviour they block and how long they've been open. Lead the report with these: they're the only category unblockable by a single conversation.
- Unprefixed questions older than a few months — either they stopped mattering, or nobody owns them.
- questions — healthy. Count them but don't flag them; they're recorded reasoning, not debt.
5. Modules with no specs
Compare the module structure of the codebase against the spec estate. A module with substantial code and no spec is the largest kind of gap, and the least visible — you can't notice a spec that was never written.
Rank by code volume and change frequency. A large, frequently-changed, unspecced module is where the estate's blind spot costs most.
6. Structural problems
- Specs missing required section headers.
- Behaviour IDs that skip or repeat.
- Flow contracts whose Mermaid sibling is older than the YAML — the diagram is stale.
- references pointing at behaviour IDs that no longer exist.
Report
Lead with blocking questions, then unspecced modules by size, then everything else. Order by what's costing most, not by category.
For each item: the spec path, the ID, the evidence with dates or counts, and the specific action. End with estate-level counts — specs by status, behaviours by badge, open questions by kind — so the trend is visible when you run it again.
Change nothing.
Quality gate
Anti-patterns
- Treating every open question as debt. Settled ones are the system working; flagging them punishes recording your thinking.
- Reporting counts with no ranking. A list of 200 items with no order is not actionable.
- Skipping unparseable specs. Those are the most broken ones.
- Ignoring modules with no specs because the sweep only looks at files that exist.
Related skills
- — fix what this finds
- — plan a spec for an unspecced module
- — go deep on a spec this flagged
- — the same data, browsable
- — asks current-work decisions; this skill only reports