---
name: review-plan
description: >-
  Review a plan/task/context artifact set before execution, reporting scope
  gaps, sequencing problems, weak verification, and missing docs/tests/memory
  updates.
---

# review-plan

This is the dedicated pre-execution plan review skill.
Use it when the target is a workflow plan, matching task list, and context file,
not source code or a diff.

## Defaults

- Default target is the latest valid plan/task/context artifact set under `.agent-layer/tmp/`.
- Produce a report only. Do not edit the plan, task, or context artifacts in this workflow.
- If there is no valid plan/task pair, ask for explicit paths or regenerate the artifacts first.
- If the context file is missing, note its absence as a finding.

## Required artifact

Write the report to:
- `.agent-layer/tmp/review-plan.<run-id>.report.md`

Use `run-id = YYYYMMDD-HHMMSS-<short-rand>`.
Create the file with `touch` before writing.

## Artifact discovery

Use the standard artifact naming rule under `.agent-layer/tmp/`:
- `<workflow>.<run-id>.plan.md`
- `<workflow>.<run-id>.task.md`
- `<workflow>.<run-id>.context.md`

Discovery rules:
1. List `.agent-layer/tmp/*.plan.md`, `.agent-layer/tmp/*.task.md`, and `.agent-layer/tmp/*.context.md`.
2. Keep only files that match the standard naming rule and valid `run-id` shape.
3. Build candidate sets when both `.plan.md` and `.task.md` exist for the exact same `<workflow>` and `<run-id>`. A matching `.context.md` is expected but not required.
4. Select the set with the latest `run-id` in lexicographic order.
5. If the intended set is not the latest valid set, require explicit paths.

Fallback:
- If no valid plan/task pair exists, ask the user for explicit paths or regenerate the plan first.

## Multi-agent pattern

Recommended roles:
1. `Plan reader`: extracts the stated objective, scope, risks, and exit criteria.
2. `Risk reviewer`: looks for missing sequencing, dependencies, and non-goals.
3. `Verification reviewer`: stress-tests the test/doc/memory/update expectations.
4. `Reporter`: writes the findings report and recommendation.

## Global constraints

- Keep the review tied to what the plan actually says, not what you wish it said.
- Produce findings with concrete evidence and exact file references.
- Do not widen this into a code audit. Use the `review-scope` skill for code, diffs, or repo slices.
- If the plan is ambiguous, say so explicitly instead of guessing intent.

## Human checkpoints

- Required: ask when no valid plan/task pair exists.
- Required: ask when the user intends a non-latest artifact set and explicit paths are needed.
- Optional: ask only when the plan wording is so ambiguous that the review target itself is unclear.
- When a checkpoint involves a genuine tradeoff between substantive alternatives, present at least two options with brief pros and cons, state which you recommend and why, and let the human decide.
- Stay autonomous for normal critique and report writing.

## Review workflow

### Phase 1: Extract the contract (Plan reader)

From the plan, task, and context artifacts, extract:
- objective
- in-scope items
- explicit non-goals
- sequencing and dependencies
- promised tests or verification
- promised docs or memory updates
- exit criteria
- key files and entry point (from context file)

### Phase 2: Critique the plan structure (Risk reviewer)

Check for:
- missing requirements or non-goals
- hidden large refactors
- dependencies ordered after dependents
- risky assumptions presented as settled
- roadmap, issue, or decision constraints that were missed
- context file gaps: missing key files, stale paths, files listed that do not exist, missing entry point

### Phase 3: Critique the verification and completion bar (Verification reviewer)

Check for:
- weak or missing verification commands
- missing test work for risky changes
- missing docs or memory updates
- exit criteria that are subjective or not actually testable
- task list items that are too large or vague to execute safely

### Phase 4: Record only actionable findings (Reporter)

Each finding must include:
- `Title`
- `Severity`: Critical | High | Medium | Low
- `Location`: exact artifact path and section
- `Why it matters`
- `Evidence`
- `Recommendation`

## Required report structure

The report must contain:

1. `# Plan Review Summary`
   - plan path
   - task path
   - context path (or note if absent)
   - short outcome summary
2. `## Findings`
   - findings first, ordered by severity
3. `## Open Questions`
   - only unresolved items that block confidence
4. `## Strengths`
   - short list of what the plan does well
5. `## Recommendation`
   - `approve`
   - `approve-with-changes`
   - `revise`

## Guardrails

- Do not report vague “needs more detail” complaints without naming what is missing.
- Do not invent implementation problems that are not implied by the plan.
- Do not collapse multiple plan problems into one oversized finding.
- If the task list or context file is missing but the plan exists, call that out explicitly instead of pretending the artifact set is complete.

## Definition of done

- The report exists at `.agent-layer/tmp/review-plan.<run-id>.report.md` with every required section (`Summary`, `Findings`, `Open Questions`, `Strengths`, `Recommendation`).
- Every finding names its artifact path + section, severity, evidence, and specific recommendation — no vague "needs more detail" entries.
- The report ends with exactly one recommendation: `approve`, `approve-with-changes`, or `revise`.
- Plan, task, and context artifacts were not modified by this run.

## Final handoff

After writing the report:
1. Echo the report path.
2. Summarize the top findings in chat.
3. State the recommendation clearly.
