| name | code-audit |
| description | Perform comprehensive code audits on repositories or directories. Use when asked to audit code, review a codebase, analyze code quality, find bugs, check for security issues, review architecture, check SOLID/DRY compliance, or generate a code audit report. Produces well-formatted markdown reports with prioritized recommendations. |
Code Audit
Perform comprehensive code audits and generate structured markdown reports.
Workflow
- Scope: Determine target (full repo, specific path, or focused concern)
- Discovery: List and categorize source files
- Analysis: Evaluate each category systematically
- Report: Generate markdown report using template format
- GitHub Issues: Create issues using
scripts/create_issue.sh:- First: Create individual issues for each actionable recommendation
- Then: Create the full audit report with subtasks linking to each issue
Analysis Categories
| Category | What to Look For |
|---|---|
| Architecture | Separation of concerns, component structure, dependencies |
| Bugs | Race conditions, null checks, resource leaks, edge cases |
| SOLID Violations | SRP (god classes), OCP, LSP, ISP, DIP issues |
| DRY Violations | Duplicated logic, repeated patterns, copy-paste code |
| Best Practices | Magic numbers, missing docs, broad exceptions |
| Security | Input validation, credential handling, injection risks |
| Performance | O(n) issues, unnecessary copies, inefficient algorithms |
| Good Practices | Highlight what the code does well |
Severity Levels
| Level | Criteria |
|---|---|
| P0/Critical | Race conditions, security vulnerabilities, data loss risks |
| P1/High | Major bugs, architectural issues, memory leaks |
| P2/Medium | Code quality issues, moderate violations |
| P3/Low | Minor improvements, nice-to-have refactors |
Scoring
Rate each applicable category out of 10:
- Architecture, Thread Safety, Error Handling
- DRY Compliance, SOLID Compliance
- Security, Performance, Testability
Overall score: weighted average (bugs and security weighted higher).
Report Format
See references/report-template.md for the exact output structure.
Key formatting rules:
- Two-column tables for issue metadata (severity, location, impact, recommendation)
- Code blocks with language hints for all code examples
- Horizontal rules between major sections
- ASCII diagrams in code blocks for architecture
- Summary statistics table at the end
- Prioritized recommendations (P0/P1/P2/P3)
- Never use em-dashes
Output
Step 1: Create Individual Recommendation Issues
For each actionable recommendation, create a separate issue using the format in references/issue-template.md. Capture the returned issue URL for each.
bash scripts/create_issue.sh \
--project "[Project Name]" \
--title "[Brief issue title]" \
--label "code-audit,priority:[level],[category]" \
--body "$ISSUE_BODY"
Priority labels:
- P0/Critical →
priority:critical - P1/High →
priority:high - P2/Medium →
priority:medium - P3/Low →
priority:low
Category labels (use as appropriate):
security,performance,bug,technical-debtarchitecture,observability,testing,documentation
Step 2: Create Full Audit Report with Subtasks
Append a "Related Issues" section to the full report with subtasks linking to each individual issue:
## Related Issues
- [ ] #123 - Fix race condition in data index map
- [ ] #124 - Add thread safety to RedisClient
- [ ] #125 - Extract side validation utility
- [ ] #126 - Add metrics and observability
Then create the main audit issue:
bash scripts/create_issue.sh \
--project "[Project Name]" \
--title "Code Audit Report - [Project] - [Date]" \
--label "code-audit" \
--body "$FULL_REPORT_WITH_SUBTASKS"
With a specific repository, add --repo "owner/repo".
Confirm all issue URLs with the user after creation.