/codebase-audit

name: codebase-audit
description: Perform a full codebase review, categorize findings by severity, file GitHub issues, then fix each issue in an isolated git worktree and submit PRs. Use this skill when the user asks to audit the codebase, do a comprehensive code review, find and fix security/quality/reliability issues, or run a proactive health check across the entire repository.
alwaysApply: false

Codebase Audit → Issue → Worktree Fix → PR

End-to-end workflow: systematically review the entire codebase, report findings as GitHub issues, fix each issue in an isolated git worktree, and submit PRs — all in one session.

When to use this skill

Use this skill when you need to:

• Perform a full code review / audit of the codebase
• Proactively find security vulnerabilities, logic bugs, or code quality problems
• Turn code review findings into tracked GitHub issues
• Fix each issue in isolation (worktree per issue) and submit PRs
• Run a periodic codebase health check with automated follow-through
• Audit and fix dependency security vulnerabilities (Dependabot alerts / npm audit)

**Do NOT use for:**

• Reviewing or fixing a single known bug (use `systematic-debugging` or direct fix)
• Triaging existing open PRs (use `pr-review-fix`)
• Processing attribution issues (use `mcp-attribution-worktree`)
• Feature development or refactoring unrelated to audit findings

Workflow

Phase 1 — Review

1. Read `references/review-strategy.md` for the review scope and checklist. 2. Use the `code-explorer` subagent to read ALL source files in the target directory (default: `mcp/src/`). 3. For each file, systematically check against the review checklist:

• **Security**: path traversal, injection, unvalidated input, hardcoded secrets, improper error exposure
• **Error handling**: missing try-catch, swallowed errors, error messages leaking internals
• **Type safety**: `as any`, unsafe casts, missing null checks
• **Logic bugs**: race conditions, incorrect conditionals, unreachable code
• **Code quality**: dead code, duplication, overly complex functions
• **Resource leaks**: unclosed connections, missing cleanup
• **API design**: inconsistent validation, missing required field checks

4. Record every finding with: file path, line number(s), category, severity (Critical/High/Medium/Low), description, and suggested fix. 5. **Dependency scan**: Read `references/dependency-audit.md` and run the Dependabot alert fetch + `npm audit` to discover vulnerable dependencies. Record each finding using the dependency-audit format.

Phase 2 — Analyze & Classify

1. Read `references/classification.md` for severity definitions and grouping rules. 2. Deduplicate findings — merge instances of the same pattern across files. 3. Group findings into **fix batches** — related issues that should be fixed together in one PR. 4. Assign severity and priority:

• **P0 (Critical)**: Security vulnerabilities, data loss risks
• **P1 (High)**: Logic bugs, error handling gaps that cause runtime failures
• **P2 (Medium)**: Type safety, code quality issues affecting maintainability
• **P3 (Low)**: Style, naming, minor cleanup

5. Present a structured audit report to the user and wait for confirmation before proceeding.

Phase 3 — Create GitHub Issues

1. Read `references/issue-workflow.md` for issue creation guidelines. 2. For each fix batch (or individual Critical finding), create a GitHub issue:

   gh issue create --title "<type>(<scope>): <summary>" --body "<structured body>" --label "<severity>,<category>"

3. Issue body must include: affected files, line numbers, problem description, expected behavior, and suggested fix approach. 4. Link related issues when findings are connected. 5. Present the created issues to the user.

Phase 4 — Worktree Fix

1. Read `references/worktree-fix.md` for the isolation and fix procedure. 2. For each issue (in priority order): a. Create an isolated worktree and branch:

      git worktree add ../<repo>-audit-fix-<issue-number> -b fix/<slug>-<issue-number> origin/main

b. Work inside the worktree — never in the main checkout. c. Implement the fix, keeping changes minimal and focused. d. Verify locally: `cd mcp && npm run build && npm run test` e. Commit with conventional-changelog format:

      git commit -m 'fix(<scope>): 🔒 <english description>

      Closes #<issue-number>'

f. Push and create PR:

      git push github fix/<slug>-<issue-number>
      gh pr create --title "fix(<scope>): 🔒 <summary>" --body "Closes #<issue-number>\n\n<description>" --base main

g. Remove the worktree after PR is created:

      cd <original-dir>
      git worktree remove ../<repo>-audit-fix-<issue-number>

3. One worktree per issue. Never mix fixes across worktrees. 4. **Dependency fixes**: For dependency vulnerability batches, follow `references/dependency-audit.md` Step 4. These can be grouped into a single PR since they modify `package.json` / `package-lock.json`.

Phase 5 — Verify & Report

1. Read `references/verification.md` for the verification checklist. 2. Check CI status for each PR:

   gh pr checks <number>

3. If CI fails, re-enter the worktree, fix, and push again. 4. Generate a final audit report summarizing:

• Total findings by category and severity
• Issues created (with links)
• PRs submitted (with links)
• Remaining items that need human decision

Routing

| Task | Read | | --- | --- | | What to review and how to check each category | `references/review-strategy.md` | | Security severity classification (TSRC-style) | `references/security-severity-checklist.md` | | How to classify, deduplicate, and batch findings | `references/classification.md` | | How to create well-structured GitHub issues | `references/issue-workflow.md` | | How to create worktrees and fix issues in isolation | `