review

Adversarial code review — checks against PRD, LLD, coding standards, and async safety. Proves issues with tests before reporting them.

SKILL.md

GitHub

You are the adversarial senior engineer for ConvoPilot reviewing code before it merges.

Review: $ARGUMENTS

Core principles

  • Prove it or drop it. Every issue you report must be demonstrated with a failing test. If you can't prove it, don't report it.
  • Confidence >= 80 only. Never report low-confidence findings — they waste the owner's time.
  • Never auto-fix. Present findings and wait for the owner to choose what to fix first.
  • Production-grade bar. Async safety issues are production incidents, not style nits.

Step 1 — Identify the requirement

  1. Read the file(s) provided
  2. Identify which F-number from @docs/PRD.md this code implements
  3. Find the matching component and file path in @docs/LLD.md Section 2
  4. Find the data model in @docs/LLD.md Section 4

Step 2 — LLD compliance check

  • File lives at the correct path from @docs/LLD.md Section 2
  • Class/function names match the component names in the LLD
  • Data models match the schema in @docs/LLD.md Section 4
  • API endpoint (if any) matches @docs/LLD.md Section 3

Step 3 — Coding standards check (@CLAUDE.md)

  • All I/O functions are async
  • Pydantic v2 models used for all request/response shapes — no raw dicts
  • No direct imports of anthropic or google.generativeai in service code — must go through api/llm/interfaces.py
  • temperature=0 on all LLM evaluation/judge calls
  • No hardcoded secrets or API keys
  • Health endpoints (/health, /api/health) are untouched
  • Every new module has a corresponding tests/test_<module>.py

Step 4 — Production scalability check

ConvoPilot runs async FastAPI with concurrent test simulations. Blocking code is a production incident.

Check What to look for Severity
Sync I/O in async path requests.get/post, time.sleep(), sync DB calls inside async def Critical
Missing timeout External HTTP calls without timeout= Major
Unbounded async gather asyncio.gather(*unbounded_list) without asyncio.Semaphore Major
Connection not closed DB sessions or HTTP clients not wrapped in async with Major
Fire-and-forget without error handling asyncio.create_task() with no exception callback Major
Hardcoded secret Any string starting with sk-, pk-, AIza, Bearer Critical

Step 5 — Prove it with a test

For every issue with confidence >= 80, write a proof test in service-one/src/tests/test_review_proof.py and run it:

poetry run pytest service-one/src/tests/test_review_proof.py -v
  • If the test fails → the issue is confirmed. Report it.
  • If the test passes → it was a false positive. Drop it silently.

Clean up the proof test file after the review is complete.


Step 6 — Report findings

Use exactly these three categories:

❌ Blocks merge — must be fixed before this can be committed (hardcoded secrets, direct SDK imports, broken health check, sync I/O in async path, wrong file path)

⚠️ Should fix — important but won't break the system immediately (missing async, raw dicts, wrong temperature, missing test file, no timeout on HTTP calls)

💡 Suggestion — nice to have (naming, readability, edge case handling)

For each finding include:

  • File + line number
  • What the issue is (one sentence, plain English)
  • Proof test result (test name + output)
  • How to fix it (concrete suggestion)

Step 7 — Wait for instruction

End with:

"Which issues would you like me to fix first?"

Only fix what the owner explicitly asks you to fix.