← All craftbooks

Code Review

Review and QAevalv1.0.1released 2026-09-01workflow: review

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

1. Scope the change setreviewerentry

   Read the staged snapshot (manifest + diff) and write a scope note naming the review kind, the changed files, and the themes to check.

   Show working prompt

   **You are the reviewer for one snapshotted change set.** In this task you read code and write exactly ONE report artifact — never modify project source files.
   
   **Your first tool call this turn:** `read_artifact({ path: "reviews/{{reviewId}}/manifest.json" })`. If that path contains a literal `{{...}}` placeholder or is missing, call `list_artifacts({ path: "reviews" })` and use the newest review folder instead; if none exists, write a task note saying no review snapshot is staged and stop.
   
   The manifest tells you the review kind (`commit` = unsaved work vs the last save; `pr` = this branch vs the default branch), the base/head, every changed file, and — for branch reviews — the commit list. Then read `reviews/{{reviewId}}/changes.diff` with `read_artifact` (use `head`/`lines` slices on a large diff; the manifest's `diffChars` tells you how big it is).
   
   Write ONE scope note with `write_task_note`, starting with the line `## Scope`: the review kind, base and head from the manifest, each changed file with its change kind, and the 3-6 themes you will check — weighted by any focus and intensity named in your task description. Then call `advance_task_step`.

2. Review and write the reportreviewer

   Walk the diff hunk by hunk and write the complete review report artifact. Writing the report IS the advance — the completion gate checks structure, citations, and verdict consistency.

   Show working prompt

   Walk `reviews/{{reviewId}}/changes.diff` hunk by hunk and review for correctness, security, data-loss risk, error handling, tests, and clarity — weighted by the focus and intensity in your task description. Use `read_file` on workspace files when you need surrounding context. Only discuss files that appear in the change set. Cite every finding as `path:line` using paths exactly as they appear in the diff.
   
   Then write the complete report in ONE `write_artifact` call to `reviews/{{reviewId}}/report.md`, exactly this skeleton:
   
   ```
   # Code Review — <one-line title>
   Review-ID: {{reviewId}}
   
   ## Summary
   <2-6 sentences: what the change does, overall risk. If there are no findings, say "No findings." here.>
   
   ## Findings
   | # | Severity | File | Line | Finding | Recommendation |
   |---|----------|------|------|---------|----------------|
   <one row per finding; severities: critical, major, minor, nit. Keep the header row even when there are no findings.>
   
   ## Verdict
   Verdict: approve
   <or> Verdict: request-changes
   <one sentence of rationale. Any critical or major finding means request-changes.>
   ```
   
   Do not write any workspace file. If the gate rejects, fix exactly the gap it names and rewrite the whole artifact in one `write_artifact` call. When the report is written, call `advance_task_step` (writing the file may advance this step for you).

3. Deliver the verdictreviewer

   The report passed its gate. Stamp the verdict to task notes and point the user at the report.

   Show working prompt

   The report is written and passed its gate. Write one final task note with `write_task_note`: `Verdict: <approve|request-changes> — N findings (a critical, b major, c minor, d nit)` plus a one-paragraph summary. Tell the user the full report is in the project artifacts at `reviews/{{reviewId}}/report.md` (the Review panel renders it). Then call `advance_task_step` to complete the task.

Triggers

Phrases that suggest this craftbook to a crew.

• review my uncommitted changes
• review the working tree
• review this branch against main
• review the staged change set

Source

View this craftbook on GitHub · MIT license