fxckcode Codebase Audit
What This Skill Owns
- Comparing a codebase against a spec (PRD, SDD, architecture doc)
- Identifying gaps with specific evidence (file paths, line numbers)
- Running the 7-phase verification loop as part of the audit
- Functional smoke testing every endpoint systematically
- Delivering actionable verdicts with prioritized recommendations
When to Use
- User says "review this codebase", "audit this project", "how does this compare to X"
- User drops a PRD/SDD and asks to evaluate implementation status
- Before starting work on an inherited or unfamiliar codebase
- As part of migration readiness assessment
Audit Workflow
Phase 0: Clone + Setup
- Clone the repo
- Find project docs (README, PRD, ARCHITECTURE, SITEMAP, TASKS)
- Install dependencies
- Start the project and verify it responds
- Run the test suite
Phase 1: Understand the Spec
Extract every explicit requirement from the spec. Build a mental checklist of what the spec demands.
Phase 2: Survey the Codebase
- Read the schema (this is the single most important artifact)
- Read package.json / go.mod for dependencies and scripts
- Scan module/service/controller structure
- Read key service files (auth, core domain, integrations)
- Check for Docker/devops setup
Phase 3: Gap Analysis
Compare each spec requirement against the code:
| Spec Item | Status | Evidence |
|---|---|---|
| ChannelIdentity model | MISSING | User still has whatsappNumber @unique |
| INVESTMENT enum | MISSING | Enum only has INCOME | EXPENSE |
Phase 4: Verdict
- TL;DR at the top — percentage complete, one-line assessment
- What's good — things done right, especially tests
- What's missing — gap table with evidence
- What's broken — bugs, broken configs, architectural violations
- Verdict — actionable recommendation
Polishing Variant
When user says "pulir funcionalidades con base este PRD":
- Categorize each PRD requirement as ✅ working / ⚠️ partial / ○ missing
- Focus on ⚠️ — existing but rough (inverted logic, unclear errors, untested paths)
- Explicitly defer ○ — missing features are NOT polish
- Recommend top 2-3 polish items with concrete evidence
Critical Rules
- Local code over external references — when user points to a local dir, that's the truth
- Don't trust the README — the code is the truth
- Don't assume tests pass — run them
- Don't conflate "missing" with "needs building" — may want polish, not new features
- Check the schema first — single most information-dense artifact
- Don't report on what you haven't verified — either cite the file or say you haven't checked
Pitfalls
- Skipping the schema — this is where requirements live or die
- Not running the tests — passing tests are a strong signal
- Not checking the run cycle — a project that looks complete may silently block on execution
- Trusting external docs over local code