Cursor rule

1---
2description: "Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected."
3alwaysApply: false
4---
5 
6# story: e09s01
7<!-- story: e45s12 -->
8<!-- story: e79s04 -->
9 
10 
11# Stocktake Skills
12> **HARD GATE** — **HARD GATE** — Skill inventory must be current. Missing HARD GATEs, stale descriptions, or broken verify commands are defects, not cosmetic. Fix them in `evolve-skill`.
13 
14 
15Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX mismatches.
16 
17## Modes
18 
19| Mode | Scope |
20|------|-------|
21| **Quick Scan** | Skills changed since last tag or in current diff |
22| **Full** | All skills per SKILL-INDEX.md + catalog audit |
23| **--verify** | Run `bash scripts/run-skill-verify.sh` and append health results to the stocktake report |
24 
25## Process
26 
270. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms).
280b. **Agentic STE audit (e79s04)** — run `bash scripts/validate-agentic-ste.sh --audit skills/`. Flag hedge words and sentences over 20 words per [AGENTIC-STE.md](../../docs/AGENTIC-STE.md). Record WARN lines in the stocktake report as **STE debt** — do NOT rewrite the full catalog in one pass. Route critical repeat offenders to `evolve-skill`.
291. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
302. Run mode; for each skill check: exists, verb-noun, &lt;300 lines total, HARD GATE present, INDEX row matches.
313. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
324. **Effectiveness report (--full mode only):** Read `specs/state.yaml` `metrics.skill_timings` and report:
33   - Top 5 most-used skills (by calls, total_seconds)
34   - Skills with zero calls (potential dead weight)
35   - Skills with high average time (candidates for `evolve-skill`)
365. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate.
376. **--verify mode:** Run `bash scripts/run-skill-verify.sh` and append a `## Verify Health` section to the stocktake report: `"N/68 PASS, M FAIL, K SKIP"`. FAIL skills are critical findings and go straight to `plan-work`.
38 
39### Skill timing data (`metrics.skill_timings`)
40 
41In `--full` mode, read `specs/state.yaml` `metrics.skill_timings` for per-skill usage stats:
42 
43```yaml
44metrics:
45  skill_timings:
46    survey-context:
47      calls: 12
48      total_seconds: 180
49      avg_seconds: 15.0
50    develop-tdd:
51      calls: 30
52      total_seconds: 5400
53      avg_seconds: 180.0
54```
55 
56Timing data is populated by `scripts/bp-timing.sh start|end <skill>` calls within critical-path skills.
57 
58## Verify
59 
60→ verify: `compgen -G 'specs/STOCKTAKE-*.md' >/dev/null && bash scripts/validate-skill-catalog.sh`
61 
62See [REFERENCE.md](REFERENCE.md) for checklist.
63 
64---
65 
66# Stocktake checklist
67 
68- [ ] SKILL.md exists at repo root `&lt;name&gt;/SKILL.md`
69- [ ] Listed in SKILL-INDEX.md with correct phase
70- [ ] `description` includes "Use when..."
71- [ ] At least one HARD GATE callout
72- [ ] specs/ output documented if applicable
73- [ ] No edit to `.cursor/rules/` or `.gemini/` (generated only)
74