Feature request: fresh-context adversarial plan-review in plan mode (audit before ExitPlanMode)

Open 💬 0 comments Opened Jul 2, 2026 by johanneshauer

Problem

Plans produced during EnterPlanMode go into execution largely unchallenged.
The built-in Plan subagent is capable, but it shares context with the driving
conversation — so biases, stale claims, and dropped edge cases accumulated
during exploration tend to persist into the plan.

Common failure modes observed across ~6 weeks of use on one multi-target
embedded project:

File paths or function names referenced from memory that have since moved
"Out of scope" / "future work" items never persisted to any tracker, lost at session end
Internal inconsistencies (file counts, addresses, version pins drifting between sections)
Edge cases the conversation already discussed but the plan quietly dropped
Claims about library/API behavior that were assumed, not verified

Catching these after implementation has started is expensive; catching them in
plan mode is nearly free.

Proposed solution

A plan-review workflow, invokable from within plan mode (as a command or as a
flag on ExitPlanMode), that audits the current plan file before it's
approved for execution. The key property: one review phase runs in a genuinely
fresh context, not influenced by the driving conversation.

Clean-room specification

Scope

A plan-mode augmentation that audits the active plan file. It produces
findings, applies critical fixes, and returns control to the user — it does
NOT automatically exit plan mode.

Functional requirements

FR-1 — Input contract

Input: path to the currently active plan file
The feature must not modify any file other than the plan file, and must not

modify the plan file before findings are applied

The feature must not call ExitPlanMode autonomously

FR-2 — Phase 1: self-review (driving agent)

The driving agent reads the plan end-to-end
Evaluates against a fixed category set. At minimum:

Logic & data flow consistency
Internal consistency (numeric values, identifiers, references match across sections)
Completeness (every described change has a listed file and vice versa)
Naming & collision risk (new identifiers don't conflict with existing ones)
External claims (referenced paths, issue numbers, library features) — verified against current state, not assumed
Scope discipline (no unrequested complexity or out-of-scope edits)

Output: numbered findings, each tagged by severity (Critical / Important / Minor / Nitpick) with location and suggested fix

FR-3 — Phase 2: independent review (fresh subagent)

A Plan-type subagent is spawned with no conversation context
The driving agent composes a self-contained brief including: project background, plan file path, list of files the reviewer should read for verification, a checklist mirroring Phase 1 categories, requested output format
The subagent performs the review independently and returns findings
The subagent must not inherit conversation state from the driving session

FR-4 — Phase 3: deferred-items audit

Every item in "Out of Scope", "Future Work", "Deferred", "Not in V1" (or equivalent) sections is checked for a persistent home — issue tracker entry, backlog doc, durable memory
Orphaned deferrals are flagged as Important
The feature suggests an appropriate persistence mechanism per item type

FR-5 — Phase 4: consolidation

Findings from all phases are deduplicated
Critical and Important fixes are applied to the plan file
A summary is reported to the user: counts by severity, what was fixed, what was merely noted
Control returns to the user; next step (iterate, approve, abandon) is a user decision

Non-functional requirements

NFR-1: Phase 2's subagent spawn must be genuinely context-free. Smuggling conversation state into the brief (e.g., by pasting the entire conversation as background) defeats the purpose.
NFR-2: Phase 4 must be non-destructive — edits restricted to the plan file.
NFR-3: The feature must be re-runnable on the same plan file without cumulative corruption.

Acceptance criteria

AC-1: Given a plan referencing a file that no longer exists at the cited path, at least one phase flags it as Critical or Important
AC-2: Given a plan with out-of-scope items not tracked anywhere, Phase 3 flags each as an orphaned deferral
AC-3: Given internal inconsistency (e.g., stated file count differs from actual listed files), at least one phase flags it
AC-4: Given a clean plan, the feature returns zero findings without modifying the plan file
AC-5: In a corpus of real plans, Phase 2 findings differ from Phase 1 findings at least some of the time — measurable evidence that the independent-context review adds marginal value over self-review alone

Out of scope for initial implementation

Automatic re-evaluation loops after fixes (one pass per invocation)
Batch review of multiple plans
Review of non-plan artifacts (code diffs, etc. — that's a separate feature)
Automatic approval and ExitPlanMode — remains a user decision

Integration options (choose one)

A. New built-in command (e.g. /plan-review) available in plan mode
B. Flag on ExitPlanMode (e.g. --review-first) that runs the workflow before allowing exit
C. Prompt-level guidance for the driving agent to invoke the workflow unprompted before calling ExitPlanMode

Option A or B preferred — prompt guidance alone is less reliable.

Alternatives considered

Make the existing Plan subagent more adversarial via prompt tuning. Tried

locally; insufficient because the subagent still inherits context when
spawned from plan mode, so it remains subject to the same conversation
biases as the driving agent.

Manual user-driven review. Works, but few users will think to do it

every time. The value of a built-in feature is that it's on-by-default for a
class of failures most users won't recognize as happening.

Evidence of value

Plan mode sees ~70 plans created in ~6 weeks on one machine; most are
discarded after review. Per-invocation metrics live in the live stats
block below, auto-regenerated after every formal skill invocation.

Live skill statistics

Formal invocations: 81
Phase 1 total findings: 323
Phase 2 total findings: 757
P2 findings per P1 finding (pre-dedup)¹: 2,34
Dedup total: 918
Fixes applied: 528
Orphaned deferrals caught: 1

Per-invocation (most recent first):

| Timestamp (UTC) | Plan hash | P1 | P2 | Dedup | Fixed | Orphans |
| --------------------- | --------- | -- | -- | ----- | ----- | ------- |
| 2026-07-01T19:28:21Z | e225b172 | 0 | 2 | 0 | 0 | 0 |
| 2026-07-01T19:25:14Z | e225b172 | 1 | 4 | 3 | 3 | 0 |
| 2026-07-01T19:16:55Z | e225b172 | 4 | 6 | 7 | 7 | 0 |
| 2026-06-29T13:13:30Z | 4dc08f25 | 1 | 1 | 2 | 1 | 0 |
| 2026-06-29T13:07:29Z | 4dc08f25 | 5 | 6 | 10 | 8 | 0 |
| 2026-05-20T16:06:11Z | deb23548 | 2 | 6 | 8 | 0 | 0 |
| 2026-05-20T16:01:44Z | deb23548 | 2 | 10 | 12 | 3 | 0 |
| 2026-05-20T15:54:55Z | deb23548 | 5 | 11 | 16 | 4 | 0 |
| 2026-05-20T15:40:25Z | deb23548 | 7 | 13 | 20 | 12 | 0 |
| 2026-05-19T17:02:56Z | 47de2ccc | 4 | 11 | 15 | 6 | 0 |
| 2026-05-19T16:56:46Z | 7005575c | 4 | 3 | 7 | 6 | 0 |
| 2026-05-19T16:29:57Z | 7005575c | 3 | 10 | 13 | 7 | 0 |
| 2026-05-19T16:24:44Z | 7005575c | 7 | 15 | 21 | 14 | 0 |
| 2026-05-19T10:15:04Z | ae0b5395 | 0 | 0 | 0 | 0 | 0 |
| 2026-05-19T10:13:30Z | ae0b5395 | 6 | 4 | 10 | 4 | 0 |
| 2026-05-19T10:10:34Z | ae0b5395 | 5 | 13 | 15 | 9 | 0 |
| 2026-05-19T10:02:41Z | ae0b5395 | 13 | 15 | 22 | 13 | 0 |
| 2026-05-18T22:46:17Z | cc26a4c9 | 0 | 0 | 0 | 0 | 0 |
| 2026-05-18T22:45:13Z | cc26a4c9 | 0 | 1 | 1 | 1 | 0 |
| 2026-05-18T22:43:03Z | cc26a4c9 | 0 | 3 | 3 | 1 | 0 |
| 2026-05-18T22:41:04Z | cc26a4c9 | 0 | 3 | 3 | 1 | 0 |
| 2026-05-18T22:25:47Z | cc26a4c9 | 5 | 10 | 14 | 9 | 0 |
| 2026-05-18T22:15:02Z | cc26a4c9 | 5 | 17 | 20 | 12 | 0 |
| 2026-05-18T14:28:17Z | cc26a4c9 | 6 | 15 | 16 | 13 | 0 |
| 2026-05-18T14:19:47Z | cc26a4c9 | 7 | 15 | 14 | 8 | 0 |
| 2026-05-18T13:09:22Z | 91e7158c | 2 | 0 | 2 | 0 | 0 |
| 2026-05-18T13:06:15Z | 91e7158c | 4 | 17 | 12 | 11 | 0 |
| 2026-05-18T13:01:23Z | 91e7158c | 4 | 20 | 19 | 18 | 0 |
| 2026-05-18T12:53:24Z | 91e7158c | 11 | 23 | 22 | 11 | 0 |
| 2026-05-18T07:53:38Z | 3ac6e827 | 0 | 0 | 0 | 0 | 0 |
| 2026-05-18T07:51:44Z | 3ac6e827 | 2 | 5 | 7 | 2 | 0 |
| 2026-05-18T07:44:46Z | 3ac6e827 | 2 | 13 | 14 | 8 | 0 |
| 2026-05-18T07:36:31Z | 3ac6e827 | 13 | 15 | 22 | 13 | 0 |
| 2026-05-13T16:23:00Z | 096a1902 | 5 | 18 | 20 | 10 | 0 |
| 2026-05-13T16:16:46Z | 096a1902 | 14 | 15 | 22 | 20 | 0 |
| 2026-05-13T13:55:30Z | 42e96514 | 0 | 5 | 5 | 0 | 0 |
| 2026-05-13T13:53:45Z | 42e96514 | 1 | 8 | 9 | 4 | 0 |
| 2026-05-13T13:49:54Z | 42e96514 | 2 | 8 | 9 | 5 | 0 |
| 2026-05-13T13:45:16Z | 42e96514 | 6 | 12 | 14 | 9 | 0 |
| 2026-05-13T12:49:26Z | e977936f | 1 | 5 | 6 | 0 | 0 |
| 2026-05-13T12:47:24Z | e977936f | 3 | 11 | 12 | 6 | 0 |
| 2026-05-13T12:41:43Z | e977936f | 3 | 12 | 13 | 8 | 0 |
| 2026-05-13T12:35:09Z | e977936f | 6 | 11 | 14 | 9 | 0 |
| 2026-05-13T09:53:08Z | d9e661b4 | 0 | 0 | 0 | 0 | 0 |
| 2026-05-13T09:52:23Z | d9e661b4 | 0 | 6 | 6 | 2 | 0 |
| 2026-05-13T09:50:12Z | d9e661b4 | 3 | 12 | 15 | 5 | 0 |
| 2026-05-13T09:45:31Z | d9e661b4 | 14 | 14 | 25 | 16 | 0 |
| 2026-05-12T22:08:05Z | 5a936ed1 | 1 | 10 | 11 | 4 | 0 |
| 2026-05-12T22:04:00Z | 5a936ed1 | 2 | 18 | 18 | 15 | 0 |
| 2026-05-12T21:59:54Z | 5a936ed1 | 3 | 15 | 14 | 13 | 0 |
| 2026-05-12T19:26:47Z | a23c7e20 | 3 | 4 | 7 | 3 | 0 |
| 2026-05-12T19:23:55Z | a23c7e20 | 3 | 14 | 12 | 7 | 0 |
| 2026-05-12T19:17:47Z | a23c7e20 | 4 | 18 | 14 | 10 | 0 |
| 2026-05-12T10:44:30Z | bf6687d5 | 5 | 0 | 5 | 1 | 0 |
| 2026-05-12T10:34:28Z | bf6687d5 | 5 | 5 | 10 | 6 | 0 |
| 2026-05-12T10:30:24Z | bf6687d5 | 10 | 10 | 20 | 8 | 0 |
| 2026-05-12T10:26:32Z | bf6687d5 | 9 | 15 | 22 | 13 | 0 |
| 2026-05-11T20:28:37Z | 4208a9f8 | 0 | 0 | 0 | 0 | 0 |
| 2026-05-11T20:27:58Z | 4208a9f8 | 1 | 5 | 5 | 3 | 0 |
| 2026-05-11T20:25:47Z | 4208a9f8 | 6 | 15 | 14 | 9 | 0 |
| 2026-05-11T20:20:18Z | 4208a9f8 | 9 | 16 | 18 | 11 | 0 |
| 2026-05-11T19:41:56Z | ab296b7d | 0 | 2 | 2 | 1 | 0 |
| 2026-05-11T19:40:51Z | ab296b7d | 5 | 7 | 10 | 7 | 0 |
| 2026-05-11T19:38:12Z | ab296b7d | 7 | 12 | 16 | 10 | 0 |
| 2026-05-11T19:31:20Z | ab296b7d | 9 | 16 | 23 | 13 | 0 |
| 2026-05-11T09:56:56Z | ed5a6f40 | 2 | 0 | 2 | 0 | 0 |
| 2026-05-11T09:55:18Z | ed5a6f40 | 4 | 12 | 16 | 4 | 0 |
| 2026-05-11T09:51:20Z | ed5a6f40 | 2 | 15 | 17 | 10 | 0 |
| 2026-05-11T09:46:33Z | ed5a6f40 | 9 | 20 | 28 | 13 | 0 |
| 2026-05-07T10:29:40Z | 52131ebc | 0 | 4 | 4 | 1 | 0 |
| 2026-05-07T10:26:45Z | 52131ebc | 3 | 10 | 8 | 4 | 0 |
| 2026-05-07T10:23:11Z | 52131ebc | 2 | 14 | 12 | 8 | 0 |
| 2026-05-07T10:13:15Z | 52131ebc | 5 | 12 | 14 | 9 | 0 |
| 2026-04-17T20:38:24Z | 40362b84 | 1 | 0 | 1 | 1 | 0 |
| 2026-04-17T20:36:27Z | 40362b84 | 3 | 9 | 10 | 4 | 0 |
| 2026-04-17T20:33:41Z | 40362b84 | 1 | 12 | 12 | 7 | 0 |
| 2026-04-17T20:28:43Z | 40362b84 | 9 | 10 | 17 | 11 | 0 |
| 2026-04-16T19:12:00Z | 01e1c3d5 | 4 | 12 | 14 | 7 | 0 |
| 2026-04-16T14:30:00Z | 2d398c57 | 0 | 5 | 5 | 3 | 1 |
| 2026-04-16T14:00:00Z | 93542016 | 5 | 10 | 12 | 8 | 0 |
| 2026-04-16T13:20:00Z | 726e9f1a | 3 | 6 | 5 | 5 | 0 |

¹ Phase 2 is an independent review; its findings may overlap with Phase 1.
Ratio is a directional signal of fresh-context value, not a strict delta.

Caveats

Single machine, single user, small sample size.
Plan basenames in the log are hashed (sha256 first 8 chars): light

obfuscation only, not cryptographic privacy — dictionary-attackable if
plan-name conventions are known.

Timestamps and counts in seeded rows are best-effort transcript

reconstructions, not live observations.

Platform: Linux (WSL2 and native Ubuntu) only; macOS support not validated for

the local reference implementation.

---

<details>
<summary><strong>Reference implementation</strong> — the plan-review skill we run locally (our internal memory system genericized to "memory store")</summary>

~~~~markdown
---
name: plan-review
description: >
Critical review of the current plan for mistakes, errors, logic flaws, missed items,
and unsaved deferred work. Two phases: self-review then independent agent review.
Use when the user says "review plan", "plan review", "check the plan", or
"review for errors". Works for any project and any session type.
user-invocable: true
allowed-tools: Read, Glob, Grep, Agent, Bash, WebFetch, WebSearch
---

Plan Review — Two-Phase Critical Audit

Review the active plan file for mistakes, errors, logic flaws, completeness,
and unsaved deferred items. Two phases: self-review (fast, biased) then
independent agent review (slower, fresh perspective).

Requires: an active plan file (path from the plan-mode system message).

---

Phase 1: Self-Review

Read the plan file top to bottom. Check every section against these categories.

1a. Logic & Data Flow

Trace every data path end-to-end. Does data get from source to destination

through every layer described? Are there gaps or impossible hops?

Does the plan's model match the existing architecture? Read the relevant

architecture docs (not from memory — Read the actual files) and check for
contradictions.

Are there circular dependencies, deadlocks, or race conditions in the

proposed design?

If the plan modifies a shared contract (protocol, API, schema), trace all

consumers — are they all updated?

1b. Internal Consistency

Do numbers match across sections? (counts, addresses, sizes, pin numbers,

version numbers, issue references)

Do file paths mentioned in one section exist in the "Files modified" table

and vice versa?

Do acceptance criteria actually test the claims they're attached to? Run

verification commands mentally — will they catch the failure mode?

Do "out of scope" items match the issue tracker actions?

1c. Completeness

For every file in "Files modified", is there a section describing what

changes? For every described change, is the file listed?

Are there files NOT in the plan that obviously need changing? Common misses:

generated files after schema changes, CI workflows after new directories,
inventory/index files after new docs, cross-reference updates in related docs.

Does every new concept get a corresponding acceptance criterion?
Does every decision get a rationale?

1d. Naming & Collisions

If adding constants, registers, types, or identifiers: will the build system

or generator produce name collisions? Check the generator's naming logic.

If adding files or directories: do names collide with existing ones?
If reusing a name from a different context: is the disambiguation clear?

1e. Currency & Best Practice

For anything in the plan with a version, release cadence, or evolving guidance,
verify against current sources — not training data:

Libraries / SDKs / frameworks: feature support, deprecations, API

signatures, the officially recommended pattern for X

Manufacturer docs / datasheets / reference designs: pin maps, register

values, electrical limits, recommended circuits

Vendor or community examples: still maintained, or superseded?
Standards / RFCs / protocol specs: current version, errata
Tooling: build system, container images, linters, runtime versions

Rule: if it's findable with a web search or vendor doc lookup, look it up
(WebSearch, WebFetch). If a check was skipped (paywalled, no canonical
source, etc.), say so explicitly so the user knows what's still on assumption.

Respect deliberate pinning: a project that pins versions (a lockfile, a pinned
container tag, a submodule commit) did so on purpose. Flag a pin only when its
staleness matters — a security fix, an end-of-life runtime, or a feature the
plan actually needs — not merely because a newer release exists.

1f. Repo-Internal References

File at specific path / line — verify it still exists there
GitHub issue by number — verify state matches the plan's assumption
Cross-references between plan sections still resolve

1g. Scope Discipline

Does the plan accidentally modify files it claims are out of scope?
Does the plan introduce unnecessary complexity (abstractions, config,

flexibility) beyond what the task requires?

1h. Spec & Product Alignment

The other checks verify the plan is internally coherent. This one verifies it
is the right plan: still solving the asked-for problem, grounded in things
that actually exist, and good for the product and its users.

Re-anchor to the request. Re-read the original issue / task / user

request (from the plan-mode system message or the linked issue). Does the
plan still solve that problem? A plan revised repeatedly — especially
across plan-perfect iterations — can drift until it solves a neighboring
problem instead. Flag divergence from the asked-for intent.

Hallucination. Every concrete thing the plan names — a function,

register, file, API, config key, hardware pin, capability, command — must
trace to a file you Read or a doc you fetched. §1f catches path:line
references; this catches the unqualified ones (e.g. "call fc_calibrate()"
with no path). Flag anything that cannot be traced — it may not exist.

Product & user. Step back from the diff. Does the plan serve the end

user and the product, not just the developer? Re-anchor to whoever this
project's actual end user is (from its README / CLAUDE.md / the original
request) and judge against them. Flag changes that are technically fine but
degrade the product experience.

Drift can be good. Distinguish drift away from intent (a finding) from

drift beyond intent that genuinely improves the product. A real
improvement is NOT scope creep and NOT a §1g violation — note it neutrally
so the user can confirm or decline it; do not flag it as an error.

Severity for this section:

Plan solves the wrong problem, or relies on a thing confirmed not to exist → [CRITICAL]
Product / user-experience degradation, or a plausible claim that could not

be verified → [IMPORTANT]

A product judgment call the user should weigh → [MINOR]

1i. Delegation Opportunities

Map the plan's work onto the available agent pool. Identify chunks of work
that should be delegated and chunks that must stay in the orchestrator.

Discover this project's agent pool — don't assume a fixed one. Read the
subagent_type options available to you this session (the harness lists them)
and the project's .claude/agents/*.md definitions. Projects differ: some ship
domain specialists (e.g. a UI agent, a comms agent, a quality/test agent),
others ship none. Always-available built-ins to fall back on:

Explore (RO) — search/locate code
Plan (RO) — architectural design / read-only critique
general-purpose (RW) — anything that doesn't fit a specialist

Prefer a project's domain specialist when the work falls cleanly in its
territory; otherwise use the built-ins.

For each phase / section of the plan, answer:

Territory match? Does the work fall cleanly under one of the project's

RW specialists? If yes — the plan should explicitly assign that agent.

Read-only investigation? Use Explore (search/locate) or Plan

(architectural read) — never burn an RW agent on read-only work.

Independent + parallelizable? Two or more chunks with no shared files

and no result-dependency → propose spawning them in one message
(parallel). Document the file set each agent owns; flag any file that two
agents would both touch (forbidden — keep in parent or serialize).

Cross-disciplinary iteration? Multiple experts must challenge each

other's assumptions on the same artifact → propose an Agent Team via
TeamCreate (rare). Heuristic: if a single PR reviewer would say "I'm not
qualified to judge half of this", a team is justified; otherwise overkill.

Context bloat risk? Will execution flood the orchestrator with file

contents it won't reference again? → delegate read-heavy work to Explore
and have it return only summaries.

Stay in parent? Single-file edits, shared-contract changes (a schema,

protocol, or API file), cross-territory coordination, and the final
consolidation step belong in the parent — don't delegate them.

Tag each finding with [DELEGATION] alongside its severity:

CRITICAL: plan is infeasible without delegation (context blowup, true conflict)
IMPORTANT: significant waste — sequential work that's trivially parallel,

or RW agent assigned to read-only work

MINOR: small efficiency gain
NITPICK: stylistic ("you could also delegate X")

1j. Execution Strategy Section

The plan must include an "Execution Strategy" section near the end that
lists, for each phase, the proposed dispatch:

Which agent (subagent_type) the phase delegates to, or "stays in parent"
Which other phases (if any) run in parallel in the same message
Files each agent owns (must not overlap with siblings in the same parallel batch)

This section is the contract between plan and execution. If missing or
incomplete, flag as [DELEGATION][IMPORTANT]. Briefs themselves are written
at execution time, not in the plan — they'd go stale across plan revisions.

Example (substitute this project's own specialists for the <…> placeholders):

## Execution Strategy

Phase 3.1 (module A work) → <specialist-a> ┐
Phase 3.2 (module B work) → <specialist-b> ├ parallel batch (one message)
Phase 3.3 (test scaffold) → <quality-agent> ┘
Phase 3.4 (regen + wire) → stays in parent (touches the shared contract)

Output: numbered list of findings, each tagged [CRITICAL], [IMPORTANT],
[MINOR], or [NITPICK], with location in the plan and suggested fix.
Findings from §1i or §1j carry an additional [DELEGATION] tag.

Apply all CRITICAL and IMPORTANT fixes to the plan file immediately.

---

Phase 2: Independent Agent Review

Spawn a Plan agent with NO conversation context. It reads the plan and
relevant repo files independently, then critiques.

Composing the agent brief

The agent has never seen this conversation. The brief must be self-contained:

Background (3-5 sentences): what the project is, what the plan does,

what the key architectural constraints are. Be specific — name the
technologies, patterns, and invariants the agent should check against.
Then quote the original request / issue verbatim (a paraphrase hides
drift) so the agent can judge the plan against the real ask.

Plan file path: tell the agent to Read it first.

Context files to read: list the specific repo files the agent needs to

verify the plan's claims. Include:

Architecture / design docs (cite specific line ranges if the file is long)
Schema or contract files the plan modifies
Generator scripts or build files the plan depends on
The "before" state of files the plan will edit
Any config files (CI, sdkconfig, package.json) affected

Review checklist (paste into the prompt):

Logic errors: does the data flow make sense?
Missing items: files or changes that should be in the plan but aren't?
Consistency: do identifiers, addresses, paths match across plan and repo?
Naming: will generators or build tools produce collisions?
Currency & best practice: are library / SDK / framework / manufacturer /

standards claims verified against current docs (use WebSearch /
WebFetch when findable), or resting on training data? Flag every
assumption that was not verified.

Feasibility: can the system actually do what the plan claims?
Acceptance criteria: do they verify what they say they verify?
Scope: does the plan touch things it shouldn't, or miss things it should?
Spec & product alignment: does the plan still solve the original

request, or has it drifted? Is every concrete thing it names (function,
register, file, API, pin, capability) traceable to a real file or doc,
or possibly hallucinated? Does it serve the product's actual end user
(re-anchor to whoever that is for this project)? Genuine improvements
beyond the spec are fine: note them, don't flag them.

Delegation: does the plan include an "Execution Strategy" section

mapping phases to specific agents (this project's .claude/agents/*
specialists, falling back to the built-in Explore, Plan, and
general-purpose)? Are independent chunks dispatched in parallel (one
message)? Any two agents touching the same file (forbidden)? Any RW
agent doing read-only work? Should the work be an Agent Team via
TeamCreate instead of plain subagents (rare — only if mid-task
communication between disciplines is genuinely needed)? Tag these
findings with [DELEGATION].

Output format: "Numbered list. Each: [SEVERITY: critical/important/minor/

nitpick], the issue, where in the plan, suggested fix. Under 800 words."

Spawning

Agent({
  description: "Independent plan review",
  subagent_type: "Plan",
  prompt: <composed brief>
})

Run in foreground — we need findings before proceeding.

---

Phase 3: Deferred Items Audit

Plans often list "out of scope" or "future work" items. These MUST be persisted
somewhere that survives the session — otherwise they vanish.

Check each deferred item has a home

For every item in "Out of Scope", "Future Work", "Deferred", "Not in V1",
or similar sections:

Issue tracker (preferred): is there a GitHub/Linear/Jira issue for it?

If not, flag it. The plan should include creating one.

Session file / backlog: does the project use session instruction files

or a backlog doc? Is the item listed there with a link to the issue?

Durable memory: for cross-cutting decisions or constraints (not

actionable tasks), is the rationale stored in long-term memory?

Risks register: if the item is a risk or open question, is it in a

risks doc with owner and status?

Flag orphaned deferrals

If ANY deferred item has no persistent home, report it as [IMPORTANT]:
"Deferred item '<title>' has no tracker issue / backlog entry / memory.
It will be lost after this session ends."

Suggest the appropriate persistence mechanism based on the item's nature:

Actionable task → GitHub issue with label + priority
Decision / constraint → a durable memory store (type: decision or constraint)
Risk / open question → risks register or a memory store (type: issue)
Reference info → doc file or a memory store (type: reference)

---

Phase 4: Consolidate & Report

Read the agent's findings (Phase 2).
Cross-reference with Phase 1 + Phase 3 findings — deduplicate.
For each unique finding:

CRITICAL / IMPORTANT → fix in the plan file immediately
MINOR → fix if quick, otherwise note for the user
NITPICK → mention, don't block

Report a summary to the user:

``Plan Review Summary ------------------- Phase 1 (self): N findings (X critical, Y important) Phase 2 (agent): M findings (X critical, Y important) Phase 3 (deferred): K orphaned items After dedup: Z unique issues Delegation: D findings (X critical, Y important) [subset, tagged] Fixed: F (all critical + important) Noted: R (minor + nitpick, listed below)``

Then list every deferred item and where it now lives — the well-homed ones
too, not just orphans — so the user sees the full disposition at a glance:

``Deferred items -------------- <item> → GitHub #<n> (homed) <item> → session file <name> (homed) <item> → a memory store "<concept>" (homed) <item> → (no home) (orphan — flagged [IMPORTANT] above)``

If the plan defers nothing, write "Deferred items: none."

Log this invocation's metrics for harness-wide statistics.

After emitting the summary, run this single Bash command. Substitute
literal values for 6 placeholders from step 4's counts. The plan
file's basename comes from the plan-mode system message's "Plan File
Info" block — strip the .md extension.

This command is a single bash pipeline using the idiomatic FD-based
flock pattern. It creates the JSONL and directories if missing,
acquires an exclusive lock, appends one JSON row, then runs the
aggregator. Wrapped so logging failure NEVER blocks the user's review
flow (missing flock silently disables logging, etc.):

``( command -v flock >/dev/null || exit 0 command -v sha256sum >/dev/null || exit 0 mkdir -p ~/.claude/stats ~/.claude/scripts ~/.claude/feedback && touch ~/.claude/stats/plan-review-log.jsonl && PLAN_HASH=$(printf '%s' "<plan-basename>" | sha256sum | cut -c1-8) && [ -n "$PLAN_HASH" ] && TS=$(date -u +%Y-%m-%dT%H:%M:%SZ) && JSON=$(printf '{"ts":"%s","plan_hash":"%s","phase1":%s,"phase2":%s,"dedup":%s,"fixed":%s,"orphans":%s}' \ "$TS" "$PLAN_HASH" "<P1>" "<P2>" "<Z>" "<F>" "<K>") && ( flock -x 200 && printf '%s\n' "$JSON" >> ~/.claude/stats/plan-review-log.jsonl && bash ~/.claude/scripts/regen_plan_review_stats.sh ) 200>>~/.claude/stats/plan-review-log.jsonl ) || true``

Worked example — if Phase 1=4, Phase 2=12, dedup=14, fixed=7, orphans=0
and the plan was delightful-wiggling-lobster, substitute:
<plan-basename> → delightful-wiggling-lobster,
<P1> → 4, <P2> → 12, <Z> → 14, <F> → 7, <K> → 0.

The log lives at ~/.claude/stats/plan-review-log.jsonl. Aggregated
statistics are auto-written to the STATS_BLOCK region in
~/.claude/feedback/anthropic_plan_review_skill.md. Both files are
local only — never sent anywhere. (regen_plan_review_stats.sh is
optional — the wrapper skips logging cleanly if it isn't present.)

Do NOT call ExitPlanMode — return control to the user who decides whether

to approve, request another round, or revise.

---

When NOT to use

No plan file exists (not in plan mode, or plan not yet written).
Plan is a trivial single change where review adds no value.
User explicitly said "skip review" or "just execute".

~~~~
</details>

View original on GitHub ↗