cto-review

Purpose

Strategic CTO-level review of a single PR, partitioned into isolated stages so the critical judgement (the whole-diff review) runs in a clean context window. Stage 01 gathers PR metadata, the full diff, repo context, and merge state. Stage 02 reviews the WHOLE diff cohesively across all dimensions (docs gaps, external deps, downstream/template impact, correctness, security, merge strategy, action items) in isolated context. Stage 03 runs inline: posts the GH review comment, applies the verdict label, merges-or-labels honoring merge state, writes the report file, and emits the outcome marker.

This proc is PR review ONLY. There is no heartbeat mode.

Arguments

Param	Required	Default	Notes
`PR_NUMBER`	yes	—	PR number to review
`org/repo`	yes	—	Target repository, e.g. `fellowship-dev/booster-pack`

Parse positionally from $ARGUMENTS: first token = PR number, second token = org/repo. Example: /cto-review 742 fellowship-dev/booster-pack.

What it does

3-stage ICM procedure (sequential):

Stage	Mode	Description
01-setup	subagent	Fetch repo context, PR metadata, full diff, and merge state. Short-circuit if CLOSED-not-merged.
02-review	subagent	ONE cohesive review of the whole diff across all dimensions → verdict + checklist + action items.
03-synthesize-act	inline	Post GH comment, apply label, merge-or-label honoring merge state, write report file, emit outcome marker.

Stage 02 is the isolated critical-judgement step — it receives only the setup handoff and its own CONTEXT.md, never orchestrator history.

Handoff locations

All handoffs live in the repo working directory:

.procedure-output/cto-review/{stage}/handoff.md

Stage 01 writes setup. Stage 02 reads only the setup handoff. Stage 03 reads both.

Execution

Stage 01 (subagent)

Spawn one Task. Pass only the arguments (PR number, org/repo) and the stage CONTEXT.md path.

Task prompt template:

You are running stage 01-setup of the cto-review procedure.

Arguments:
  PR_NUMBER = {PR}
  REPO = {org/repo}

Read your stage instructions:
  skills/cto-review/stages/01-setup/CONTEXT.md

Write your output to:
  .procedure-output/cto-review/01-setup/handoff.md

Execute all steps in CONTEXT.md. Write handoff.md before exiting.

If stage 01 reports short_circuit: closed-no-merge, skip stage 02 and go straight to stage 03 (which will post nothing and emit the blocked/closed outcome).

Stage 02 (subagent)

Spawn one Task. Pass only the stage 01 handoff path and the stage CONTEXT.md path. Do NOT pass orchestrator history or any prior reasoning — the review must run in clean isolated context.

Task prompt template:

You are running stage 02-review of the cto-review procedure.

Read your stage instructions:
  skills/cto-review/stages/02-review/CONTEXT.md

Your inputs:
  .procedure-output/cto-review/01-setup/handoff.md

Write your output to:
  .procedure-output/cto-review/02-review/handoff.md

Review the WHOLE diff cohesively across all dimensions. Write handoff.md before exiting.

Await stage 02 before proceeding to stage 03.

Stage 03 (inline)

Run stage 03 yourself (orchestrator context). Read CONTEXT.md:

skills/cto-review/stages/03-synthesize-act/CONTEXT.md

Post the comment, apply the label, merge-or-label, write the report file, and emit the [pylot] outcome=... marker from the orchestrator (not from a subagent).

Stage handoff chain

01-setup ──► 02-review ──► 03-synthesize-act (inline, reads 01 + 02)
   │                              ▲
   └── short_circuit: closed-no-merge ──┘  (skip 02)

Exit paths

Success: stage 03 emits [pylot] outcome="cto-review PR #{N} complete — verdict={verdict}, action={merged|labeled}" status=success
Failure: failing stage emits [pylot] outcome="cto-review failed at stage NN: {reason}" status=failed
Blocked: PR CLOSED-not-merged short-circuit → [pylot] outcome="cto-review skipped: PR #{N} closed without merge" status=blocked

Hard Rules

Sequential only — one subagent at a time, never parallel Task launches.
Stage 02 is the isolated judgement step — it receives ONLY the setup handoff + its CONTEXT.md.
Never pass full orchestrator context into subagent Task prompts — inputs only.
The whole diff is reviewed in ONE cohesive stage — never split per-file or per-dimension.
Stage 03 runs inline — GH side effects and the [pylot] outcome=... marker MUST come from the orchestrator.
Each stage writes handoff.md before the next stage reads it.
Do not skip stages — every stage executes, except stage 02 is skipped only on the CLOSED-no-merge short-circuit.
Honor merge state — never merge a CLOSED PR; for an already-merged PR, post the review as a post-merge note and never attempt merge.
Never merge if CI is red — even on an LGTM verdict.
No Quest — reporting is the local report file only.

Reference files

CONTEXT.md — architecture overview
shared/review-comment-format.md — exact GH review-comment template (verbatim from the original skill)
shared/report-format.md — local report-file template
stages/NN-name/CONTEXT.md — per-stage inputs, task, output contract