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.