Code Review
Comprehensive multi-agent code review adapted for Python codebases.
Six specialist agents examine code from different angles — bugs, security,
test coverage, code quality, contracts, and historical context — then a
confidence-scoring phase filters out false positives before reporting.
Essential Principles
Each agent examines a different dimension. Agents run one at a time via
the Task tool (Copilot does not support parallel sub-agents). Keep agents
independent so their findings are not influenced by each other's results.
A review that reports 50 low-confidence nitpicks is worse than one that
reports 3 high-confidence critical issues. Every finding goes through a
confidence-scoring phase; only issues above threshold survive.
Check for Python-specific pitfalls: mutable default arguments, late-binding
closures, except Exception swallowing, unsafe pickle/yaml.load,
missing async/await, Pydantic validation gaps, and Django/FastAPI
framework patterns. Skip checks that don't apply to Python.
This project uses ruff for linting/formatting (line-length 120), pytest for
tests, uv for dependency management, and Conventional Commits. Don't flag
issues the existing toolchain already catches.
Vague advice ("consider improving error handling") wastes reviewer time.
Cite the exact location, explain the consequence, and show a code fix.
When to Use
- Reviewing local uncommitted changes before committing
- Reviewing a pull request for bugs, security, and quality
- Running a pre-merge quality gate
- Investigating a specific file or module for issues
- When asked to "review", "audit", or "check" code
Example Prompts
These prompts will trigger the code-review skill:
Review a PR:
Review PR #42Do a code review of this PRRun code-review on PR #184Audit the changes in PR #42 for bugs and security issues
Review local changes:
Review my local changesCode review the uncommitted changesCheck my changes before I commit
Review specific files:
Review src/coodie/cql_builder.py for bugsSecurity audit the driver module
When NOT to Use
- Running linters or formatters — use
uv run pre-commit run --all-files directly
- Writing new tests — use the
test-refactoring skill or write them manually
- Performance benchmarking — use the
benchmarks skill
- Planning new features — use the
writing-plans skill
Review Mode Selection
What are you reviewing?
│
├─ Local uncommitted changes (git diff)
│ └─ Follow: workflows/review-local-changes.md
│
├─ A pull request (PR number given)
│ └─ Follow: workflows/review-pr.md
│
└─ Specific files (paths given)
└─ Treat as local changes review scoped to those files
Agent Architecture
Six specialist agents run independently during Phase 2 of each workflow:
| Agent |
Focus |
Reference |
| Bug Hunter |
Runtime errors, None/null issues, race conditions, resource leaks |
bug-hunter.md |
| Security Auditor |
Injection, auth bypass, secrets exposure, unsafe deserialization |
security-auditor.md |
| Test Coverage |
Missing tests, weak assertions, untested error paths |
test-coverage-reviewer.md |
| Code Quality |
PEP 8, complexity, naming, SOLID, DRY, project conventions |
code-quality-reviewer.md |
| Contracts |
Pydantic models, type hints, API schemas, breaking changes |
contracts-reviewer.md |
| Historical Context |
Git blame, past bugs, hotspot files, architectural drift |
historical-context-reviewer.md |
Agent Applicability
Not every agent needs to run on every review. Select based on what changed:
| Condition |
Agents to Run |
| Any code changes |
bug-hunter, security-auditor, code-quality |
| Test files changed |
+ test-coverage |
| Types/models/API changed |
+ contracts |
| Complex or high-risk changes |
+ historical-context |
| All (default) |
All six agents |
Confidence Scoring
After agents report findings, each issue is scored on two axes:
Confidence (0–100): How certain is this a real issue?
| Score |
Meaning |
| 0 |
False positive — doesn't survive scrutiny |
| 25 |
Might be real, might be false positive |
| 50 |
Real issue, but minor or unlikely in practice |
| 75 |
Verified real issue, will be hit in practice |
| 100 |
Certain — evidence directly confirms it |
Impact (0–100): How bad is it if left unfixed?
| Score |
Meaning |
| 0–20 |
Minor code smell, no functional impact |
| 21–40 |
Hurts maintainability or readability |
| 41–60 |
Causes errors in edge cases or degrades performance |
| 61–80 |
Breaks core features or corrupts data |
| 81–100 |
Runtime crash, data loss, or security breach |
Filtering Thresholds
Higher-impact issues require less confidence to pass:
| Impact |
Min Confidence |
Rationale |
| 81–100 (Critical) |
50 |
Critical issues warrant investigation even with moderate confidence |
| 61–80 (High) |
65 |
High-impact issues need good confidence |
| 41–60 (Medium) |
75 |
Medium issues need high confidence |
| 21–40 (Low-Medium) |
85 |
Low-medium issues need very high confidence |
| 0–20 (Low) |
95 |
Minor issues only if nearly certain |
False Positive Examples
These should be filtered out:
- Pre-existing issues in unchanged code
- Issues that ruff, ty, or pytest would catch (CI handles those)
- Pedantic nitpicks a senior engineer wouldn't flag
- Intentional functionality changes related to the broader change
- Issues silenced by
# noqa, type: ignore, or similar comments
- General suggestions without specific evidence ("consider adding more tests")
Quick Reference: Python-Specific Checks
| Category |
What to Look For |
| Mutable defaults |
def f(items=[]) — use None + conditional |
| Broad except |
except Exception / bare except: swallowing errors |
| Async pitfalls |
Missing await, blocking calls in async functions |
| Pydantic |
Missing validators, wrong model_config, mutable defaults in models |
| Type hints |
Missing return types on public functions, Any overuse |
| Imports |
Circular imports, unused imports, inline imports |
| Resource leaks |
Files/connections not using context managers |
| Security |
pickle.load, yaml.load (not safe_load), eval(), f-string SQL |
| Testing |
Assertions without messages, assert True, missing parametrize IDs |
Reference Index
| File |
Content |
| bug-hunter.md |
Bug detection agent instructions — root cause analysis, Python-specific patterns |
| security-auditor.md |
Security audit agent — OWASP, Python-specific vulnerabilities |
| test-coverage-reviewer.md |
Test coverage agent — pytest patterns, behavioral coverage |
| code-quality-reviewer.md |
Code quality agent — PEP 8, SOLID, complexity, project conventions |
| contracts-reviewer.md |
Contracts agent — Pydantic, typing, API design, breaking changes |
| historical-context-reviewer.md |
Historical context agent — git archaeology, hotspots, past patterns |
| Workflow |
Purpose |
| review-local-changes.md |
3-phase workflow for reviewing uncommitted local changes |
| review-pr.md |
3-phase workflow for reviewing a pull request |
Success Criteria
A well-executed code review:
1---2name: code-review-23description: Multi-agent code review for Python projects. Use when reviewing local uncommitted changes, pull request diffs, or when asked to do a code review. Dispatches specialist agents (bug-hunter, security-auditor, test-coverage, code-quality, contracts, historical context) and aggregates results with confidence scoring.4---56# Code Review78Comprehensive multi-agent code review adapted for Python codebases.9Six specialist agents examine code from different angles — bugs, security,10test coverage, code quality, contracts, and historical context — then a11confidence-scoring phase filters out false positives before reporting.1213## Essential Principles1415<essential_principles>1617<principle name="independent-specialists">18**Run each specialist agent independently.**1920Each agent examines a different dimension. Agents run one at a time via21the Task tool (Copilot does not support parallel sub-agents). Keep agents22independent so their findings are not influenced by each other's results.23</principle>2425<principle name="confidence-over-volume">26**Filter by confidence × impact, not by count.**2728A review that reports 50 low-confidence nitpicks is worse than one that29reports 3 high-confidence critical issues. Every finding goes through a30confidence-scoring phase; only issues above threshold survive.31</principle>3233<principle name="python-idiomatic">34**Apply Python-specific knowledge, not generic rules.**3536Check for Python-specific pitfalls: mutable default arguments, late-binding37closures, `except Exception` swallowing, unsafe `pickle`/`yaml.load`,38missing `async`/`await`, Pydantic validation gaps, and Django/FastAPI39framework patterns. Skip checks that don't apply to Python.40</principle>4142<principle name="respect-project-conventions">43**Read AGENTS.md, pyproject.toml, and ruff config before flagging style issues.**4445This project uses ruff for linting/formatting (line-length 120), pytest for46tests, uv for dependency management, and Conventional Commits. Don't flag47issues the existing toolchain already catches.48</principle>4950<principle name="actionable-output">51**Every finding must include file path, line number, and a concrete fix.**5253Vague advice ("consider improving error handling") wastes reviewer time.54Cite the exact location, explain the consequence, and show a code fix.55</principle>5657</essential_principles>5859## When to Use6061- Reviewing local uncommitted changes before committing62- Reviewing a pull request for bugs, security, and quality63- Running a pre-merge quality gate64- Investigating a specific file or module for issues65- When asked to "review", "audit", or "check" code6667## Example Prompts6869These prompts will trigger the code-review skill:7071**Review a PR:**72- `Review PR #42`73- `Do a code review of this PR`74- `Run code-review on PR #184`75- `Audit the changes in PR #42 for bugs and security issues`7677**Review local changes:**78- `Review my local changes`79- `Code review the uncommitted changes`80- `Check my changes before I commit`8182**Review specific files:**83- `Review src/coodie/cql_builder.py for bugs`84- `Security audit the driver module`8586## When NOT to Use8788- Running linters or formatters — use `uv run pre-commit run --all-files` directly89- Writing new tests — use the `test-refactoring` skill or write them manually90- Performance benchmarking — use the `benchmarks` skill91- Planning new features — use the `writing-plans` skill9293## Review Mode Selection9495```96What are you reviewing?97│98├─ Local uncommitted changes (git diff)99│ └─ Follow: workflows/review-local-changes.md100│101├─ A pull request (PR number given)102│ └─ Follow: workflows/review-pr.md103│104└─ Specific files (paths given)105 └─ Treat as local changes review scoped to those files106```107108## Agent Architecture109110Six specialist agents run independently during Phase 2 of each workflow:111112| Agent | Focus | Reference |113|-------|-------|-----------|114| **Bug Hunter** | Runtime errors, None/null issues, race conditions, resource leaks | [bug-hunter.md](references/bug-hunter.md) |115| **Security Auditor** | Injection, auth bypass, secrets exposure, unsafe deserialization | [security-auditor.md](references/security-auditor.md) |116| **Test Coverage** | Missing tests, weak assertions, untested error paths | [test-coverage-reviewer.md](references/test-coverage-reviewer.md) |117| **Code Quality** | PEP 8, complexity, naming, SOLID, DRY, project conventions | [code-quality-reviewer.md](references/code-quality-reviewer.md) |118| **Contracts** | Pydantic models, type hints, API schemas, breaking changes | [contracts-reviewer.md](references/contracts-reviewer.md) |119| **Historical Context** | Git blame, past bugs, hotspot files, architectural drift | [historical-context-reviewer.md](references/historical-context-reviewer.md) |120121### Agent Applicability122123Not every agent needs to run on every review. Select based on what changed:124125| Condition | Agents to Run |126|-----------|---------------|127| Any code changes | bug-hunter, security-auditor, code-quality |128| Test files changed | + test-coverage |129| Types/models/API changed | + contracts |130| Complex or high-risk changes | + historical-context |131| All (default) | All six agents |132133## Confidence Scoring134135After agents report findings, each issue is scored on two axes:136137**Confidence (0–100):** How certain is this a real issue?138139| Score | Meaning |140|-------|---------|141| 0 | False positive — doesn't survive scrutiny |142| 25 | Might be real, might be false positive |143| 50 | Real issue, but minor or unlikely in practice |144| 75 | Verified real issue, will be hit in practice |145| 100 | Certain — evidence directly confirms it |146147**Impact (0–100):** How bad is it if left unfixed?148149| Score | Meaning |150|-------|---------|151| 0–20 | Minor code smell, no functional impact |152| 21–40 | Hurts maintainability or readability |153| 41–60 | Causes errors in edge cases or degrades performance |154| 61–80 | Breaks core features or corrupts data |155| 81–100 | Runtime crash, data loss, or security breach |156157### Filtering Thresholds158159Higher-impact issues require less confidence to pass:160161| Impact | Min Confidence | Rationale |162|--------|---------------|-----------|163| 81–100 (Critical) | 50 | Critical issues warrant investigation even with moderate confidence |164| 61–80 (High) | 65 | High-impact issues need good confidence |165| 41–60 (Medium) | 75 | Medium issues need high confidence |166| 21–40 (Low-Medium) | 85 | Low-medium issues need very high confidence |167| 0–20 (Low) | 95 | Minor issues only if nearly certain |168169### False Positive Examples170171These should be filtered out:172173- Pre-existing issues in unchanged code174- Issues that ruff, ty, or pytest would catch (CI handles those)175- Pedantic nitpicks a senior engineer wouldn't flag176- Intentional functionality changes related to the broader change177- Issues silenced by `# noqa`, `type: ignore`, or similar comments178- General suggestions without specific evidence ("consider adding more tests")179180## Quick Reference: Python-Specific Checks181182| Category | What to Look For |183|----------|-----------------|184| **Mutable defaults** | `def f(items=[])` — use `None` + conditional |185| **Broad except** | `except Exception` / bare `except:` swallowing errors |186| **Async pitfalls** | Missing `await`, blocking calls in async functions |187| **Pydantic** | Missing validators, wrong `model_config`, mutable defaults in models |188| **Type hints** | Missing return types on public functions, `Any` overuse |189| **Imports** | Circular imports, unused imports, inline imports |190| **Resource leaks** | Files/connections not using context managers |191| **Security** | `pickle.load`, `yaml.load` (not `safe_load`), `eval()`, f-string SQL |192| **Testing** | Assertions without messages, `assert True`, missing parametrize IDs |193194## Reference Index195196| File | Content |197|------|---------|198| [bug-hunter.md](references/bug-hunter.md) | Bug detection agent instructions — root cause analysis, Python-specific patterns |199| [security-auditor.md](references/security-auditor.md) | Security audit agent — OWASP, Python-specific vulnerabilities |200| [test-coverage-reviewer.md](references/test-coverage-reviewer.md) | Test coverage agent — pytest patterns, behavioral coverage |201| [code-quality-reviewer.md](references/code-quality-reviewer.md) | Code quality agent — PEP 8, SOLID, complexity, project conventions |202| [contracts-reviewer.md](references/contracts-reviewer.md) | Contracts agent — Pydantic, typing, API design, breaking changes |203| [historical-context-reviewer.md](references/historical-context-reviewer.md) | Historical context agent — git archaeology, hotspots, past patterns |204205| Workflow | Purpose |206|----------|---------|207| [review-local-changes.md](workflows/review-local-changes.md) | 3-phase workflow for reviewing uncommitted local changes |208| [review-pr.md](workflows/review-pr.md) | 3-phase workflow for reviewing a pull request |209210## Success Criteria211212A well-executed code review:213214- [ ] Ran all applicable specialist agents215- [ ] Every finding includes file path, line number, and concrete fix216- [ ] Confidence scoring filtered out false positives (threshold applied)217- [ ] No issues flagged that ruff/ty/pytest would already catch218- [ ] Python-specific patterns checked (mutable defaults, async, Pydantic)219- [ ] Project conventions (AGENTS.md, pyproject.toml) respected220- [ ] Critical/High issues clearly separated from suggestions221- [ ] Output follows the structured report template
scylladb