/stocktake-skills

name: stocktake-skills
# story: e18s05
description: 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.
# story: e22s02
model: sonnet
effort: standard

story: e09s01

<!-- story: e45s12 --> <!-- story: e79s04 -->

Stocktake Skills

> **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`.

Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX mismatches.

Modes

| Mode | Scope | |------|-------| | **Quick Scan** | Skills changed since last tag or in current diff | | **Full** | All skills per SKILL-INDEX.md + catalog audit | | **--verify** | Run `bash scripts/run-skill-verify.sh` and append health results to the stocktake report |

Process

0. **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). 0b. **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`. 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding. 2. Run mode; for each skill check: exists, verb-noun, &lt;300 lines total, HARD GATE present, INDEX row matches. 3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity). 4. **Effectiveness report (--full mode only):** Read `specs/state.yaml` `metrics.skill_timings` and report:

• Top 5 most-used skills (by calls, total_seconds)
• Skills with zero calls (potential dead weight)
• Skills with high average time (candidates for `evolve-skill`)

5. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate. 6. **--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`.

Skill timing data (`metrics.skill_timings`)

In `--full` mode, read `specs/state.yaml` `metrics.skill_timings` for per-skill usage stats:

metrics:
  skill_timings:
    survey-context:
      calls: 12
      total_seconds: 180
      avg_seconds: 15.0
    develop-tdd:
      calls: 30
      total_seconds: 5400
      avg_seconds: 180.0

Timing data is populated by `scripts/bp-timing.sh start|end <skill>` calls within critical-path skills.

Verify

→ verify: `compgen -G 'specs/STOCKTAKE-*.md' >/dev/null && bash scripts/validate-skill-catalog.sh`

See [REFERENCE.md](REFERENCE.md) for checklist.