Skip to content
bigpowers

stocktake-skills

story: e09s01

Section titled “story: e09s01”

<!– story: e45s12 –>

Stocktake Skills

Section titled “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

Section titled “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

Section titled “Process”
  1. 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).
  2. Run bash scripts/audit-catalog.sh to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
  3. Run mode; for each skill check: exists, verb-noun, <300 lines total, HARD GATE present, INDEX row matches.
  4. Write specs/STOCKTAKE-&lt;date>.md with findings table (skill, issue, severity).
  5. 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)
  6. Critical findings → plan-work story; cosmetic → evolve-skill candidate.
  7. –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)

Section titled “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 &lt;skill> calls within critical-path skills.

Verify

Section titled “Verify”

→ verify: test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING

See REFERENCE.md for checklist.