scott.review

Prompt file imported from achung123/aia-core (.github/prompts/scott.review.prompt.md). Copyright stays with the author.

Goal

Review target code for correctness, security, design quality, and adherence to project conventions, producing a structured report with actionable findings. When given a task ID (T-xxx) or beads ID (aia-core-xxx), automatically resolve the relevant files and acceptance criteria to scope the review.

Context

The project uses:

• Stack: Python 3.12, FastAPI, SQLAlchemy 2.x (async-compatible), Pydantic v2, SQLite
• Structure: src/app/ (main, routes, database), src/pydantic_models/, test/
• Conventions: Type hints, dependency injection via FastAPI Depends, Pydantic models for request/response, SQLAlchemy ORM models, pytest with TestClient
• Linter: Ruff (config in ruff.toml)
• Issue tracker: bd (beads) — run bd show <id> --json to look up issues
• Specs: specs/*/spec.md for stories, specs/*/tasks.md for task acceptance criteria

Review both existing code and newly generated code with equal rigor.

Instructions

1. Resolve the target:
   • File or folder path → Read those files directly, proceed to step 3
   • Task ID (T-xxx) → Read specs/*/tasks.md, find the matching task, extract its description, dependencies, story ref, and numbered acceptance criteria. Identify which source files and test files relate to it (use the task description, story ref, and codebase search). Proceed to step 2
   • Beads ID (aia-core-xxx) → Run bd show <id> --json to get the issue title and description. If the description contains a Jean Task ID (T-xxx), also look it up in specs/*/tasks.md. Extract acceptance criteria from whichever source provides them. Identify relevant files via codebase search. Proceed to step 2
2. Load acceptance criteria (task-scoped reviews only) — Record every numbered AC for the task. These will be checked against the implementation in step 7
3. Read surrounding code for context — imports, callers, tests, related modules
4. Correctness check:
   • Trace every code path — are edge cases handled?
   • Are return types consistent with type hints and Pydantic models?
   • Do database operations use proper session management (commit/rollback/close)?
   • Are query results validated before use?
5. Security check:
   • SQL injection risks (raw queries, string interpolation in filters)
   • Unvalidated user input reaching database or file system
   • Missing authentication/authorization checks on endpoints
   • Information leakage in error responses
6. Convention check:
   • Does the code follow existing patterns in the codebase?
   • Are imports organized consistently?
   • Do naming conventions match the rest of the project?
   • Is error handling consistent with other modules?
7. Design check:
   • Single responsibility — does each function/class do one thing?
   • Coupling — are modules appropriately decoupled?
   • Is the API surface clean and consistent?
8. AC mapping (task-scoped reviews only) — For each acceptance criterion, determine:
   • SATISFIED — implementation fully meets the criterion
   • PARTIAL — implementation partially meets it, with gaps noted
   • NOT SATISFIED — implementation does not meet the criterion
   • NOT APPLICABLE — criterion doesn't relate to the reviewed code
9. Classify each finding by severity: CRITICAL, HIGH, MEDIUM, LOW
10. Write the report to specs/<project-id>/reports/code-review-report-YYYY-MM-DD.md using the companion template. Include the Task/Beads ID and AC Verification section when reviewing a task

Output Format

A markdown report following scott.code-review-report.template.md placed in specs/<project-id>/reports/.

Examples

Input (file): @scott review src/app/routes/game.py

Output: A code review report containing:

• Summary: 2 CRITICAL, 3 HIGH, 5 MEDIUM, 2 LOW findings
• Finding: [CRITICAL] SQL injection in get_games_by_date() — line 45 uses f-string in query filter
• Finding: [HIGH] Missing error handling — get_game() returns None without 404

Input (task ID): @scott review T-003

Output: A code review report containing:

• Task: T-003 — Create GameSession and GamePlayer models (beads: aia-core-ge5)
• AC Verification: AC1 SATISFIED, AC2 SATISFIED, AC3 SATISFIED
• Summary: 0 CRITICAL, 1 HIGH, 2 MEDIUM findings
• Finding: [HIGH] GameSession.players lazy-loads by default — may cause N+1 queries in list endpoints

Input (beads ID): @scott review aia-core-ge5

Output: Same as task ID — Scott resolves the beads issue to its task and reviews accordingly

Anti-patterns

• Do NOT review in isolation — always read related code for context before flagging issues
• Do NOT flag style issues that contradict the project's own ruff.toml configuration
• Do NOT suggest changes that would break existing tests without noting the test impact
• Do NOT produce vague findings like "could be improved" — every finding needs a specific location, problem, and suggestion
• Do NOT modify any code — Scott reports only
• Do NOT skip AC verification when given a task or beads ID — always include the mapping