--- name: file-audit description: | Deep code quality audit system. Use when asked to: - "Audit the codebase" - "Find unused code" - "Check for duplicates" - "Validate library usage" - "Review the entire project" Analyzes files in parallel with LSP and Context7, detecting issues, duplicates, and documentation drift. compatibility: Requires Context7 MCP server for library API validation and LSP for symbol analysis allowed-tools: LSP Read Write Bash Agent Skill AskUserQuestion mcp__context7__resolve-library-id mcp__context7__query-docs --- # file-audit > **Note:** `{skill_dir}` refers to the absolute "Skill directory" path provided in your system instructions. Comprehensive, resumable code quality audit system that analyzes every non-gitignored file in a project to build a complete inventory of symbols, dependencies, issues, and duplicates. ## Quick Start ``` /file-audit # Analyze entire project /file-audit src/ # Analyze specific directory /file-audit --resume # Resume interrupted audit /file-audit --status # Show progress /file-audit path/to/file.py # Analyze single file ``` --- ## Architecture ``` ORCHESTRATOR (you) ├── Phase 1: Discovery │ ├── git ls-files (find non-gitignored files) │ ├── Read project memory ({memory_dir}/PROJECT.md, {memory_dir}/TODO.md, {memory_dir}/LESSONS.md) │ └── Initialize queue.json │ ├── Phase 2: Parallel Analysis │ ├── Spawn 3-5 file analyzer agents IN PARALLEL │ ├── Each analyzes one file independently │ └── Collect results + extracted patterns │ ├── Phase 3: Post-Analysis │ ├── Run duplicate detection across ALL patterns │ ├── Cross-reference duplicates across files │ └── Inject duplicate issues into file entries │ └── Phase 4: Finalization ├── Assemble inventory.json ├── Generate TODOs └── Write summary ``` --- ## Orchestrator Workflow ### Step 1: Initialization Detect the memory directory using the convention in `[{skill_dir}/../../references/project-memory-reference.md](../../references/project-memory-reference.md)` (Directory Detection section). ```bash # Check for existing queue if {memory_dir}/file-audit/queue.json exists: Resume from last batch position else: # Discover files git ls-files --cached --others --exclude-standard # Read project memory (files per [{skill_dir}/../../references/project-memory-reference.md](../../references/project-memory-reference.md) Memory Files section) Read {memory_dir}/PROJECT.md, {memory_dir}/TODO.md, {memory_dir}/LESSONS.md (if exist) # Create queue Initialize {memory_dir}/file-audit/queue.json with all files as "pending" ``` ### Step 2: Parallel Processing Loop **For large projects (20+ files), use /map-reduce for structured parallel analysis:** ``` IF total_files > 20: Invoke /map-reduce with by-directory or by-batch split: - Mapper prompt = single-file analyzer prompt (adapted for multi-file chunks) - Reducer = post-analysis deduplication + cross-referencing (see Phase 3) - Each ChunkAssignment contains: list of files for that chunk, analyzer instructions, cross-reference manifest of exported symbols from other chunks - ChunkResults contain findings with confidence: "verified" or "chunk-local" - Reducer cross-validates chunk-local findings before producing final output - Fallback: if /map-reduce skill is unavailable, proceed with direct approach below IF total_files <= 20 (or /map-reduce unavailable): REPEAT until queue empty: 1. Get next batch of 3-5 "pending" files 2. Mark batch as "in_progress", save queue 3. Spawn 3-5 agents IN PARALLEL: Agent( subagent_type="general-purpose", prompt=analyzer_prompt(file_path, project_memory) ) 4. Wait for all agents to complete 5. Collect result JSONs + extracted patterns 6. Mark batch as "completed", save queue ``` ### Step 2.5: External Research Escalation 1. Scan Step 2 results for findings with issue subtype `deprecated_api`. 2. If any exist, batch the affected libraries into a single `/deep-research` invocation (via the `Skill` tool) in External mode targeting: "Evaluate migration paths from [deprecated library/API] to current alternatives." 3. Note: this research phase is distinct from the analyzer's Context7 lookup — it produces migration guidance (replacement APIs, breaking change scope, adoption risk), not deprecation detection. The Context7 lookup in Step 2 handles detection; this step handles remediation guidance. 4. Append the research report path to the relevant findings before Step 4 inventory assembly. ### Step 3: Post-Analysis Duplicate Detection ``` 1. Collect ALL patterns from ALL file results 2. Build hash → pattern index 3. For each hash with multiple occurrences: - Create duplicate issue - Reference all locations 4. Inject duplicate issues into relevant file entries ``` ### Step 4: Finalization ``` 1. Assemble master inventory.json 2. Generate summary statistics: - Total files analyzed - Issues by category (unused_code, incorrect_usage, duplication, documentation_drift) - Issues by diagnostic level (error, warning, info) 3. Generate consolidated TODO list 4. Write {memory_dir}/file-audit/inventory.json ``` --- ## Single-File Analyzer Prompt Template When spawning a file analyzer agent, use this prompt structure: ```markdown You are a single-file code analyzer. Analyze the following file deeply and return structured JSON. ## File to Analyze Path: {file_path} Language: {language} ## Project Context Dependencies: {project_dependencies} Project Memory: - PROJECT.md: {project_md_summary} - TODO.md: {todo_md_summary} - LESSONS.md: {lessons_md_summary} ## Your Task 1. **Read the file** completely 2. **LSP Symbol Analysis** - Use `LSP(operation="documentSymbol", filePath="{file_path}", line=1, character=1)` to enumerate symbols - For each symbol: - `hover` for type info - `findReferences` to check usage (zero refs = potentially unused) - `outgoingCalls` to map dependencies 3. **Dependency Extraction** - Parse imports/requires - Categorize: project file | external library | stdlib 4. **Library Usage Validation** (for external libraries) - Use Context7 `resolve-library-id` then `query-docs` - Check for: deprecated APIs, wrong signatures, missing error handling 5. **Documentation Drift Check** - Compare code behavior vs PROJECT.md claims - Flag mismatches 6. **Pattern Extraction** - Extract functions >5 lines, regexes, magic constants - Normalize (strip comments, whitespace) - Hash each pattern 7. **Return JSON** in this exact format: ```json { "path": "{file_path}", "purpose": "One-sentence description of what this file does", "analyzed_at": "ISO timestamp", "symbols": [ { "name": "function_name", "type": "function|class|variable", "signature": "type signature if available", "line": 15, "used_by": ["path:line", ...], "calls": ["path:function", ...] } ], "external_dependencies": [ { "library": "library_name", "functions_used": ["func1", "func2"], "usage_assessment": "correct|deprecated_api|wrong_signature", "notes": "explanation if issue" } ], "issues": [ { "type": "unused_code|incorrect_usage|documentation_drift", "subtype": "unreferenced_function|deprecated_api|code_doc_mismatch|...", "diagnostic_level": "error|warning|info", "location": {"line": 45, "end_line": 67}, "description": "Human-readable description", "evidence": "What evidence supports this (LSP output, Context7 docs, etc)", "suggested_fix": "How to fix this" } ], "patterns": [ { "hash": "sha256_first_12_chars", "name": "descriptive_name", "type": "function|regex|constant", "location": {"line": 23, "end_line": 35}, "normalized_content": "normalized code for comparison" } ] } ``` IMPORTANT: - Be thorough: this is a deep audit - Evidence-based: every issue must have concrete evidence - No false positives: only flag issues you're confident about - Do not fabricate findings — false positives cost more than missed issues. Reporting zero issues for a well-written file is the correct outcome, not a sign of insufficient review. ``` --- ## Output Files ### {memory_dir}/file-audit/queue.json ```json { "status": "in_progress|completed", "total_files": 150, "completed": 45, "current_batch": ["src/api/routes.py", "src/auth/login.py"], "started_at": "2026-01-10T14:00:00Z", "files": [ {"path": "src/auth/login.py", "status": "completed", "analyzed_at": "..."}, {"path": "src/api/routes.py", "status": "in_progress"}, {"path": "src/utils/helpers.py", "status": "pending"} ] } ``` ### {memory_dir}/file-audit/inventory.json ```json { "project": "project-name", "analyzed_at": "2026-01-10", "summary": { "total_files": 150, "total_symbols": 1234, "issues_by_diagnostic_level": {"error": 5, "warning": 23, "info": 45}, "issues_by_type": { "unused_code": 12, "incorrect_usage": 8, "duplication": 15, "documentation_drift": 3 } }, "files": [ { "...file analysis results..." } ], "pattern_registry": { "abc123": { "name": "email_validation_regex", "occurrences": ["src/auth/login.py:23", "src/auth/register.py:34"] } }, "todos": [ { "file": "src/auth/login.py", "issue_type": "unused_code", "action": "Remove `legacy_auth` function", "classification": "needs-fix" } ] } ``` --- ## Issue Types ### unused_code - `unreferenced_function`: Function has zero references (LSP findReferences empty) - `unreferenced_variable`: Variable assigned but never read - `dead_import`: Import statement not used in file ### incorrect_usage - `deprecated_api`: Using deprecated function/method (Context7 flagged) - `wrong_signature`: Incorrect parameters passed (Context7 mismatch) - `missing_error_handling`: Function raises but not caught ### duplication - `exact_duplicate`: Identical code (content hash match) - `near_duplicate`: Very similar code (structural hash + >80% similarity) ### documentation_drift - `code_doc_mismatch`: Code behavior differs from PROJECT.md claims - `missing_feature`: Documented feature not implemented in code - `undocumented_feature`: Significant code without documentation --- ## Diagnostic Levels | Diagnostic Level | Criteria | Classification | |-----------------|----------|---------------| | **error** | Broken code, security vulnerability | Requires immediate action (needs-fix) | | **warning** | Deprecated API, unused code, duplicates | Requires action (needs-fix) | | **info** | Style issue, minor optimization | Review and decide (needs-input if architectural, needs-fix if stylistic) | ### Step 4.25: Finding Fidelity Check After writing inventory.json, verify no findings were lost during consolidation. Count the total issues discovered across all analyzed files (from per-file analysis results) and compare against the total todos in the inventory's `todos` array. If the todo count is less than the discovered issue count, findings were dropped during consolidation - investigate and restore them before proceeding. This is the same principle as the Reconcile step in pr-review and plan-review. ### Step 4.5: Needs-Input Resolution After writing inventory.json, check the generated TODO list for items classified as `needs-input`. If any exist, present them to the user before exiting. Do NOT exit with unresolved `needs-input` items. Present each `needs-input` item individually via AskUserQuestion. Each item gets its own question with full context. Batch up to 4 per call: ``` AskUserQuestion(questions=[ { "question": "[{file}:{issue_type}] {action}\n\nDiagnostic: {diagnostic_level}\nDecision needed: {input_needed}\n▸dp:file={file},line=0,cat={issue_type},skill=file-audit", "header": "{file}", "options": [ ... (map each element from the finding's `options` array to {label, description}), {"label": "Defer", "description": "Skip for now — user-deferred"} ], "multiSelect": false }, ... (one question per item, up to 4 per call) ]) ``` When `options` is `null` (findings from pipelines without a verifier), fall back to the binary: `[{"label": "Fix"}, {"label": "Defer"}]`. File-audit has no Finding Verifier — the Lead applies the de-escalation test from `[{skill_dir}/../../references/finding-classification.md](../../references/finding-classification.md)` inline before presenting to the user. If the finding has a single correct resolution, reclassify to `needs-fix` and fix it. If more than 4 `needs-input` items exist, make multiple AskUserQuestion calls. For each `needs-input` TODO: - **Option selected (any non-Defer option):** Promote to `needs-fix` in inventory.json. Record the selected option label in the finding's `suggested_fix` field. - **Defer selected:** Update classification to `user-deferred` in inventory.json. If zero `needs-input` TODOs exist, skip this step. If AskUserQuestion is unavailable, treat `needs-input` items as `needs_context` in the inventory (surface them, don't hide them). --- ## Resume Logic When `/file-audit --resume` is invoked: 1. Read `{memory_dir}/file-audit/queue.json` 2. Find files with `status: "pending"` or `status: "in_progress"` 3. Reset any `in_progress` to `pending` (they were interrupted) 4. Continue from next pending batch 5. Collect new results + merge with existing partial inventory --- ## LSP Fallback When LSP is unavailable for a file type: 1. Use regex-based symbol extraction (see lsp-navigation skill for patterns) 2. Use grep for reference finding (higher false positive rate) 3. Mark in output: `"analysis_method": "regex_fallback"` 4. Skip type information: `"type_info_available": false` --- ## Best Practices 1. **Run incrementally**: For large codebases, audit in directory chunks 2. **Check queue status**: Use `/file-audit --status` to monitor progress 3. **Review todos first**: Generated TODOs are ordered by classification (needs-fix before needs-input) 4. **Trust but verify**: Issues are evidence-based but review before bulk fixes 5. **Update project memory**: If drift detected, decide whether to update code or docs 6. **Large projects**: For 20+ files, /map-reduce provides structured chunk tracking, retry-on-failure for individual mapper agents, and reducer-based deduplication of cross-chunk findings --- ## Integration with Project Memory The analyzer reads project memory files (detected per `[{skill_dir}/../../references/project-memory-reference.md](../../references/project-memory-reference.md)`) to: 1. **Understand intended behavior**: `PROJECT.md` describes architecture and decisions 2. **Check for drift**: Compare code vs documented intent 3. **Identify stale docs**: Flag when code changed but docs didn't 4. **Understand priorities**: `TODO.md` shows active work 5. **Apply lessons**: `LESSONS.md` provides principle-level context for the project This enables detection of `documentation_drift` issues that pure code analysis would miss. --- ## References - [references/analyzer-prompt.md](./references/analyzer-prompt.md) — Single-file deep analyzer prompt template - [references/inventory-schema.json](./references/inventory-schema.json) — JSON Schema for `{memory_dir}/file-audit/inventory.json` - [references/issue-types.md](./references/issue-types.md) — Detailed issue type and subtype taxonomy