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

Git safety rules

• Never force-push unless explicitly asked.
• Never amend commits that are already pushed.
• Always work inside the worktree, not the main checkout.
• Always verify build + test locally before pushing.
• One worktree per issue — never mix fixes.
• Clean up worktrees after PR creation.

Commit conventions

Follow the project's conventional-changelog format:

fix(<scope>): 🔒 <english description>

Closes #<issue-number>

Scope examples: security, deps, error-handling, type-safety, code-quality, cloudrun, database, functions

Minimum self-check

• Did I review ALL source files in the target scope, not just a sample?
• Did I categorize each finding with file, line, severity, and description?
• Did I present the audit report and get user confirmation before creating issues?
• Did I create a separate GitHub issue for each fix batch?
• Did I use an isolated worktree for each fix, not the main checkout?
• Did I verify build + test pass before pushing each fix?
• Did I clean up worktrees after creating PRs?
• Did I generate a final report with links to all issues and PRs?
• Did I check Dependabot alerts and npm audit for dependency vulnerabilities?
• Did I apply the correct fix strategy (upgrade / override / replace / dismiss) for each vulnerable dependency?