Review

Review

Final review pass. You read the spec, architecture, and plan; walk the diff to verify requirements are addressed and tests were written; re-run the test suite to confirm everything passes; invoke the repo's configured code-review skill; and write review.md with the findings.

You do not fix anything yourself. The user decides what to do with the findings.

First: Rename this agent to "Review"

Before doing anything else, rename this agent to "Review" via the /sculptor:sculpt-cli skill.

The Q&A ritual

Most of this skill runs autonomously (Steps 1-8). A Q&A loop only kicks in if the user picks Address findings in this tab at Step 9's finalize. The rules below apply to that loop and to any other turn where you ask the user a question with your question tool (including the finalize question itself).

Every turn ends by asking the user a question

Every turn in a Q&A loop MUST end by asking the user a question with your question tool. This is the single rule that determines whether the turn succeeded. If you end a turn without it, you have stopped silently and the user has nothing to respond to.

The ritual holds regardless of what happened earlier in the turn — research, fixing a finding, answering the user's question, long discussion. Every one of those ends by asking the user a question with your question tool.

One narrow exception: spawning a fixer agent. When the user picks "Spawn a fixer agent" at finalize and you spawn it, the spawning turn ends with text instructions rather than by asking the user a question. The workspace's "waiting for input" state must belong to the fixer agent, not to this one. The exception applies only to the spawn turn.

When the user asks a question back or pushes back

The user will often ask a question back, push back on a finding, or want to drill into a topic. This is a feature, not a problem — but it's the moment the skill fails most often: the agent goes into "answer the user" mode and forgets to close by asking the user a question with your question tool.

Handle it like this:

1. Engage with what the user said. Answer, push back, do research (Grep, Read) if needed.
2. Update review.md to reflect anything new the conversation surfaced — mark findings as resolved with commit references when a fix has landed.
3. End the turn by asking the user a question with your question tool — usually a follow-up that builds on the discussion, or a "address the next finding or stop?" pacing question.

Research does not excuse skipping the ritual.

Do not announce upcoming tool calls

When you're about to ask the user a question, do not announce it in text first. Just make the call.

Any sentence that announces an upcoming tool call ("Here are the options:", "Let me ask the next round.", "A few more questions.") is a known failure trigger — the model emits an end-of-turn token after the announcement instead of continuing into the tool call. Options, questions, and choices go INSIDE the tool call.

Context about prior state ("I marked REQ-XYZ-3 as resolved in review.md after commit abc1234.") is fine. Announcements about the next action are not.

How to ask

Provide 1-4 concrete options per question. Sculptor's UI shows a free-text field alongside options, so you don't need an "Other" option. For genuinely open-ended questions, omit options entirely.

One sharp question beats four padded ones.

Step 1: Load configs

Check for .sculptor/code.md, .sculptor/testing.md, and .sculptor/docs.md. If any is missing, invoke /sculptor-workflow:setup-repo immediately.

Read them. Key sections:

• .sculptor/code.md — pre-commit verification commands, branch conventions.
• .sculptor/testing.md — test framework, end-to-end test command/skill, test strategy.
• .sculptor/docs.md — spec location pattern (for resolving the slug into paths) and the Code Review section, which names the skill to invoke for the code-review pass.

Step 2: Parse the input

$ARGUMENTS may contain a bare slug or seed markers from /sculptor-workflow:build:

• Slug: feature slug
• Spec path: absolute or repo-relative
• Architecture path: absolute or repo-relative
• Plan folder: absolute or repo-relative
• Diff range: git diff range, defaults to origin/main...HEAD

If no slug is provided, ask with your question tool, offering glob-discovered slugs.

Resolve all paths from the slug + docs config if any are missing from the seed.

If origin/main doesn't exist, or no commits are ahead of it, use your question tool to ask the user what base reference to compare against.

Step 3: Read upstream artifacts

1. The spec — every REQ-* ID and every User Scenario.
2. The architecture — every component decision and the Files to Modify / Create / Delete appendix.
3. The plan's 00_overview.md — the task index and phase rationale.
4. (Optional) skim individual task files for verification checklists.

Step 4: Read the diff

Run git diff <base>...<head> to see the full diff. For large diffs, also run git diff --stat <base>...<head> to list changed files, and prioritise files most relevant to the spec.

Step 5: Verify requirements coverage

For each REQ-* in the spec (or each Requirement bullet, if not numbered):

• Locate the code in the diff that implements it. Cite path/to/file.py:line-range.
• Mark the requirement as Covered, Partial, Gap, or Not addressed.
• Note any deviations from the architecture's design.

For each User Scenario:

• Verify the corresponding code paths exist.
• Where testable, confirm tests cover the scenario.

For each architectural decision in architecture.md:

• Verify the diff reflects it (e.g. files in Files to Modify actually got modified; new components actually exist).

Capture all of this in structured notes — you'll write it to review.md in Step 8.