| name | sb-audit |
| description | Periodic Storybook audit — naming-drift survey, archived/decision-board review, lifecycle tagging, usage refresh. Use for 'audit my Storybook', 'find drift', 'show pending decisions', or a periodic catalog health check. |
| compatibility | Requires bash and python3; git optional (decision-board date fallback in audit-archived/prune-to-ledger). |
| allowed-tools | Bash Read Glob Grep Write |
| license | MIT |
| metadata | {"author":"strongeron","version":"2.3.0","bundle":"storybook-workbench","vendor":{"scripts":["audit-drift.sh","audit-archived.sh","find-stories-by-tag.sh","prune-to-ledger.sh","extract-component-usage.sh","audit-controls.sh","refresh-usage.sh"],"wrappers":false,"references":["galleries-and-tags.md","lifecycle-tags.md","propagate-workflow.md","anti-patterns.md"],"templates":["design-decisions.md"]}} |
sb-audit — drift survey + decision board
The periodic gate. Surveys the catalog, seeds the ledger, names consolidation candidates.
Run it
SKILL=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
CORE=${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}
"$SKILL/scripts/audit-drift.sh"
"$SKILL/scripts/audit-archived.sh"
"$CORE/scripts/find-stories-by-tag.sh" decision:pending
"$CORE/scripts/extract-component-usage.sh"
"$SKILL/scripts/audit-controls.sh" .
"$CORE/scripts/refresh-usage.sh" --docs .
[ -f .storybook/scripts/extract-app-graph.mjs ] && node .storybook/scripts/extract-app-graph.mjs
[ -f .storybook/app-graph.json ] && node -e 'const g=require("./.storybook/app-graph.json"); const by={}; for(const e of g.edges) by[e.attribution]=(by[e.attribution]||0)+1; console.log("flow edges by attribution:", by, "| unresolved:", g.unresolvedEdges.length); for (const u of g.unresolvedEdges) console.log(" UNRESOLVED", u.provenance, "→", u.to, "—", u.reason)'
Sequence — don't run all six cold. Start with audit-drift.sh (cheap, names consolidation
candidates). The HEAVY audit-archived.sh L1/L2/L3 scan only earns its cost once the catalog is
sizable — skip it under ~20 chosen stories (nothing to prune yet). Run audit-controls.sh +
extract-component-usage.sh when you're checking coverage; refresh-usage.sh --docs is the
all-in-one rendered refresh — run it last, not alongside the individual extractors it supersedes.
One-command usage refresh. refresh-usage.sh runs all four extractors (inventory/token map,
component prop-usage, routes, design-system health — every rendered file; see CONTEXT.md
§STORAGE MAP) and — with --docs — re-stamps every <Name>.usage.mdx. The autodocs
import the JSON, so a Storybook rebuild after this reflects current reality with no hand-editing. Trigger
it three ways: per-script (here, or call one extractor directly), every audit (this step), or in CI before
storybook build. The usage prop on StateGrid/StateMatrix reads the same JSON to badge each
variant cell with its real call-site count (declared-but-unused → struck through).
Auto-refresh usage (no human authoring). Re-running extract-component-usage.sh here keeps
component-usage.json current as the app changes; the usage-profile.mdx autodocs read that JSON at
build time, so the "real usage in this app" tables update themselves on the next Storybook build. Wire
the same one-liner into CI for repos that want it always fresh. If usage shifted (a variant that was
declaredButUnused is now shipped, or vice-versa), flag the affected stories' usage:unused tags as a
drift finding.
Decide (ask yourself)
- Drift — 17 names for "empty state" → consolidation candidate; 1 cluster → noise, ignore.
- Archive —
audit-archived.sh flags >20 chosen stories → prune to the durable ledger seeded from
templates/design-decisions.md ($SKILL/scripts/prune-to-ledger.sh); otherwise leave it.
- Pending decisions — stale
decision:pending → remind stakeholders.
- Controls coverage —
audit-controls.sh flags component stories that pass args but wire neither
argTypes nor a controls-disable (so they expose no usable Controls panel), and warns if
.storybook/manager.ts doesn't showPanel. Fix by wiring argTypes (unions → select, flags →
boolean, group via table.category, hide non-serializable props) — or disabling controls on
render-only stories — per the Controls pattern in sb-stories (its without-mcp reference, §13).
- Flow / app-graph drift — the validate step above prints edges-by-attribution + every
UNRESOLVED. If unresolvedEdges grew, or a new entry's reason is "dynamic dispatch" / a nav idiom
the extractor doesn't parse, that's a real edge being dropped — the app added a navigation
pattern the script misses. Work the under-extraction loop in sb-flows (flow-capture.md), extend
the repo-local extract-app-graph.mjs, re-validate. Never accept a silently shrinking map: an edge
with no source is unresolved, not absent. (Same JSON also feeds the component lists — a component
that lost all parents/pages is a dead-component or import-trace finding.)
Load references/galleries-and-tags.md when scaffolding a TagGallery,
references/lifecycle-tags.md for archive/deprecation, references/propagate-workflow.md
when a prune candidate appears, references/anti-patterns.md when reviewing AI-generated stories
(the full list — mega-stories, inline mocks, CSF2, pseudo-class misuse) — pick based on what surfaced, don't load all four.
Ledger (durable memory you steer)
Append findings to .storybook/audit/findings.md (timestamped, append-only). Log-only rule: a
real prod issue out of scope for the story pass (unassociated <label>, sub-AA contrast, headless
crash) gets a LOG-ONLY: marker — record it, keep moving, don't touch app code unless asked. After
seeding the ledger, prompt to commit it (git add .storybook/audit/) — an uncommitted ledger is
one git clean from gone.
Next
/sb-hub → usually a sb-stories consolidation pass or a sb-ship for a graduated Explore.
