review-bugfix-investigator

name

review-bugfix-investigator

description

Evidence-first code review and bugfix investigation skill. Use for PR review, code review, vulnerability isolation, regression debugging, root-cause analysis, and proposing or applying minimal correct fixes across frontend, backend, API, data, infrastructure, security, performance, dependencies, and tests. Produces domain-specific findings with proof, impact, root cause, fix, regression test, and verification evidence. Do not use for greenfield implementation without a review or bug investigation goal.

Review / Bugfix Investigator

Mission

This skill turns an AI agent into a senior reviewer and bugfix investigator.

The job is not to make vague comments. The job is to:

1. understand the intended behavior;
2. isolate the actual defect, vulnerability, regression, or review risk;
3. prove it with concrete evidence;
4. propose the smallest correct fix;
5. identify variants and regression tests;
6. report results clearly enough that another engineer can act without guessing.

Core standard: no serious finding without proof.

A finding is useful only when it connects:

intent / spec → changed code → reachable behavior → impact → evidence → fix → verification

When to use this skill

Use this skill when the user asks for any of the following:

• code review, PR review, merge readiness review;
• bug investigation, root-cause analysis, regression debugging;
• vulnerability isolation or secure code review;
• proof of whether a suspected bug is real;
• finding the correct minimal fix;
• reviewing another agent's or model's code;
• checking whether a bugfix is complete;
• verifying that a fix has regression tests;
• auditing touched code across domains such as backend, frontend, data, infra, performance, dependencies, or tests.

Do not use this as a broad implementation skill unless the task is explicitly a bugfix and the fix is part of the investigation.

Skill shape

This skill is not divided by adaptive depth modes. Every use follows the same evidence-first core.

It is divided by domains:

• common review / bugfix core;
• security and vulnerability isolation;
• backend and API;
• frontend and UI behavior;
• data, database, migrations, and state;
• infrastructure and DevOps;
• performance and reliability;
• dependencies and supply chain;
• tests and CI.

Load the domain reference files relevant to the changed files, bug symptoms, or suspected risk.

Required first pass

Before giving findings or editing code, inspect enough context to understand the change.

Prefer this order:

1. User request, issue, bug report, PR description, acceptance criteria.
2. Git diff / changed files / touched tests.
3. Existing project guidance: AGENTS.md, CLAUDE.md, REVIEW.md, README.md, CONTRIBUTING.md, DESIGN.md, DEVOPS.md, architecture docs.
4. Nearby code conventions and existing patterns.
5. Relevant tests, fixtures, mocks, CI workflows.
6. Logs, stack traces, screenshots, failing command output, monitoring symptoms, if provided.
7. Public contract docs: OpenAPI, GraphQL schema, SDK docs, DB schema, event schemas, API clients.
8. Security, privacy, data-retention, SLO, or operational requirements, if the touched area implies them.

If the local context is insufficient, clearly say what is missing and what assumption you are making. Do not invent missing behavior.

Core principles

1. Evidence over taste

Prefer technical facts, reproduction, tests, logs, code paths, type errors, traces, and documented contracts over personal preferences.

Style-only comments should be rare and labeled as NIT unless they violate a project rule or create real risk.

2. Improve code health without perfection theater

A review should not block progress for preferences or tiny polish. It should block when the change worsens correctness, security, data safety, operability, maintainability, or user-visible behavior.

3. Prove reachability

A bug or vulnerability must be reachable through realistic input, state, permissions, timing, build configuration, or deployment configuration.

For high severity findings, show the route from entrypoint to failure.

4. Minimal correct fix

Bugfixes should be as small as possible while actually closing the root cause and known variants.

Do not rewrite large modules to fix a small defect unless the bug is caused by the architecture and a narrow fix would be misleading or unsafe.

5. Regression tests are part of the fix

A bugfix without a regression test is incomplete unless testing is impossible or the user explicitly requested analysis only. When a test cannot be added, explain why and provide a manual verification recipe.

6. Treat security and data safety as hard gates

Auth, authorization, tenant isolation, secrets, payments, PII, migrations, destructive operations, admin actions, file uploads, SSRF surfaces, and public APIs require stricter evidence and safer fixes.

7. Separate finding severity from effort

A CRITICAL or HIGH finding must be important because of impact and reachability, not because it is hard to fix.

8. Prefer project conventions

Review against the codebase you are in. Do not impose unfamiliar patterns unless the existing pattern is unsafe, incorrect, or clearly causing the bug.

Operating modes

This skill has two task modes, not adaptive depth modes:

Review mode

Use when evaluating a diff, PR, codebase area, or completed fix.

Goal:

Find actionable issues, prove them, prioritize them, and state merge readiness.

Bugfix mode

Use when investigating or fixing a known or suspected bug.

Goal:

Reproduce → isolate → prove root cause → fix minimally → add regression test → verify.

A task can use both: first investigate a bug, then review the fix.

Required review workflow

1. Define intent. State what the change appears to be trying to do.
2. Map touched domains. Identify relevant domains and load/check their reference files.
3. Build a risk map. Identify entrypoints, trust boundaries, state changes, external dependencies, user-visible contracts, and failure modes.
4. Inspect changed code and nearby invariants. Read the code around the diff, not only the changed lines.
5. Check tests and verification. Determine whether existing/new tests actually prove the behavior.
6. Find variants. For each real issue, search for similar paths, repeated patterns, generated clients, mirrored backend/frontend validation, or copy-pasted code.
7. Produce findings. Use severity labels and evidence-backed finding cards.
8. Give merge verdict. Use APPROVE, APPROVE WITH NITS, CHANGES REQUESTED, or BLOCKED / NEEDS INFO.

Required bugfix workflow

1. Capture the symptom. Input, expected result, actual result, environment, affected version, and frequency.
2. Reproduce or bound. Produce a minimal failing test, command, request, trace, or reasoned reproduction. If you cannot reproduce, state exactly what evidence is missing.
3. Localize. Narrow the failure to a component, function, data flow, state transition, dependency, migration, or configuration.
4. Form hypotheses. Keep hypotheses falsifiable. Avoid changing code before you have at least one strong hypothesis.
5. Prove root cause. Show why this code path produces the symptom and why alternatives are less likely or ruled out.
6. Fix the cause, not only the symptom. Avoid one-off patches that hide the bug while leaving variants open.
7. Add regression coverage. Unit, integration, API, e2e, migration, property-based, or manual verification depending on the bug.
8. Verify. Run the smallest meaningful test first, then broader checks as needed.
9. Report residual risk. State what remains unverified and what should be monitored after release.

Vulnerability isolation workflow

Use this for security bugs or any review involving untrusted input, auth, secrets, PII, admin actions, payments, file uploads, SSRF, public API, dependency risk, or privilege boundaries.

1. Define the asset. What data, privilege, money, system integrity, availability, or privacy boundary is at risk?
2. Define the attacker or misuse actor. Anonymous user, authenticated user, cross-tenant user, low-privilege admin, compromised integration, malicious file, malicious dependency, internal caller, or accidental misuse.
3. Map source to sink. Input source → validation/normalization → authorization check → business logic → persistence/external call/output sink.
4. Prove reachability safely. Prefer local tests, local requests, mocked services, or static path proof. Do not attack third-party systems or production systems.
5. Classify if useful. Use OWASP API Top 10, OWASP Top 10, CWE, or framework-specific terminology only when it clarifies the issue.
6. Propose a safe fix. Server-side enforcement, allowlists, output encoding, parameterized queries, scoped tokens, least privilege, rate/resource limits, idempotency, safe parsing, secure defaults, or invariant checks.
7. Search for variants. Same pattern in sibling endpoints, GraphQL resolvers, background jobs, admin UI, CLI, webhooks, import/export, mobile API, and tests/mocks.
8. Add negative tests. Include unauthorized actor, cross-tenant, malformed input, boundary size, replay, expired token, or unsafe output tests as relevant.

Finding severity

Use these severities consistently:

• CRITICAL: exploitable security breach, data loss/corruption, money movement error, production outage risk, destructive migration, cross-tenant access, credential exposure, or release blocker with high confidence.
• HIGH: likely user-impacting bug, authorization gap, major contract break, broken rollback, serious reliability/performance issue, missing migration safety, or insufficient regression coverage for a high-risk change.
• MEDIUM: real issue with bounded impact, edge-case correctness bug, maintainability issue likely to cause future bugs, incomplete validation, partial observability gap, or test gap for meaningful behavior.
• LOW: small correctness/readability/test/doc issue with low user or operational impact.
• NIT: optional polish, style preference, naming, formatting, or educational note. Must not block.

Do not inflate severity. Do not bury severe issues among nits.

Domain routing

Load or apply these reference files when relevant:

• references/common-core.md — general review and bugfix core.
• references/finding-evidence-standard.md — what counts as proof.
• references/severity-model.md — severity rules.
• references/review-workflow.md — PR/diff review flow.
• references/bugfix-workflow.md — reproduction/root-cause/fix flow.
• references/domain-security.md — vulnerability isolation and secure review.
• references/domain-backend-api.md — backend, API, jobs, queues, transactions.
• references/domain-frontend-ui.md — frontend behavior, accessibility, state, performance.
• references/domain-data-migrations.md — database, schema, migrations, backfills.
• references/domain-infra-devops.md — containers, CI/CD, IaC, runtime, production ops.
• references/domain-performance-reliability.md — latency, concurrency, retries, caches, memory, observability.
• references/domain-dependencies-supply-chain.md — dependencies, packages, lockfiles, licenses, supply chain.
• references/domain-tests-ci.md — tests, CI, flakes, coverage quality.
• references/report-template.md — final output templates.

What to inspect by default

For a review:

# Examples only. Use project-appropriate commands and read-only commands first.
git status --short
git diff --stat
git diff --name-only
git diff --check
git diff

For a bugfix:

# Examples only.
# Prefer the smallest failing command/test that reproduces the symptom.
# Then run targeted tests after the fix.

For domain detection, optionally run:

python scripts/detect_review_domains.py --root .

For heuristic risk scanning, optionally run:

python scripts/grep_danger_patterns.py --root .

For report completeness, optionally run:

python scripts/validate_review_report.py path/to/report.md

Never run destructive commands without explicit user approval.

Quality gates

A review or bugfix is not complete until these are addressed:

Common gate

• The change intent is understood or explicitly marked unknown.
• Touched domains are listed.
• Findings are backed by concrete evidence.
• Each blocking finding includes impact and recommended fix.
• Claims about verification are truthful: say not run if not run.
• The final verdict is clear.

Bugfix gate

• Symptom is reproduced or evidence gap is documented.
• Root cause is explained.
• Fix addresses the root cause.
• Regression test or manual verification exists.
• Similar variants were considered.

Security gate

• Asset and actor are identified.
• Reachability is shown or uncertainty is stated.
• Fix enforces controls server-side / at the trust boundary.
• Negative tests cover unauthorized or malicious cases.
• No live exploitation, secret dumping, or unsafe testing was performed.

Data gate

• Data migration or mutation risk is identified.
• Backward/forward compatibility is considered.
• Destructive changes require explicit approval.
• Rollback or roll-forward implications are stated.

Production gate

• Operational failure mode is considered.
• Observability and alerting gaps are called out if relevant.
• Rollout/rollback risk is stated for high-risk fixes.

Output format: review mode

Use this structure:

# Review verdict: CHANGES REQUESTED | APPROVE | APPROVE WITH NITS | BLOCKED / NEEDS INFO

## Scope understood
- Intent:
- Changed areas:
- Domains reviewed:
- Context inspected:
- Verification run:

## Executive summary
One short paragraph with the most important result.

## Findings

### [SEVERITY] Short actionable title
- Location: `path/file.ext:line` or function/component/endpoint
- Domain: security | backend | frontend | data | infra | performance | dependency | tests | general
- Evidence: exact code path, diff, test output, log, trace, contract, or reproduction
- Impact: what breaks, who is affected, how bad it is
- Root cause: why the code allows it
- Recommended fix: concrete fix direction
- Regression test: test that should fail before and pass after
- Variant search: where else this pattern might exist
- Confidence: high | medium | low

## Non-blocking notes
- Nits and optional improvements only.

## What I would verify next
- Only include if important evidence is missing.

Output format: bugfix mode

Use this structure:

# Bugfix report

## Symptom
- Expected:
- Actual:
- Environment / input:

## Reproduction
- Minimal reproducer:
- Status: reproduced | not reproduced | reasoned from evidence

## Root cause
Explain the exact path from input/state to failure.

## Fix
- Files changed:
- Why this fix addresses the root cause:
- Why this fix is minimal:

## Regression coverage
- Added/updated tests:
- What fails before the fix:
- What passes after the fix:

## Verification
- Commands run:
- Results:
- Not run / remaining gaps:

## Variant search
- Similar code paths checked:
- Remaining risks:

Hard rules

• Do not produce high-severity findings without evidence.
• Do not claim a test/build/lint passed unless you ran it or were given trusted output.
• Do not hide uncertainty. Mark confidence explicitly.
• Do not make broad rewrites during bugfix unless the root cause requires it.
• Do not delete tests to make CI pass.
• Do not weaken validation, authorization, typing, transactionality, or observability to fix a symptom.
• Do not expose secrets in reports. Redact tokens, keys, cookies, and private user data.
• Do not run destructive commands, migrations, production requests, load tests, exploit attempts, or state-changing operations without explicit approval.
• Do not test vulnerabilities against third-party or production systems. Use local, mocked, or authorized test environments.
• Do not copy large code from external sources. Extract patterns, cite sources where external facts matter, and adapt to the local codebase.
• Do not overload the user with every possible issue. Prioritize findings that matter.

Examples

Example 1: Review a backend PR

Use the review-bugfix-investigator skill.
Review this PR for correctness, API contract breaks, auth/tenant isolation, migrations, tests, and performance regressions.
Return only evidence-backed findings and merge verdict.

Example 2: Investigate a production-like bug

Use the review-bugfix-investigator skill in bugfix mode.
Users sometimes see another team's project in search results. Reproduce if possible, isolate root cause, propose minimal fix, and add regression tests for cross-tenant leakage.

Example 3: Security review

Use the review-bugfix-investigator skill.
Review the new file upload endpoint. Prove any vulnerabilities locally only. Check content type, size limits, storage key generation, SSRF/path traversal, auth, malware scanning hooks, and logging of PII.

Example 4: Review another agent's fix

Use the review-bugfix-investigator skill.
Another agent fixed the webhook retry bug. Review whether the root cause is actually fixed, whether idempotency is correct, and whether regression tests cover replay and duplicate delivery.