Windsurf rules

1---
2name: stocktake-skills
3model: sonnet
4description: "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."
5---
6 
7# story: e09s01
8<!-- story: e45s12 -->
9<!-- story: e79s04 -->
10 
11 
12# Stocktake Skills
13> **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`.
14 
15 
16Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX mismatches.
17 
18## Modes
19 
20| Mode | Scope |
21|------|-------|
22| **Quick Scan** | Skills changed since last tag or in current diff |
23| **Full** | All skills per SKILL-INDEX.md + catalog audit |
24| **--verify** | Run `bash scripts/run-skill-verify.sh` and append health results to the stocktake report |
25 
26## Process
27 
280. **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).
290b. **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`.
301. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
312. Run mode; for each skill check: exists, verb-noun, &lt;300 lines total, HARD GATE present, INDEX row matches.
323. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
334. **Effectiveness report (--full mode only):** Read `specs/state.yaml` `metrics.skill_timings` and report:
34   - Top 5 most-used skills (by calls, total_seconds)
35   - Skills with zero calls (potential dead weight)
36   - Skills with high average time (candidates for `evolve-skill`)
375. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate.
386. **--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`.
39 
40### Skill timing data (`metrics.skill_timings`)
41 
42In `--full` mode, read `specs/state.yaml` `metrics.skill_timings` for per-skill usage stats:
43 
44```yaml
45metrics:
46  skill_timings:
47    survey-context:
48      calls: 12
49      total_seconds: 180
50      avg_seconds: 15.0
51    develop-tdd:
52      calls: 30
53      total_seconds: 5400
54      avg_seconds: 180.0
55```
56 
57Timing data is populated by `scripts/bp-timing.sh start|end <skill>` calls within critical-path skills.
58 
59## Verify
60 
61→ verify: `compgen -G 'specs/STOCKTAKE-*.md' >/dev/null && bash scripts/validate-skill-catalog.sh`
62 
63See [REFERENCE.md](REFERENCE.md) for checklist.
64 
65---
66 
67# Stocktake checklist
68 
69- [ ] SKILL.md exists at repo root `&lt;name&gt;/SKILL.md`
70- [ ] Listed in SKILL-INDEX.md with correct phase
71- [ ] `description` includes "Use when..."
72- [ ] At least one HARD GATE callout
73- [ ] specs/ output documented if applicable
74- [ ] No edit to `.cursor/rules/` or `.gemini/` (generated only)
75