stocktake-skills

<!-- 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. 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, <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 for checklist.

---

Stocktake checklist

• [ ] SKILL.md exists at repo root <name>/SKILL.md
• [ ] Listed in SKILL-INDEX.md with correct phase
• [ ] description includes "Use when..."
• [ ] At least one HARD GATE callout
• [ ] specs/ output documented if applicable
• [ ] No edit to .cursor/rules/ or .gemini/ (generated only)