Codebase Audit

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?