| name | codebase-audit-grounding |
| model | sonnet |
| description | Produces a quantified current-state report (test count, aria markers, error boundaries, storage usage, dependencies) used to anchor specifications in measured reality rather than assumptions. Use when: 'audit the codebase before speccing', 'ground this spec in reality', 'what does the code actually look like', 'measure before I write the spec'. |
| category | specification-driven-development |
| triggers | ["audit the codebase before speccing","ground this spec in reality","what does the code actually look like","measure before I write the spec"] |
| tier | 1 |
| agents | ["primary"] |
| tool_dependencies | ["file_system"] |
| inputs | [{"name":"repo_path","type":"string","description":"Path to the codebase to audit before specification","required":true}] |
| outputs | [{"name":"audit_report","type":"string","description":"Quantified current-state report with test count, aria markers, error boundaries, storage usage, and dependencies"}] |
Codebase Audit Grounding
Philosophy
Specifications should describe deltas from measured reality, not deltas from ideals. A spec grounded in quantified codebase state ("207 aria instances, 24 test files, 0 localStorage usage") produces more precise implementation guidance than a spec describing an imagined end state. This prevents the gap between assumption and reality that causes rework.
The pattern emerged from direct evidence: v0.2.4 specs that included measured codebase audits required zero Track 0 remediation, while v0.2.2 specs written without grounding required significant correction. Measured state → better spec → better implementation.
When to Use
Activate this skill when:
- Writing any specification that describes changes to an existing codebase
- Before handing off work to an autonomous implementation agent
- Grounding a strategic scout or analysis in actual codebase reality
- Competing interpretations exist about "current" state
- A spec will guide architectural changes or dependency decisions
- Prevention of Track 0 remediation is a priority
Workflow
1. Identify What to Measure
Determine which metrics matter for your project type:
- Test coverage: Test file count, test patterns, coverage gaps
- Accessibility: aria-* instances, semantic HTML patterns
- Error handling: ErrorBoundary components, try-catch blocks, error patterns
- State management: localStorage usage, context providers, state patterns
- Dependencies: Specific library usage counts, version patterns, plugin ecosystems
- Architecture: Component hierarchy, file structure, naming conventions
2. Run Quantified Audits
Use grep, glob, and language-specific tools to measure actual patterns. Record exact counts and file lists.
Test count:
find . -name "*.test.*" -o -name "*.spec.*" | wc -l
Accessibility markers (React example):
grep -r "aria-" --include="*.tsx" --include="*.jsx" | wc -l
Error boundary usage:
grep -r --include= | -l
