| name | codebase-audit |
| description | Deep codebase audit that first reads project docs (AGENTS.md, README.md) and investigates the architecture, then systematically finds hardcoded constants that should be dynamic and unfinished code (TODOs, "will"/"would" in comments). Use this skill when the user wants a thorough code review for hygiene issues, asks to find hardcoded values, wants to audit for TODOs or incomplete code, says things like "audit this codebase", "find hardcoded stuff", "what's unfinished", "find tech debt", "code hygiene check", or asks you to look across the whole project for issues. Also use when the user asks to understand a project before making changes, or wants a comprehensive health check of their codebase. |
Codebase Audit
A systematic audit that builds deep understanding of the project before identifying problems. The understanding phase isn't just a formality -- it's what lets you distinguish "this constant is fine" from "this constant will break in production."
Phase 1: Understand the Project
Before looking for problems, you need to know what the project is and how it's built. Without this context, you'll flag things that are intentional and miss things that are actually broken.
-
Read the docs thoroughly. Start with AGENTS.md and README.md (or whatever top-level docs exist). Read them completely -- don't skim. These tell you what the project does, how it's structured, and what conventions it follows. If there's a CLAUDE.md, CONTRIBUTING.md, or architecture doc, read those too.
-
Investigate the code structure. Use code navigation to understand the technical architecture: what the main modules are, how they connect, what the entry points are, what external services it talks to. Build a mental model of the system before you start auditing it.
The goal is to understand the project well enough that you could explain its architecture to someone in 2-3 paragraphs. If you can't do that yet, keep reading.
-
Summarize your understanding. Before moving to Phase 2, briefly state what the project does and how it's structured. This forces you to crystallize your understanding and gives the user a chance to correct any misunderstandings before you start the audit.
