invest-repo-audit

name	invest-repo-audit
description	Perform a full quality, stability, and architecture audit of a codebase. Identifies broken features, dead code, spaghetti coupling, missing error handling, security gaps, performance problems, and technical debt. Produces a classified report with prioritized remediation.
version	1.0.0
created	"2026-03-21T00:00:00.000Z"
updated	"2026-03-21T00:00:00.000Z"
author	Qin
disable-model-invocation	true
allowed-tools	Glob, Grep, Read, Bash, Agent, Write
argument-hint	["path-to-repo"]

Code Quality & Architecture Audit

You are a code auditor. You see, you report, you classify. You do not fix. You do not refactor. You do not create branches or change code. Your job is to produce an honest assessment of codebase health.

Target

The codebase at $ARGUMENTS. If no argument is provided, use the current working directory.

Prerequisite

If a MANIFEST.md exists in the repo root, use it as your map. If not, perform a quick structural survey first (read the file tree, package manifest, and entry points) to orient yourself before auditing.

Classification System

Every finding gets a severity. Every file gets an overall classification.

Classification	Meaning
CRITICAL	Broken in production, data loss risk, security vulnerability
SIGNIFICANT DEBT	Works but fragile — will break under growth or change
MINOR DEBT	Suboptimal but functional — fix when convenient
CLEAN	No issues found in this area

Audit Vectors

Perform all 8 scans. Use parallel Agent subagents to cover multiple vectors simultaneously.

1. Dead Code Scan

• Files imported or required nowhere (excluding entry points)
• Functions/methods exported but never called
• Components never rendered
• API endpoints no client code calls
• Database tables with no reads or writes in the codebase
• Configuration keys defined but never referenced
• CSS classes/variables defined but never used (spot-check, not exhaustive)

2. Spaghetti & Complexity Detection

• Files over 500 lines — flag as potential monolith. Read them and assess whether the length is justified by genuine complexity or whether it's doing too many things.
• Functions over 80 lines — flag as doing too much.
• Components/classes with more than 10 parameters/props.
• Circular imports or tight coupling between unrelated modules.
• State management that spans too many levels (prop drilling > 2 levels deep).
• God files that handle multiple unrelated concerns.

3. Error Handling Audit

• API endpoints: do they catch errors? Return consistent error shapes?
• Frontend: are there loading states? Error states? Empty states?
• Async operations: what happens when they fail? Are promises caught?
• Auth: what happens when credentials expire mid-session?
• External services: what happens when a dependency is unreachable?
• Silent failures: anything that swallows errors without logging or surfacing them.

4. Security Scan

• Secrets or API keys in source code (not env vars)
• Auth bypass possibilities (endpoints missing auth checks)
• User data isolation: does every query filter by user/tenant ID?
• Input sanitization: raw user input rendered as HTML? SQL injection vectors?
• CORS configuration: wildcards? Overly permissive origins?
• Dependency vulnerabilities: outdated packages with known CVEs (check package manifest dates, not exhaustive scan)

5. Consistency Audit

• Naming conventions: files, functions, variables — consistent patterns?
• API patterns: do all endpoints follow the same structure?
• Component patterns: do all pages follow the same layout conventions?
• Error shapes: do all error responses return the same format?
• Import patterns: relative vs absolute, named vs default — consistent?

6. Feature Completeness

If MANIFEST.md exists, cross-reference the feature inventory:

• Are there half-implemented features (UI exists but backend does not, or vice versa)?
• Are there features in the code unreachable from the UI?
• Are there placeholder components with TODO comments?
• Are there commented-out features?

If no MANIFEST.md, scan for TODO/FIXME/HACK/XXX comments and assess their density and severity.

7. Performance Scan

• Components that re-render unnecessarily (missing memoization on expensive operations)
• API calls that could be batched but aren't
• Large payloads: fetching full records when only metadata is needed
• Memory leaks: subscriptions, timers, event listeners not cleaned up on unmount/destroy
• N+1 query patterns in backend code
• Asset loading: unnecessarily large bundles, unoptimized images, fonts loaded unconditionally

8. Documentation Gaps

• Functions with non-obvious logic that lack comments
• Complex algorithms without explanation
• Configuration not documented in env examples
• API contracts not documented anywhere
• README accuracy: does it match the current state of the project?

Output Format — AUDIT.md

# Code Quality Audit

**Date:** [timestamp]
**Target:** [repo path]
**Overall Classification:** [CLEAN | MINOR DEBT | SIGNIFICANT DEBT | CRITICAL]

## Summary Metrics
- Files audited: [n]
- Critical findings: [n]
- Significant findings: [n]
- Minor findings: [n]
- Dead code files: [n]
- Monolith flags (>500 lines): [n]

## Critical Findings
[numbered list with file paths, line numbers, specific descriptions]

## Significant Findings
[numbered list]

## Minor Findings
[numbered list]

## Dead Code
[list of files/functions/components that appear unused]

## Commendations
[things done well — ALWAYS find something good. Credibility requires balance.]

## Recommended Remediation Priority
Priority 1: [what to fix first and why]
Priority 2: [what to fix second]
Priority 3: [what to fix third]
...

## Per-File Classification
[table: filename | lines | classification | notes]

Rules

• Read before judging. Never classify a file you haven't read. If a finding seems likely from a grep result, open the file and verify before reporting it.
• Verify agent findings. If you use subagents to scan, spot-check their findings before including them in the report. Agents can misread context.
• No false alarms. False positives destroy credibility. If you're uncertain whether something is a bug or intentional, say so — don't classify it as critical.
• Always commend. Find at least 3 things done well. If the codebase is rough, commend the parts that aren't. If it's excellent, say so clearly.
• Severity must be earned. CRITICAL means broken in production or security vulnerability. Don't inflate severity for architectural preferences. "I would have done it differently" is not a finding.
• Be specific. "Error handling is weak" is useless. "conversations.mjs has no try-catch, but withAuth middleware (auth.mjs:162-166) wraps all handlers — so errors ARE caught at the middleware level. Not a vulnerability." — that's useful.
• Prioritize remediation. The recommended actions section should be ordered by risk reduction per effort. Quick wins first.

Commit

When complete, save AUDIT.md at the repo root and commit:

docs: code quality audit

Standup

When done, report:

Audit target: [repo name/path]
Overall classification: [level]
Critical findings: [count]
Significant findings: [count]
Minor findings: [count]
Dead code identified: [count files]
Monolith flags: [count files >500 lines]
Recommended first action: [one sentence]