Stage Review Skill

Reviews a completed pipeline stage to determine whether it's safe to advance. Checks output existence, runs checkpoint criteria, and verifies the next stage's inputs are satisfied.

Trigger

Use this skill when:

• The user asks to review a stage before moving on ("review stage 2", "can I advance?", "check stage output")
• The user says "stage review", "stage checkpoint", "is this stage done?"
• The user wants a quality gate between /run-stage and the next stage
• The user is unsure whether a stage's output is good enough

Procedure

Step 1: Identify Target Stage

Determine which stage to review:

• If the user specifies a stage number or name, use that
• If the user says "review this stage" or "can I advance?", find the most recent stage with output files
• If ambiguous, list stages that have output and ask

# Find stages with output
for dir in [0-9][0-9]_*/; do
  if [ -d "$dir/output" ] && [ "$(ls -A "$dir/output" 2>/dev/null)" ]; then
    echo "$dir — has output"
  else
    echo "$dir — no output yet"
  fi
done

Step 2: Read the Stage Contract

Load {stage-folder}/CONTEXT.md. Extract:

• Outputs table — what files should exist and where
• Review Checkpoint — the criteria the human (and this skill) should verify
• Process section — what the stage was supposed to do (for quality assessment)
• Inputs table — what the stage had to work with (for traceability)

If the stage has no CONTEXT.md, report: "Stage {NN} has no contract. Cannot verify outputs against intent."

Step 3: Verify Output Existence

For each file declared in the Outputs table:

• Check the declared destination path
• Record: exists or missing
• If a file exists, note its size (empty files are a warning)

| Declared Output | Path | Status |
|----------------|------|--------|
| {file1} | {stage}/output/{file1} | [Exists/Missing/Empty] |
| {file2} | {stage}/output/{file2} | [Exists/Missing/Empty] |

If any declared output is missing, mark the stage as Not Ready immediately. The remaining checks still run to give a complete picture.

Step 4: Run Review Checkpoint

Read the Review Checkpoint section from the stage's CONTEXT.md. For each checkpoint criterion:

1. Read the relevant output file(s)
2. Assess whether the criterion is met
3. Score: Pass, Partial, or Fail
4. Provide brief evidence (one sentence)

| Checkpoint | Status | Evidence |
|-----------|--------|----------|
| {criterion 1} | [Pass/Partial/Fail] | {one-line evidence} |
| {criterion 2} | [Pass/Partial/Fail] | {one-line evidence} |

If the stage's CONTEXT.md has no Review Checkpoint section, run a basic quality check instead:

• Does the output appear complete (not truncated)?
• Does the output format match the declared format in the Outputs table?
• Does the output relate to the Process section's intent?

Step 5: Quality Assessment

Compare the stage's outputs against its Process section:

• Does the output reflect what the Process instructions asked for?
• Are there gaps between what was requested and what was produced?
• Are Layer 3 constraints (from the Inputs table's reference files) reflected in the output?

Score: Good (output fully matches intent), Acceptable (minor gaps), or Needs Revision (significant gaps or missing elements).

If quality is poor, identify specific issues: "The Process section asks for scene-by-scene breakdown, but the output is a single continuous narrative."

Step 6: Check Downstream Readiness

Identify the next stage (N+1). If it exists:

1. Read its CONTEXT.md Inputs table
2. For each input that sources from the current stage's output/:

• Verify the file exists
• Verify the file name matches exactly
• Verify the format is compatible

| Next Stage Input | Expected From | Status |
|-----------------|---------------|--------|
| {file} | {current stage}/output/ | [Ready/Missing/Name mismatch] |

If no next stage exists (this is the final stage), note: "This is the final stage — no downstream dependencies."

Step 7: Generate Review Report

## Stage Review: {NN}_{name}

**Status:** [Ready / Needs Revision / Not Ready]

### Output Completeness
{Table from Step 3}

### Checkpoint Results
{Table from Step 4}

### Quality Assessment
**Score:** [Good / Acceptable / Needs Revision]
{One paragraph explaining the assessment}

### Downstream Readiness
{Table from Step 6, or "Final stage" note}

### Recommendation
{One of:}
- **Advance:** Stage is complete. Run `/run-stage {NN+1}` to continue.
- **Revise:** Address these items before advancing: {list}
- **Re-run:** Stage output is incomplete or missing. Run `/run-stage {NN}` again.

Step 8: Offer Actions

Based on the recommendation:

• If Ready: "Run /run-stage {NN+1} to proceed to {next stage name}."
• If Needs Revision: Offer to re-run the current stage with specific guidance on what to fix, or let the user manually edit the output files.
• If Not Ready: Identify whether the problem is missing output (re-run needed) or missing inputs (previous stage issue).

What NOT to Do

• Do not modify output files during review — this skill reads, it does not write
• Do not auto-advance to the next stage — the user decides
• Do not re-run the stage automatically — flag the issue and let the user choose
• Do not score outputs on subjective quality beyond what the checkpoint criteria specify
• Do not read files outside the current stage and the next stage's contract