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: ```bash 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: ```bash 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: ```bash git commit -m 'fix(<scope>): 🔒 <english description> Closes #<issue-number>' ``` f. Push and create PR: ```bash 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: ```bash 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: ```bash 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 | `references/worktree-fix.md` | | How to verify fixes and generate the final report | `references/verification.md` | | How to audit and fix dependency vulnerabilities | `references/dependency-audit.md` | ## 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?