Codebase Audit Grounding

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 "ErrorBoundary" --include="*.tsx" | wc -l

Storage usage:

grep -r "localStorage" --include="*.ts" --include="*.tsx" | wc -l

Specific library usage:

grep -r "framer-motion\|react-spring" --include="*.tsx" | wc -l

Dependency audit:

cat package.json | jq '.dependencies | keys | length'

File structure snapshot:

find src -type f -name "*.tsx" | head -20

3. Record Results in "Current State" Section

Create a section in your spec with exact numbers and file samples:

## Current State (Measured)

- Test files: 24
- Accessibility markers (aria-*): 207 instances across 18 files
- Error boundaries: 1 (at App root)
- localStorage usage: 0
- Framer Motion: 8 files
- Dependencies: 42 direct
- Key patterns: Redux for state, React Router for navigation

Include specific file examples where relevant.

4. Write Spec as Delta from Measured State

Frame all changes relative to measured baseline:

## Proposed Changes

From 207 aria instances → add 12 new markers in Modal and Form components
From 1 ErrorBoundary → add boundaries around Card components
From 0 localStorage → introduce localStorage for preferences in 1 module

Avoid describing an ideal end state. Describe the delta.

5. Include Audit Files and Commands

Document how the measurements were taken:

• List specific grep/find commands used
• Record the execution context (repo root, branch, date)
• Include the measured output as reference

Best Practices

• Be specific: "207 aria instances in 18 files" beats "many accessibility markers"
• Name files: "aria instances in Modal.tsx, Form.tsx, Button.tsx" not just a count
• Measure before you speculate: Run audits before writing any spec text
• Preserve audit evidence: Keep the grep output and commands in the spec for reproducibility
• Update audits as you go: If spec work takes days, re-run audits before finalizing
• Distinguish assumptions from measurements: Mark assumptions as such; keep audit results factual
• Tailor metrics to your goals: Different projects need different audits — choose what matters for implementation decisions

Quality Checklist

• Identified 3-5 metrics relevant to this spec's scope
• Ran quantified audits using grep/glob/find for each metric
• Recorded exact counts and sample files
• Created "Current State" section in spec with measured data
• Framed all proposed changes as deltas from measured baseline
• Included specific grep commands and execution context
• Avoided describing ideals; stayed grounded in deltas
• Re-validated audits if spec work spans multiple days

Common Pitfalls

• Skipping the audit: Assuming you know the current state. Always measure.
• Measuring wrong metrics: Auditing line count when component count matters. Choose metrics tied to your spec's goals.
• High-level counts only: Provide file names and examples, not just totals.
• Not recording audit method: Others can't validate or reproduce your measurements.
• Measuring stale code: Run audits from main/current branch in fresh checkout.
• Forgetting to compare: A good spec shows the delta, not just the current state. "From X → to Y" is stronger than "We have X."

Related Skills

• pre-commission-alignment: Fixes gaps that audit prevents. Audit is proactive; Track 0 is reactive.
• strategic-scout: Can be grounded in codebase audit results for more precise analysis.
• specification-writer: Works best paired with audit grounding to prevent ungrounded specs.
• implementation-prompt: Receives higher-quality specs when grounding is done upstream.
• gap-audit-then-fix (specification-driven-development): This skill covers the measurement phase of a gap audit — producing quantified current state. For the full pipeline including gap classification by effort tier, parallel fix dispatch with file manifests, and a GAPS.md registry, see gap-audit-then-fix in specification-driven-development.

Output

• A "Current State (Measured)" section ready to paste into a specification document, containing exact counts and file samples for each chosen metric
• The grep/find commands used, recorded in the spec for reproducibility
• A delta framing ("From X → to Y") for each measured dimension, ready to anchor proposed changes

Examples

Scenario 1: "Audit the DojoChat codebase before writing the v0.4 accessibility spec." → Current State section listing 207 aria instances across 18 files, 1 ErrorBoundary at App root, 0 localStorage usage, 8 Framer Motion files — plus the exact grep commands that produced those counts.

Scenario 2: "Ground the new test strategy spec in what tests already exist." → A report showing 24 test files, the test framework (Vitest), current coverage gaps by directory, and a delta framing showing which modules have zero coverage.

Edge Cases

• When the codebase is brand new with no existing files, skip the audit and note that all metrics start at zero — write the spec as greenfield.
• When running audits on a monorepo, scope each grep command to the specific package directory; repo-wide counts mislead when only one package is being specced.
• When the spec work spans multiple days, re-run all audits on the day of finalization — codebase changes invalidate counts taken earlier.

Anti-Patterns

• Recording only totals without file names — a count of "207" without knowing which files contain the markers gives the implementing agent nothing to act on.
• Running audits from a feature branch instead of main — branch-specific state produces measurements that won't match what the agent sees when it checks out.
• Describing an ideal end state instead of a measured delta — "we should have full test coverage" is a wish, not a spec; "from 24 test files → add 8 more covering the Modal and Form modules" is a spec.