code-to-review

Code to Review

Stage 4 of 4. Consumes a finished plan and the full diff of the work it produced. Produces one review report and, where findings are in scope, new tasks appended to that plan for plan-to-code to execute.

Announce at start: "Using code-to-review to review the whole of this plan against standards and spec."

Two axes, run as parallel sub-agents so neither pollutes the other's context:

• Standards. Does the code follow this repo's documented standards, the smell

baseline, and the glossary?

• Spec. Does the code faithfully implement the spec, and does it contradict any ADR?

This skill reviews a finished plan, not a task. It runs once per plan.

1. Refuse to run early

Read the plan. Scan for - [ ] **Task lines.

If any task is unchecked, print exactly and stop:

This plan is not finished, so there is nothing to review yet.

Unchecked tasks in <plan path>:

  Task 5: <title>
  Task 6: <title>

Review runs once, over the whole plan, after the last task. Reviewing a half built
feature reports absences as defects.

Finish them first:

  Use the plan-to-code skill with <plan path> task 5

Do not offer to review anyway. If the user instructs it explicitly, comply, and note in the report header which tasks were unfinished at review time.

2. Pin the fixed point from the plan

The fixed point is the plan's **Base commit:**, not something to ask for. If the user passed one explicitly, theirs wins.

git rev-parse <base commit>            # must resolve
git rev-parse --abbrev-ref HEAD        # must match the plan's Branch
git diff <base commit>...HEAD          # must be non-empty
git log <base commit>..HEAD --oneline  # the commit list

Run all four before spawning anything. A bad ref or an empty diff must fail here, not inside two parallel sub-agents.

If `Base commit:` is empty, print exactly and stop:

This plan has no base commit recorded, which means plan-to-code never ran against it.

There is no fixed point to diff from, so there is nothing to review.

If HEAD is on a different branch from the plan's `Branch:`, say so and ask before continuing. The diff would be against unrelated history.

3. Gather the inputs

There is always a spec in this workflow. Do not search for one, do not look at issue references in commit messages, and do not fall back to reviewing without one.

If a path the plan or spec names does not exist, print which one and stop. A missing ADR is precisely the constraint the review would otherwise fail to check.

4. Spawn both sub-agents, in parallel

Both briefs cap at 400 words of output.

Standards sub-agent. Give it the diff command, the commit list, the standards source files you found, the full contents of SMELL-BASELINE.md pasted into the prompt, and the glossary terms with their definitions and _Avoid_ lists. Brief:

Report, per file or hunk where relevant: (a) every place the diff violates a documented standard, citing the standard by file and rule; (b) any baseline smell you spot, named, with the hunk quoted; (c) any name in the diff, meaning types, methods, and public surfaces, that does not use the canonical glossary term, quoting the term it should have used. Drift from a canonical term is a finding even when the name reads well. Distinguish hard violations from judgement calls. A documented standard breach can be hard. A baseline smell is always a judgement call. A documented repo standard overrides the baseline. Skip anything tooling already enforces. Under 400 words.

Spec sub-agent. Give it the diff command, the commit list, the full spec contents, and the full contents of every ADR. Brief:

Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that was not asked for, meaning scope creep, checked against the spec's Out of scope section; (c) requirements that look implemented but where the implementation looks wrong; (d) any place the code contradicts a recorded ADR. Quote the spec line, by its R or AC identifier, or the ADR line, for every finding. Under 400 words.

5. Aggregate

Present the two reports under ## Standards and ## Spec, verbatim or lightly cleaned.

Do not merge findings across axes, and do not rerank them against each other. The separation is the design. A change can follow every standard while implementing the wrong thing, and can implement the spec exactly while breaking every convention. Reporting them separately stops one axis masking the other.

End with a one line summary: total findings per axis, and the worst issue within each axis. Never pick a single worst across both, because that is the reranking the separation exists to prevent.

6. Write the report

Save to docs/reviews/<stem>.md, where <stem> is the plan's own filename stem, so the spec, plan, and review share one name. Print the report as well as saving it.

Header fields and full document shape are in REPORT-FORMAT.md.

Run git check-ignore -q on the path first. If it is ignored, say so and stop rather than writing a report that never reaches the repository.

A rerun overwrites this path. The superseded report stays recoverable in git history.

7. Close the loop

Every finding goes to exactly one of three places. Decide each one out loud.

In scope of the finished plan. Append it to the plan as a new numbered task, using the next unused number, in the same task format specs-to-plan produces, with unchecked boxes and a **Source:** review <date> line. It is then executed by plan-to-code, one task per session, like any other task. Never fix a finding inline in this session.

The spec or an ADR was wrong. Escalate. Say so plainly and stop there.

This finding is not a code defect. It shows the spec was wrong:

  Finding:   <the finding>
  Spec says: "<quoted R or AC>"
  Reality:   <why the spec is wrong>

I will not rewrite the spec or the ADR. Reopen stage one:

  Use the interview-to-specs skill

An ADR is superseded by a new ADR, never edited.

Neither. Say why, and leave it in the report without appending a task. A judgement call the user disagrees with is a legitimate outcome.

Then print exactly:

code-to-review complete.

  Report:  docs/reviews/<stem>.md
  Plan:    <plan path>
  Base:    <base commit>  to  HEAD (<n> commits)

Findings: <n> Standards, <n> Spec.
Appended: Task <N> through Task <M> for remediation.
Escalated: <n> findings need interview-to-specs. (or: None.)

Next: run the appended tasks, one per session.

  Use the plan-to-code skill with <plan path> task <N>

When they are all ticked, run code-to-review again against this same plan. The base
commit does not change, and the new report replaces docs/reviews/<stem>.md.

This session is done.

Refuse rather than improvise

• An unchecked task means stop. Do not review a partial plan unless told to in words.
• A missing spec or ADR path means stop. Do not review without it.
• An empty diff means stop before spawning anything.
• A finding is appended as a task, escalated, or left in the report. It is never fixed here.
• The spec and the ADRs are read only to this skill, always.