| name | plan-review |
| description | Review .context/plans/*.md files using 3 independent subagent reviewers: Technical (feasibility, gaps, soundness), Strategic (scope, alignment, priority), and Risk (blind spots, edge cases, failure modes). The skill FIRST asks the user which models to assign to each reviewer — presenting available options based on the user's environment (OpenCode Zen, Go, Claude Code, or BYOK). Each reviewer receives the same plan with a role-specific lens and returns structured feedback. The main agent consolidates all three perspectives. Triggers: 'review this plan', 'audit plan', 'plan review', 'check my plan', 'what's wrong with this plan', 'review all plans', 'plan quality check'. Do NOT use for plans not in .context/plans/, one-off notes, or external documents.
|
Plan Review — 3-Agent Multi-Perspective Audit
Review .context/plans/ files through 3 independent lenses: Technical,
Strategic, and Risk. Each reviewer is a separate subagent with a unique
prompt and perspective. The main agent collates results into a consolidated report.
This catches what a single reviewer normalises — each subagent brings a fresh
set of assumptions and focus areas.
Prerequisites
- A
.context/plans/*.md file exists to review (or a glob selecting multiple)
- The plan has standard YAML frontmatter (
title, type, status, date)
- Your environment supports spawning
general and explore subagent types
Quick Start
When to Use
- A
.context/plans/*.md file needs an independent multi-perspective review before implementation
- A draft plan needs validation before marking it
ACTIVE
- Multiple plans exist in the same domain and need prioritisation
- A stale plan needs a freshness check against current project state
- The user explicitly asks for a plan audit
When NOT to Use
- For one-off notes, scratch files, or non-plan documents — use
session-reflection instead
- For plans outside
.context/plans/ — the reviewer prompts assume .context/ frontmatter conventions
- When the plan is trivially small (1 paragraph, no steps) — the overhead of 3 subagents is not justified
- When the user explicitly asks for a quick opinion, not a full audit
Mindset
- Three independent reviewers catch what a single reviewer normalises. The value is in the divergence between their findings, not in consensus.
- Model diversity is the strongest lever for perspective diversity. Different models trained on different data notice different failure modes.
- A plan review is a service to the plan author, not a judgement. Findings should be actionable, not critical.
- Structural validation is a prerequisite, not the goal. The frontmatter check exists to keep the plan visible in the index, but the real value is the implementation architecture and risk analysis from the 3 reviewers.
- If a review reveals a critical issue, the right outcome is to improve the plan, not to reject it.
Workflow
1. Identify the plan to review
The user specifies a plan path, or you suggest one from .context/plans/.
Read the plan in full. Note its frontmatter (status, date, related),
goal, steps, open questions, and risks.
2. Compose the plan brief
From the plan file, create a structured brief that all 3 reviewers will receive.
The brief must be self-contained — each reviewer should not need to read the
original plan file. Include:
- Title, status, date — from frontmatter
- Goal — the plan's stated objective (verbatim if concise, summarised if long)
- Steps — numbered list of implementation steps
- Dependencies / related files — from
related: frontmatter
- Open questions — listed verbatim
- Known risks — listed verbatim from the plan's risk section (if any)
- Implementation status — what's already been done vs what's still pending
- Context — any relevant background from related findings or docs
3. Validate plan structure against the standard trio
Every .context/ plan should follow a three-part standard: a YAML template
defining required fields, a JSON schema for machine validation, and a validation
script. Check the plan against all three.
The trio
| Component | Location | What it defines |
|---|
| YAML template | context-file SKILL.md (frontmatter section) | Required fields: title, type, status, date, optional related |
| JSON schema | context-file/assets/schemas/context-frontmatter.schema.json | Field types, allowed values (enum), patterns, required list |
| Validation script | context-index/scripts/validate-context-frontmatter.sh | CLI script that reads the schema and checks one or more files against it |
What to check
Run the validation script on the plan file:
.context/plugins/pantheon-org/context-mgmt/context-index/scripts/validate-context-frontmatter.sh .context/plans/<plan-file>.md
This checks:
- Frontmatter exists and opens/closes with
---
- All required fields present (
title, type, status, date)
type is one of the allowed values (PLAN, FINDING, ANALYSIS, INSTRUCTION, AUDIT)status is one of DRAFT, ACTIVE, DONE, SUPERSEDEDdate matches YYYY-MM-DD pattern- No extra fields beyond those defined in the schema
If validation passes
Include **Structure: Valid** in the plan brief. Proceed to model selection.
If validation fails
Capture each validation error and include it in the plan brief under a
## Structural Issues section so all 3 reviewers can reference them. Sample:
## Structural Issues
- Missing required field: 'status'
- 'date' does not match pattern YYYY-MM-DD, got '01-07-2026'
Plan body structure — infer the local standard
Beyond frontmatter, check the plan's body sections (## headings) against what
other plans in this repo actually use. Do NOT hardcode a template — scan the
existing plans and infer what's conventional.
How to infer
Run this to collect all H2 headings from every plan:
grep -r '^## ' .context/plans/*.md | sed 's/.*## //' | sort | uniq -c | sort -rn
This gives a frequency table like:
7 ## Goal
7 ## Steps
5 ## Open Questions
4 ## Scope
4 ## Related
4 ## Decisions
3 ## Verification
3 ## Risks
3 ## Success Criteria
3 ## Background
From this, identify the core sections (present in >= 40% of plans), the
common sections (present in 20-39%), and the rare sections (<20%).
What to report
Include in the plan brief under ## Structural Issues:
### Body Structure (inferred from <N> existing plans)
Core sections (≥40% of plans):
- Goal: present/missing
- Steps/Phases: present/missing
- Open Questions/Decisions: present/missing
Common sections (20-39%):
- Scope/Out of scope: present/missing
- Related findings: present/missing
- Verification: present/missing
- Risks/sequencing: present/missing
Note: Sections like Background, File-by-file change list, Academic References,
and Critical Review appear in <20% of plans and are optional.
Missing core sections are advisory warnings — they don't invalidate the plan
(plans can be valid with different structures) but the reviewer should note them.
Missing common sections are neutral observations.
Rare or unique sections are also interesting — they may indicate scope creep or
a plan that doesn't fit the local conventions. Note them as "unusual sections"
but do not flag them as problems.
Why infer instead of hardcode
Hardcoding a template (Goal → Steps → Open Questions) penalises plans that
legitimately need a different structure. Inferring from actual plans reflects
what this repo's conventions actually are — and those conventions evolve as
new plans are added. A plan that omits ## Goal but has a ## Problem and
## Target State is following the spirit of the convention, just not the
letter.
Implementation architecture — Phases, Tasks, and Waves
A well-structured plan divides the work into Phases, Tasks, and
Waves — and the review should check for this structure.
| Term | Meaning | Example |
|---|
| Phase | Sequential stage — Phase N must finish before Phase N+1 starts | Phase 1: Foundation, Phase 2: Integration |
| Task | Smallest unit of work within a phase — independently assignable | Task 1.1: Create schema, Task 1.2: Write migration |
| Wave | Group of tasks within a phase that can run in parallel | Wave A (can run with Wave B): frontend + backend |
Common bad patterns to flag:
- Flat step list — 15 numbered steps with no grouping, no parallelisation.
Every step waits for the previous one, even when they don't depend on each other.
- Missing dependency annotation — steps are listed sequentially but some
could run in parallel. The plan doesn't say which.
- Oversized phases — "Phase 1: Everything" with 20+ tasks and no sub-structure.
A phase should be small enough that it can be reviewed and shipped independently.
- Missing task boundaries — steps describe vague outcomes ("improve things")
instead of concrete, completable units ("add --format flag to evaluate cmd").
What to check
Look at the plan's ## Steps / ## Implementation / ## Phases section:
-
Are steps grouped into phases? The plan should have 2-5 sequential phases
(numbered or labelled). If there are >10 flat steps with no grouping, flag it.
-
Are tasks the right size? Each task should be completable in a single
session (hours, not weeks). Tasks with vague descriptions ("finalise",
"improve", "handle remaining") are a red flag.
-
Are parallel waves identified? Within a phase, are there tasks explicitly
marked as parallelisable? Look for language like "can run in parallel",
"independent of", "Wave A / Wave B". If all tasks are strictly sequential
without justification, flag it.
-
Are dependencies explicit? Does the plan say why Phase 1 must come before
Phase 2? Are cross-phase dependencies called out? If dependencies are
implicit, that's a risk.
-
Are there concrete exit criteria per phase? Each phase should define what
"done" means — a deliverable, a passing test, a merged PR. Phases that end
with "iterate" or "review" without a concrete gate are risky.
What to report
Include in the plan brief under ## Structural Issues:
### Implementation Architecture
Phases: <N> phases identified — <list phase names>
- Phase dependencies: explicit/implicit/missing
- Phase exit criteria: present for <N>/<N> phases
Task granularity: good / too vague / too large
- <count> of <total> tasks have actionable descriptions
Parallelisation:
- Waves identified: yes/no
- Tasks flagged as parallel: <N> of <N>
- Parallelism opportunity: <N> tasks could run concurrently but aren't grouped
#### Why this matters
A plan with structurally invalid frontmatter will be silently excluded from
`.context/index.yaml` — making it invisible to other agents. Catching this
during review prevents the plan from becoming orphaned context.
### 4. Check opencode.json for existing model config
Before asking the user anything, check whether `opencode.json` already has
`subAgents` configured:
```bash
cat opencode.json | python3 -c "import sys,json; c=json.load(sys.stdin); print('configured' if c.get('subAgents') else 'not-configured')"
If subAgents is configured with at least two distinct models, note the
mapping and proceed to compose the plan brief (skip model selection — the
user already configured it). Include the model assignments in the final report.
If not configured, proceed to step 5 and advise the user.
5. Ask the user which models to use
Do NOT proceed without asking. The agent should proactively advise based on
what it detects. First check if this is Claude Code or OpenCode by looking
for environment cues (e.g., CLAUDE_CODE env var, or ANTHROPIC_API_KEY
is set). If you cannot determine the environment, ask:
"Are you using OpenCode or Claude Code? This determines which models are available for the subagent reviewers."
Use the appropriate guidance below.
If OpenCode (no subAgents configured)
Advise the user with a capability-vs-cost breakdown. Present options using the
question tool. The goal is to assign one model to Technical + Strategic
(both use general subagent type) and a different model to Risk
(explore subagent type). Different models = different blind spots.
OpenCode Zen (pay-as-you-go) — capability vs cost:
| Tier | Pair | Tech/Strategic | Risk | Cost/run | When |
|---|
| Best value (Recommended) | DS Flash + GPT 5 Nano | DeepSeek V4 Flash ($0.14/M in) | GPT 5 Nano ($0.05/M in) | ~$0.03 | Default for most reviews |
| Balanced | DS Flash + Claude Haiku | DeepSeek V4 Flash ($0.14/M in) | Claude Haiku 4.5 ($1.00/M in) | ~$0.08 | Want an Anthropic perspective on risk |
| Max depth | DS Pro + GPT 5 Nano | DeepSeek V4 Pro ($1.74/M in) | GPT 5 Nano ($0.05/M in) | ~$0.12 | Critical, high-stakes plan review |
| Budget | GPT 5 Nano (all) | GPT 5 Nano ($0.05/M in) | GPT 5 Nano ($0.05/M in) | ~$0.01 | Draft plan, quick sanity check |
OpenCode Go (flat-rate subscription):
All models cost the same (no per-token charge). Prioritise diversity:
{
"subAgents": {
"general": { "model": "deepseek-v4-flash" },
"explore": { "model": "minimax-m3" }
}
}
Recommended pairs:
| Pair | Tech/Strategic | Risk | Why |
|---|
| DS Flash + MiniMax (Recommended) | DeepSeek V4 Flash (1M ctx) | MiniMax M3 (512K ctx) | Different model families, good diversity |
| DS Flash + GLM-5.2 | DeepSeek V4 Flash (1M ctx) | GLM-5.2 (1M ctx) | Risk gets same giant context for long plans |
| DS Flash + Kimi Code | DeepSeek V4 Flash (1M ctx) | Kimi K2.7 Code (262K ctx) | Code-oriented risk lens |
Example question tool call (structure defined in assets/templates/model-selection.yaml,
validated by assets/schemas/model-selection.schema.json):
header: "Model selection for plan reviewers"
question: "I need to assign models for 3 subagent reviewers..."
options:
- "Best value — DS Flash + GPT 5 Nano" (Recommended) — $0.03/run
- "Balanced — DS Flash + Claude Haiku" — $0.08/run
- "Max depth — DS Pro + GPT 5 Nano" — $0.12/run
- "Budget — GPT 5 Nano for all" — $0.01/run
- "Custom — let me specify per reviewer"
If the user picks "Custom", ask them for each reviewer individually and
suggest sensible defaults based on their chosen model.
If Claude Code
Advise the user on the Haiku vs Sonnet vs Opus tradeoff. All three are
Anthropic models available in Claude Code:
| Model | Input/MTok | Output/MTok | Context | Reasoning | Best for |
|---|
| Claude Haiku 4.5 | $1.00 | $5.00 | 200K | Adequate | Risk reviewer — cheap, fast, still catches blind spots |
| Claude Sonnet 5 | $3.00 | $15.00 | 1M | Strong | Technical/Strategic — sweet spot for depth |
| Claude Opus 4.8 | $5.00 | $25.00 | 1M | Maximum | Both reviewers — only if plan is mission-critical |
Recommended pairs:
| Pair | Tech/Strategic | Risk | Cost/run | When |
|---|
| Sonnet + Haiku (Recommended) | Claude Sonnet 5 | Claude Haiku 4.5 | ~$0.10 | Best capability/cost balance |
| Sonnet + Sonnet | Claude Sonnet 5 | Claude Sonnet 5 | ~$0.15 | Same model everywhere (less diverse) |
| Opus + Haiku | Claude Opus 4.8 | Claude Haiku 4.5 | ~$0.18 | Max depth on technical analysis, cheap risk |
| Opus + Sonnet | Claude Opus 4.8 | Claude Sonnet 5 | ~$0.25 | Both reviewers get strong reasoning |
Example question tool call (structure in assets/templates/model-selection.yaml):
header: "Model selection for plan reviewers"
question: "I'll use 3 subagent reviewers..."
options:
- "Sonnet + Haiku" (Recommended)
- "Opus + Haiku"
- "Opus + Sonnet"
- "Sonnet for all"
- "Custom — let me specify per reviewer"
If Bring Your Own Key (BYOK)
Ask the user which models their provider supports. If unsure, recommend:
- Technical/Strategic: the strongest reasoning model available
- Risk: a different model (ideally from a different provider family)
If the user says "not sure" or "surprise me"
Recommend the best-value diversity pair:
- OpenCode Zen: DeepSeek V4 Flash (Technical/Strategic) + GPT 5 Nano (Risk) — ~$0.03/run
- OpenCode Go: DeepSeek V4 Flash (Technical/Strategic) + MiniMax M3 (Risk) — flat-rate
- Claude Code: Claude Sonnet 5 (Technical/Strategic) + Claude Haiku 4.5 (Risk) — ~$0.10/run
- BYOK: Strongest model (Technical/Strategic) + cheapest different model (Risk)
6. Map model choices to subagent configuration
If the user wants to configure opencode.json, show them the snippet:
{
"subAgents": {
"general": {
"model": "<chosen Technical/Strategic model>",
"systemPrompt": "You are a thorough, detail-oriented reviewer."
},
"explore": {
"model": "<chosen Risk model>",
"systemPrompt": "You are a skeptical, adversarial reviewer focused on finding flaws."
}
}
}
Ask if they want to apply this now or proceed with current routing (may use
the same model for all types). If they proceed without configuration, run all
3 but note in the output that model diversity was limited — the reviewer
prompts alone provide the perspective separation.
7. Spawn 3 reviewers (in parallel)
Spawn all 3 subagents at once using the task tool. Each receives the
same plan brief prefixed with their role-specific instructions.
| Reviewer | subagent_type | Lens |
|---|
| Technical | general | Feasibility, implementation gaps, technical soundness |
| Strategic | general | Goal alignment, scope correctness, priority, sequencing |
| Risk | explore | Blind spots, edge cases, failure modes, dependencies |
Reviewer 1: Technical
Use this prompt template with the plan brief inserted:
{
"subagent_type": "general",
"description": "Technical review of plan",
"prompt": "You are a TECHNICAL REVIEWER evaluating a plan. Your focus: feasibility, implementation gaps, technical correctness, and completeness.\n\nAnswer these questions with specific, actionable items:\n\n1. FEASIBILITY: Are the implementation steps technically sound? Identify any steps that are ambiguous, under-specified, or impossible as written.\n\n2. GAPS: What specific details are missing? (e.g., missing error handling, no test strategy, no rollback plan, missing configuration). Be precise — reference step numbers.\n\n3. CONSISTENCY: Do the steps internally agree? Any contradictions in approach, ordering, or assumptions?\n\n4. EFFORT ESTIMATE: Is the effort realistic for the scope? Identify any steps that look under- or over-scoped.\n\n5. DEPENDENCIES: Are all prerequisites and dependencies called out? Any implicit ones that should be explicit?\n\nPLAN BRIEF:\n<PASTE PLAN BRIEF HERE>"
}
Reviewer 2: Strategic
{
"subagent_type": "general",
"description": "Strategic review of plan",
"prompt": "You are a STRATEGIC REVIEWER evaluating a plan. Your focus: goal alignment, scope, priority, and completeness relative to objectives.\n\nAnswer these questions with specific, actionable items:\n\n1. GOAL ALIGNMENT: Does every step clearly serve the stated goal? Identify any steps that are off-track, scope-creep, or not connected to the goal.\n\n2. SCOPE: Is the scope right? Too narrow (misses important outcomes) or too broad (trying to solve everything)?\n\n3. PRIORITY: Are the steps in the right order? Identify sequencing issues — steps that should come earlier or later, or missing prerequisites.\n\n4. COMPLETENESS: Are there obvious missing steps or phases? What would a reasonable person expect that isn't here, including whether stated execution paths actually reach far enough to meet the goal?\n\n5. SUCCESS CRITERIA: Does the plan define what 'done' looks like? If not, what's missing?\n\nPLAN BRIEF:\n<PASTE PLAN BRIEF HERE>"
}
Reviewer 3: Risk
{
"subagent_type": "explore",
"description": "Risk review of plan",
"prompt": "You are a RISK REVIEWER evaluating a plan. Your focus: blind spots, edge cases, failure modes, and unstated assumptions.\n\nAnswer these questions with specific, actionable items:\n\n1. BLIND SPOTS: What is the plan not considering? Look for implicit assumptions that could be wrong, stakeholders not mentioned, or system boundaries not considered. If the plan states where or how a mechanism executes (a hook, a CI job, a trigger, a caller), explicitly assess who or what bypasses that path and whether the stated goal is actually met given that reach.\n\n2. FAILURE MODES: For each step, what's the most likely failure? What's the worst-case outcome? Be specific — reference step numbers.\n\n3. EDGE CASES: What scenarios would break this plan? Consider: incomplete data, external dependencies failing, concurrent changes, user error.\n\n4. RECOVERY: If a step fails, is there a rollback or recovery path? Identify steps where failure = irreversible or costly.\n\n5. RESILIENCE: How brittle is this plan? Could small changes in assumptions invalidate large parts of it?\n\nPLAN BRIEF:\n<PASTE PLAN BRIEF HERE>"
}
8. Receive and collate results
Each subagent returns a structured review. Collect all 3 and compile a
Consolidated Review Report following the structure defined in
assets/templates/review-report.yaml.
The template is validated against assets/schemas/review-report.schema.json
— run scripts/validate-review-report.sh on the generated report to confirm
schema compliance.
Required sections: Model Configuration, Structural Validation, Implementation
Architecture, Scores, Critical Issues, Moderate Concerns, Strengths, Next Actions.
9. Present to the user
Present the consolidated report with a preamble that includes the models used:
"I ran this plan through 3 independent reviewers using (Technical/Strategic) and (Risk). Here's the consolidated report:"
If the user wants to dig deeper on any finding, offer to spawn a follow-up
investigation subagent with the relevant context.
10. Classify findings and resolve — this step is not optional
Step 9's presentation is a progress update, not sign-off. Before the review counts as
finished, sort every item in critical_issues and moderate_concerns into one of two
buckets:
- Editorial — a contradiction, missing detail, wrong ownership, or unspecified
mechanism with one clearly correct fix given the rest of the plan and this repo's
existing conventions. No real tradeoff exists; a competent engineer looking at the
same facts would land on the same fix. ALWAYS apply these directly to the plan file —
don't make the user approve something that isn't actually a choice.
- Decision — a genuine tradeoff with two or more valid answers (hard-fail vs.
advisory rollout, gate-on-condition vs. run-unconditionally, spike-first vs.
attempt-and-recover). No amount of re-reading the repo resolves these; only the plan
owner's judgment does.
For decision-classified items, NEVER leave them sitting in ## Open Questions for the
user to notice later — run a short interview immediately: one question at a time, each
with concrete mutually-exclusive options plus room for free text, matching
guided-interview's pattern. End with a one-message recap of every answer and get
explicit confirmation before writing anything into the plan.
Fold both outcomes back into the plan file, not just into chat:
- Editorial fixes land directly in the relevant section (Scope, Phases, Verification).
- Decisions land in a
## Decisions section, each with the chosen option and why the
alternative didn't win. If a decision carries a review-later condition (e.g. "flip to
hard-fail after N clean runs"), state it as a concrete, checkable revisit trigger —
never "revisit later" — the same rule design-debate enforces on its own verdicts.
- A
## Decisions heading is itself an ADR-capture trigger in this repo
(check-undocumented-decisions.sh flags any ## Decision heading and fails
hk's pre-commit check). Check whether an existing ADR already covers the plan's
topic; if not, run adr-capture before treating the amendment as done — this is a
hard gate, not a suggestion, since the pre-commit hook will block the commit either
way.
11. (Optional) Persist a standalone finding
If the review surfaced something beyond this one plan — a pattern likely to recur in
future reviews, a gap in a related skill — capture it as a finding via context-file,
separate from the decisions already folded into the plan in Step 10.
When NOT to Use
- For one-off notes, scratch files, or non-plan documents — use
session-reflection instead
- For plans outside
.context/plans/ — the reviewer prompts assume .context/ frontmatter conventions
- When the plan is trivially small (1 paragraph, no steps) — the overhead of 3 subagents is not justified
- When the user explicitly asks for a quick opinion, not a full audit
Anti-Patterns
NEVER — Skip the plan brief and just pass the file path
SYMPTOM: Reviewer produces shallow, generic analysis because they lack the full plan context. Each reviewer may interpret the plan differently, leading to inconsistent feedback.
CONSEQUENCE: The review misses critical issues because no reviewer had the complete picture. The final report contradicts itself across reviewer sections.
WHY: Subagents cannot read files unless they have the general type with file access. The plan brief ensures every reviewer works from the same complete information regardless of subagent capability.
BAD: Sending "review .context/plans/foo.md" as the prompt.
GOOD: Extracting the plan content into a self-contained brief first.
NEVER — Spawn reviewers sequentially
SYMPTOM: The review takes 3× longer than necessary. The user waits while each subagent initialises and runs in turn.
CONSEQUENCE: Context builds up between sequential calls, increasing cost and delay. The user may interrupt before all reviews complete.
WHY: They are fully independent — sequential spawning wastes time and context. Always use parallel tool calls.
BAD: Spawn Technical, wait for result, spawn Strategic, wait, spawn Risk.
GOOD: Spawn all 3 in one message with 3 parallel task tool calls.
NEVER — Proceed without asking about models first
SYMPTOM: The review uses the same model for all 3 reviewers, producing three reports with the same blind spots. The user never knew they had a choice.
CONSEQUENCE: The cost of model diversity awareness was zero, but the cost of missing a critical blind spot is unbounded. The user loses trust when they discover routing was available but unused.
WHY: Model diversity is the main lever for catching different blind spots.
Asking first gives the user control over cost vs. depth and lets them
configure routing if needed. Skipping this step silently defaults to a single
model for all reviewers.
BAD: "Reviewing the plan now with 3 reviewers..."
GOOD: "Before I start, which models should I use for the reviewers?"
NEVER — Present raw subagent output without attribution
SYMPTOM: The user receives three blocks of undifferentiated text and must guess which reviewer produced which finding. Conflicting opinions cannot be traced to their source.
CONSEQUENCE: Actionable findings get mixed with noise because the user cannot weigh each reviewer's credibility. The strategic reviewer's insight carries the same weight as the risk reviewer's false alarm.
WHY: The user needs to know which perspective each finding comes from. Raw output without labels loses the multi-reviewer value.
BAD: Paste three blocks of text with no headers.
GOOD: Organise by reviewer with clear headings and attribution.
NEVER — Modify the plan brief differently per reviewer
SYMPTOM: Two reviewers disagree on a key question, but the disagreement is caused by different input, not different analysis. The conflict is an artefact, not a signal.
CONSEQUENCE: False conflicts waste time in resolution meetings. Real consensus is hidden because each reviewer had different assumptions.
WHY: The whole point is that different reviewers reach different conclusions from the same information. Giving each a different brief invalidates the comparison.
BAD: Giving the Strategic reviewer extra context about project history.
GOOD: Identical brief to all 3; the differences in output come from their lenses.
NEVER — Use the same subagent type for all 3 reviewers
SYMPTOM: All 3 reviewers converge on the same set of concerns. The "multi-perspective" review effectively becomes a single-perspective review with 3× the cost.
CONSEQUENCE: The review provides no more value than a single pass, yet costs 3× in both time and tokens. The user pays for diversity but receives uniformity.
WHY: Model diversity is the main lever for catching different blind spots. If all 3 use the same model via the same subagent type, you lose the independent-perspective benefit — they'll converge on similar blind spots.
BAD: All 3 use general.
GOOD: Mix general and explore (and more if your opencode.json routes them differently).
NEVER — Leave a decision-type finding sitting in Open Questions after the review
SYMPTOM: The consolidated report lists a real tradeoff (e.g. hard-fail vs. advisory
rollout) as an Open Question, the user reads the report, and the conversation moves on.
Nobody circles back.
CONSEQUENCE: The plan ships with the tradeoff unresolved. Implementation starts
against whichever reading of the plan happened to be top of mind, not a decision anyone
actually made — the exact failure mode this skill's Step 10 exists to prevent.
WHY: A report is a snapshot, not a commitment. Presenting findings (Step 9) and
resolving them (Step 10) are different steps; skipping straight from one to "the review
is done" drops every decision-type finding on the floor.
BAD: Present the consolidated report, thank the user, stop.
GOOD: Present the report, then interview the user on every decision-type finding
before treating the plan as amended (Step 10).
Advanced: Model Routing Configuration
The review's power comes from each subagent having a different cognitive bias
— which is best achieved by routing them to different underlying models via
opencode.json.
How to configure
In your opencode.json, map subagent types to specific models:
{
"subAgents": {
"general": {
"model": "claude-sonnet-5",
"systemPrompt": "You are a thorough, detail-oriented reviewer."
},
"explore": {
"model": "deepseek-v4-flash",
"systemPrompt": "You are a skeptical, adversarial reviewer focused on finding flaws."
}
}
}
If model routing is not configured
If your opencode setup does not support per-type model routing:
- The reviewer prompts (different lenses, different question sets) still provide
some diversity of analysis — they ask different questions of the same plan.
- The
explore subagent type (Risk reviewer) is a different agent implementation
even on the same model, which may produce different outputs due to different
tool access and system prompts.
- Make sure to note this limitation when presenting the report.
Verification
After presenting the consolidated review report, run these checks before
signing off:
-
Schema compliance — run the validation script to verify the report output:
scripts/validate-review-report.sh <path-to-report>
This checks the report conforms to the required structure and all sections
are present. Re-run if validation fails.
-
Model attribution check — confirm the report states which models were
used for Technical/Strategic and for Risk, and whether routing was
pre-configured or user-selected.
-
Structural validation captured — confirm the plan's frontmatter validation
results and body structure inference are included in the report. The structural
validation must pass before the review is considered complete.
-
Actionability review — verify the report ends with specific Recommended
Next Actions that reference specific reviewer findings. Each action must be
concrete and directly address a finding.
-
Investigation offered — ask the user if they want to dig deeper on any
finding. If they accept, run the investigation before concluding.
-
Every critical/moderate finding is classified and resolved — confirm each item
from critical_issues and moderate_concerns is either applied as an editorial fix
in the plan file, or answered through the Step 10 interview and recorded in a
## Decisions section. Run grep -c '^- ' <finding-list> against the plan's diff if
unsure whether anything was dropped.
If any of these checks fail, correct the issue before presenting the report as
final.
Error Handling
| Situation | Response |
|---|
| Report validation fails | Check the report against assets/schemas/review-report.schema.json for missing or malformed sections; otherwise regenerate |
| A reviewer does not return results | Re-spawn that reviewer individually with the same brief; if a reviewer fails twice, fall back to the other two |
| User has no preference on models | Recommend the best-value pair for their detected environment; stop if they confirm |
| Plan is trivially small | Skip if fewer than 2 H2 sections — do a single pass instead |
| Review reveals a critical issue | Stop if critical and present immediately; ask if the user wants to fix before continuing |
When a Reviewer Fails
If a subagent reviewer returns an error or times out, do not block the entire
review. Spawn a replacement using the same subagent type and brief. If the
replacement also fails, omit that perspective and proceed with the remaining
reviews. Note the failure in the final report so the user knows a perspective
is missing.
Templates
This skill follows the repository convention of YAML template + JSON Schema + validation script
for all structured artifacts. See the project rules for the convention.
References
- Model Routing Reference — detailed opencode.json
configuration examples for model diversity
context-file skill — to persist findings from the review, and to write the plan's
## Decisions section (Step 10)guided-interview skill — the one-question-at-a-time pattern Step 10 follows when
resolving decision-type findingsdesign-debate skill — source of the "always name a concrete revisit trigger" rule
Step 10 applies to time-boxed decisionssession-reflection skill — for single-agent session-end reflection (complementary use)adr-capture skill — required, not optional, once a plan gains a ## Decisions
section (Step 10) — this repo's pre-commit hook enforces it
