Workflow Review Process

Review Process

Act as a senior software architect with deep experience in code review. You haven't seen this code before. Your job is to verify that every plan task was implemented correctly, tested adequately, and meets professional quality standards — then assess the product holistically.

Purpose in the Workflow

Follows implementation. Verify plan tasks were implemented, tested adequately, and meet quality standards — then assess the product holistically.

What This Skill Needs

• Review scope (required) - single, multi, or all
• Plan content (required) - Tasks and acceptance criteria to verify against (one or more plans)
• Specification content (required) - The specification from the prior phase, for design decision context

Instructions

Load framework.md and follow its instructions as written.

Resuming After Context Refresh

Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:

1. Re-read this skill file completely, then re-load framework.md. Do not rely on your summary of either, and re-read both even if you believe they are already loaded — that belief is what a summary feels like from the inside. The full process, steps, and rules must be reloaded.
2. Read review and synthesis files for the current topic. Review documents are at .workflows/{work_unit}/review/{topic}/report.md with per-task report files alongside (report-{phase_id}-{task_id}.md). Synthesis staging files are at .workflows/{work_unit}/implementation/{topic}/review-tasks-c{N}.md. These hold the staged proposals — bodies exist only once the task author has run after the walk; the per-task decisions and gate_mode live in the manifest's staging.c{N} subtree.
3. Check git state. Run git status and git log --oneline -10 to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
4. Announce your position to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.

Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.

Hard Rules

1. Review ALL tasks — Verify every planned task, or only unreviewed tasks when continuing a prior review
2. Don't fix code — Identify problems, don't solve them
3. Don't re-implement — You're reviewing, not building
4. Be specific — "Test doesn't cover X" not "tests need work"
5. Reference artifacts — Link findings to plan/spec with file:line references
6. Balanced test review — Flag both under-testing AND over-testing
7. Fresh perspective — You haven't seen this code before; question everything

Step 0: Resume Detection

Refresh the tmux session label — a no-op unless the user opted in and this session runs inside tmux:

node .claude/skills/workflow-engine/scripts/engine.cjs session label {work_unit} review {topic}

Check for prior review state — a review file at .workflows/{work_unit}/review/{topic}/report.md, and recorded coverage (empty stdout means none):

node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.review.{topic} reviewed_tasks

If neither exists

→ Proceed to Step 1.

Otherwise

Output the next fenced block as markdown (not a code block):

**`□ Resume Detection`**

Output the next fenced block as markdown (not a code block):

> An in-progress review exists for this topic — choose whether to pick it up or start fresh.

Gather coverage state. Read completed_tasks from the implementation manifest:

node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.implementation.{topic} completed_tasks

Render the resume menu — the engine derives review coverage from the two arrays — and emit its section verbatim per its marker:

node .claude/skills/workflow-engine/scripts/engine.cjs render resume-gate {work_unit}.review.{topic} --variant review

STOP. Wait for user response.

If continue

If unreviewed tasks exist:

Set unreviewed_tasks = [{list of unreviewed internal IDs}].

→ Proceed to Step 1.

If all tasks reviewed and the review file exists:

→ Proceed to Step 9.

If all tasks reviewed and no review file exists (verification finished; everything after it was lost):

→ Proceed to Step 6.

Otherwise (no tracking data):

→ Proceed to Step 1.

If restart

Order matters — the review file is deleted last, so a crash mid-restart re-offers restart on the next entry instead of impersonating a fresh run.

1. Clear review tracking (each subtree only if it exists — check with manifest exists {work_unit}.review.{topic} reviewed_tasks, … staging, and … out_of_scope first):

   node .claude/skills/workflow-engine/scripts/engine.cjs manifest delete {work_unit}.review.{topic} reviewed_tasks
   

   node .claude/skills/workflow-engine/scripts/engine.cjs manifest delete {work_unit}.review.{topic} staging
   

   node .claude/skills/workflow-engine/scripts/engine.cjs manifest delete {work_unit}.review.{topic} out_of_scope
   

2. Delete any synthesis staging files (review-tasks-c*.md) in .workflows/{work_unit}/implementation/{topic}/ — stale proposals from the abandoned run. The synthesis reports (review-report-c*.md) stay — the cycle counter reads them
3. If the planning item carries no storage_paths (a plan initialised before the field existed): record it now — read the format's authoring.md (format from manifest get {work_unit}.planning.{topic} format) → Storage Pathspecs and copy the fenced array (node .claude/skills/workflow-engine/scripts/engine.cjs manifest set {work_unit}.planning.{topic} storage_paths '{format storage pathspecs}')
4. If the abandoned run's Review Remediation (Cycle {N}) phase already landed in the plan: mark each of that phase's tasks whose id is not in {work_unit}.implementation.{topic} completed_tasks skipped per the format's updating.md (format from manifest get {work_unit}.planning.{topic} format) — abandoned remediation must never execute, and a partially-executed phase keeps only what already ran
5. Delete the review file and all report files (report-*.md) in the review directory (.workflows/{work_unit}/review/{topic}/)
6. Commit the deletions under the topics that held them, then the plan — --plan stages the planning topic, the manifests, and the plan's declared storage (the skip-markings live there):

   node .claude/skills/workflow-engine/scripts/engine.cjs commit {work_unit} -m "review({work_unit}): restart review — clear reports and staging" --topic review/{topic}
   node .claude/skills/workflow-engine/scripts/engine.cjs commit {work_unit} -m "review({work_unit}): restart review — clear staged proposals" --topic implementation/{topic} --sweep
   node .claude/skills/workflow-engine/scripts/engine.cjs commit {work_unit} -m "review({work_unit}): restart review" --plan {topic}
   

→ Proceed to Step 1.

Step 1: Initialize Review

Check if review phase is registered in manifest:

node .claude/skills/workflow-engine/scripts/engine.cjs manifest exists {work_unit}.review.{topic}

If false

Start the review item — the engine creates it with status: in-progress:

node .claude/skills/workflow-engine/scripts/engine.cjs topic start {work_unit} review {topic}

→ Proceed to Step 2.

Otherwise

→ Proceed to Step 2.

Step 2: Read Plan(s) and Specification(s)

Load read-plans.md and follow its instructions as written.

→ On return, proceed to Step 3.

Step 3: Load Project Skills

Load load-project-skills.md and follow its instructions as written.

→ On return, proceed to Step 4.

Step 4: Knowledge Usage

Load knowledge-usage.md and follow its instructions as written.

→ On return, proceed to Step 5.

Step 5: QA Verification

Output the next fenced block as markdown (not a code block):

**`□ QA Verification`**

Output the next fenced block as markdown (not a code block):

> Dispatching task verifier agents. Each task is independently verified against its acceptance criteria and the specification.

Load invoke-task-verifiers.md and follow its instructions as written.

*Knowledge-base nudge — use only for cross-work-unit consistency checks ("does this mirror how similar decisions were made elsewhere?"). Consistency with the current spec is already in scope — no KB needed. See knowledge-usage.md.*

→ On return, proceed to Step 6.

Step 6: Prep Findings

Output the next fenced block as markdown (not a code block):

**`□ Prep Findings`**

Output the next fenced block as markdown (not a code block):

> Each verifier saw one task. Checking every finding against the code and the code standard, against the guards it could breach, and against the other findings it collides with.

Load prep-findings.md and follow its instructions as written.

→ On return, proceed to Step 7.

Step 7: Apply Do-Now

Output the next fenced block as markdown (not a code block):

**`□ Apply Do-Now`**

Output the next fenced block as markdown (not a code block):

> Applying the contained corrections — low-impact, blast radius minimised. The whole body of work is verified and the suite run before anything lands.

Load apply-do-now.md and follow its instructions as written.

→ On return, proceed to Step 8.

Step 8: Produce Review

Output the next fenced block as markdown (not a code block):

**`□ Produce Review`**

Output the next fenced block as markdown (not a code block):

> Writing the review — the verdict, what was corrected, what must be planned, and what was discarded.

Load produce-review.md and follow its instructions as written.

→ On return, proceed to Step 9.

Step 9: Present Review

Output the next fenced block as markdown (not a code block):

**`□ Present Review`**

Output the next fenced block as markdown (not a code block):

> The outcome: pass or fail, what was corrected, and what needs you.

Load present-review.md and follow its instructions as written.

→ On return, proceed to Step 10.

Step 10: Compliance Self-Check

Load compliance-check.md and follow its instructions as written.

→ On return, proceed to Step 11.

Step 11: Review Actions

Load review-actions-loop.md and follow its instructions as written.