Iterative Plan Review

Project Context

• CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
• project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f

Review Approach

• Read the full plan before challenging — an assumption that looks wrong in isolation may make sense in context.
• Ground challenges in codebase evidence: "The API handler at src/api/handler.go:47 returns XML, not JSON" is actionable; "This assumes the API returns JSON" is not.
• Check overlap against existing code, not just the plan — the most valuable overlap findings are external utilities or patterns the codebase already has.
• Ask practical ambiguity questions — "Should this handle concurrent access?" is only useful if there's evidence concurrent access actually happens.
• YAGNI is a first-class review pillar. Apply the evidence-based YAGNI rule from [../../references/yagni-rule.md](../../references/yagni-rule.md) to every plan item the review touches — every behavior, plan step, abstraction, configuration knob, runbook, observability hook, infrastructure component, test category, ADR clause, or coding-standard line. Items that fail the evidence test or have a strictly simpler version available are first-class findings (Category: YAGNI candidate), not polish. Resolution paths: cite missing evidence and keep, replace with simpler version, or move to the plan's ## Deferred (YAGNI) section with the reopening trigger named. YAGNI candidates are surfaced visibly to the user — never silently dropped, never silently kept. Every plan item is ongoing maintenance and a pattern future agents will copy.
• Evidence quality is a first-class review pillar. Apply the companion evidence rule from [../../references/evidence-rule.md](../../references/evidence-rule.md) alongside the YAGNI gate. YAGNI asks whether a plan item has any evidence at all; the evidence rule asks how strong that evidence is. Specifically: name the trust class of each citation a plan item rests on (codebase, web, provided); apply the corroboration gate to web-source claims that drive a recommendation (single-source web claims get marked and cannot stand alone); and label claims with no evidence at any tier as a distinct state rather than treating them as weak evidence. The proximity-to-origin principle is a heuristic, not a strict tier list; do not raise findings purely because a plan item cites docs instead of running code.
• The review lives in three cross-referenced files. The plan file is the primary artifact edited in place and stays at the root of {plan-dir}/; review-findings.md records every finding and how it was resolved, and review-iteration-history.md records each iteration or round — both companion artifacts live in {plan-dir}/artifacts/ to keep the plan folder uncluttered. The plan gets a standardized ## Review History section at the bottom pointing to the companion files. Inline (F#) markers are NOT added to plan sentences — forward traceability lives in the findings file's Changed in plan: field. (Inline ([T#](...)) markers in spec-aware mode remain — they tag load-bearing mechanic-driven spec sentences and are not finding markers.) The findings and iteration files (siblings inside artifacts/) cross-link through Raised in round: / Findings raised: fields and both record Changed in plan: sections. Any edit to one file requires updating the matching fields in the others.

Iterative Plan Review

Step 1: Locate the Plan and Set Up Companion Files

Find the plan file from the user's argument. If no path was provided, use Glob to find ~/.claude/plans/*.md — Glob returns files sorted by modification time, so the first result is the most recent plan. Read the full plan file and understand its structure, scope, and current state before proceeding.

Resolve project config: read CLAUDE.md's ## Project Discovery section for language, framework, docs, ADR, and coding-standards directories; fall back to project-discovery.md; fall back to Glob defaults (docs/, docs/adr/, docs/coding-standards/). This context informs assumption evaluation and overlap checks in later steps.

Spec-aware mode detection

After reading the plan file, determine whether it is a feature-specification.md produced by (or compatible with) han-planning:plan-a-feature. Engage spec-aware mode when either signal holds:

• Primary signal — the plan's filename is exactly feature-specification.md.
• Fallback signal — the file contains the canonical top-level headings of a feature spec: ## Outcome, ## Actors and Triggers, ## Primary Flow, and ## Coordinations (at least three of these four).

When spec-aware mode engages, state one line to the user:

> Detected feature specification; applying spec-stage rules to this review. Say "general mode" to override if this file is not a behavioral spec.

This confirmation lets the user correct a misclassification (e.g., the file was renamed, or is a document that happens to share headings but isn't a spec). If the user overrides, drop spec-aware mode for the rest of the session.

When spec-aware mode is engaged, detect whether {plan-dir}/artifacts/feature-technical-notes.md already exists. If it does NOT exist, the file is treated as absent for the duration of this review unless a load-bearing finding causes it to be created lazily. When the file is absent, omit every T#-related sentence from agent briefs, the spec-maturity tag set, and the round entry's Changed in tech-notes: field — do not add boilerplate qualifiers like "if it exists." When the file is present (or once it has been created lazily), restore the T# instructions for the agents from that point forward.

When spec-aware mode is engaged, the following apply across later steps:

• Content rule — the spec must obey plan-a-feature's operating-principles rule: no language primitives, file/line references, function/class names, library mechanics, implementation patterns, or internal flag names in behavioral sentences. Any finding that surfaces a mechanic in the spec is routed per the rule.
• Mechanic routing — a finding that requires a mechanic to explain a behavior is classified as:
• Load-bearing (affects observable behavior) → extract the mechanic to a new T# entry in {plan-dir}/artifacts/feature-technical-notes.md (creating the file lazily if this is the first qualifying note). Restate the spec sentence behaviorally and add an inline ([T#](artifacts/feature-technical-notes.md#...)) link. Record the write in the F# entry's Changed in tech-notes: field.
• Discoverable from code repo → restate the spec sentence behaviorally and cite the evidence source on the related D# entry in {plan-dir}/artifacts/decision-log.md (if the spec has a decision log). Do not write a T#.
• Pure implementation → remove from the spec entirely. Record as an F# with Resolved by: deferred to open item, noting that the mechanic belongs to plan-implementation.
• "mechanics leaking into spec" finding class — specialists (and self-review) tag any behavioral sentence that leaks implementation mechanics as Category: mechanics leaking into spec. Resolution of this class rewrites the offending sentence behaviorally and, when needed, extracts the mechanic per the routing above.

Determine the companion file paths. They live in the artifacts/ subfolder of the plan's directory (create the subfolder when the first companion file is written):

• {plan-dir}/artifacts/review-findings.md
• {plan-dir}/artifacts/review-iteration-history.md
• {plan-dir}/artifacts/feature-technical-notes.md — spec-aware mode only, and lazily created. Written only when the review produces at least one load-bearing T#. Follow the cross-reference invariants in [feature-technical-notes-template.md](../plan-a-feature/references/feature-technical-notes-template.md) as applied by plan-a-feature.

For legacy reviews produced before the artifacts layout was introduced, the companion files may exist at {plan-dir}/review-findings.md and {plan-dir}/review-iteration-history.md. When those legacy paths are found, continue appending to them at their existing location rather than migrating — keep the cross-references stable and note the legacy path in the plan's Review History section.

If any companion file already exists (prior review of the same plan), read it and append new F# / R# / T# entries continuing from the highest existing ID — do not overwrite. Numbering must be globally unique across all review sessions of the same plan so cross-references remain stable.

If the companion files do not exist, defer creation until the first iteration or round actually produces content. Do not write empty stub files. When the first companion file is written, create the artifacts/ subfolder if it does not already exist.

Step 2: Choose Review Mode and Size

Default to small. Start the classification at small and only escalate to medium or large when the signals below clearly require it. When a signal is borderline, stay at the smaller band. Use these signals:

• Small (default) — 2–3 files affected, single system, no cross-cutting concerns. Defaults to lightweight mode (no team review). Iteration cap: 1 round.
• Medium — 3–5 files, one or two adjacent systems, may touch a single cross-cutting concern (e.g., one API contract or one new permission check). Defaults to team mode with a 3–4 agent team. Round cap: 2.
• Large — more than 5 files, multiple systems, architectural changes, security or data implications, or the user explicitly requests full agent review. Defaults to team mode with a 4–5 agent team. Round cap: 3.

The size determines:

| Size | Mode | Team cap | Round cap | |---|---|---|---| | Small | lightweight | n/a (self-review only) | 1 | | Medium | team | 3–4 | 2 | | Large | team | 4–5 | 3 |

Size override. If $size is non-empty (the user passed small, medium, or large as the first argument), use that value as the size and skip the signal-based classification above. State the chosen size and mode to the user in one line with the justification (e.g., "Medium: 4 files, one auth surface" or "Medium: passed via $size"). If the user asked for team review on a plan that would otherwise be small, honor the request and treat it as medium-or-larger. If the user explicitly names a size in conversation, accept the override.

In lightweight mode, skip Step 3 and run the checklist-based iteration loop in Step 4 alone. In team mode, proceed to Step 3 to assemble a team and Step 5 to run team iterations.

Step 3: Select the Team (team mode only)

Always include these two — they are the minimum roster and cannot be omitted:

• han-core:junior-developer — reframes the plan in plain terms and surfaces hidden assumptions, unstated prerequisites, and standards conflicts a generalist would notice.
• han-core:adversarial-validator — attacks the plan's evidence, proposed approach, and assumptions with counter-evidence, edge cases, and falsification attempts.

han-core:evidence-based-investigator is conditionally mandatory — include it whenever the plan contains codebase claims to verify, and exclude it otherwise. The plan contains codebase claims if any of the following is true:

• the plan body contains a file path matching common source extensions (e.g., .ts, .tsx, .js, .jsx, .svelte, .go, .rb, .py, .rs, .java, .kt, .swift, .cs, .php);
• the plan references src/, app/, lib/, internal/, pkg/, or another source directory by path;
• the plan contains a line-number reference like :NNN or lines NN–NN;
• the plan names a function, class, or method in backticks alongside a file path or directory.

Run a quick grep over the plan to detect these signals before finalizing the team. If any single match is found, include han-core:evidence-based-investigator. When in doubt, include it.

When han-core:evidence-based-investigator is not included, state to the user in one line: "han-core:evidence-based-investigator is not required because the plan has no codebase claims to verify." If the user explicitly names the agent, honor the request regardless of the heuristic.

Select additional specialists up to the size cap from Step 2 (medium: 3–4 total team, large: 4–5 total team) based on what the plan actually touches. Fewer is better — only add an agent if their absence would meaningfully weaken the review. Draw from:

• han-core:user-experience-designer — user-facing flows, UI, interaction models, accessibility.
• han-core:adversarial-security-analyst — authentication, authorization, PII, untrusted input, secrets, supply chain.
• han-core:devops-engineer — deployment, observability, rollout, feature flags, scale, SLO impact, cost.
• han-core:on-call-engineer — application-source resilience patterns named in the plan: timeouts, retry strategy, idempotency, backpressure, kill switches, observability of new code paths. Hard boundary against han-core:devops-engineer: defer infrastructure and pipeline concerns to it.
• han-core:structural-analyst — module boundaries, coupling, dependency direction, duplication.
• han-core:behavioral-analyst — runtime behavior, data flow, error propagation, state transitions.
• han-core:concurrency-analyst — concurrent access, race conditions, async coordination, ordering.
• han-core:software-architect — intra-codebase architectural fit, module/class/interface sketches, SOLID-grounded refactoring paths.
• han-core:system-architect — cross-service / bounded-context topology, context-map relationships, integration patterns, data ownership, failure-domain containment.
• han-core:risk-analyst — prioritization of architectural and delivery risks.
• han-core:test-engineer — observable-behavior test planning, test doubles.
• han-core:edge-case-explorer — boundary values, input messiness, state-dependent failures.
• han-core:data-engineer — schema changes, migrations, data movement, analytics implications.
• han-core:gap-analyzer — spec-vs-implementation gap checks when a source spec exists.
• han-core:content-auditor — documentation-preservation review when docs are being updated.
• han-core:codebase-explorer — feature discovery when the plan touches unfamiliar code regions.

Selection rules:

• Honor any agents the user named explicitly.
• Justify each additional specialist in one line — what in the plan requires them.
• han-core:risk-analyst, han-core:software-architect, and han-core:system-architect consume upstream findings; only include them when at least one of han-core:structural-analyst, han-core:behavioral-analyst, or han-core:concurrency-analyst is also on the team.
• If han-core:user-experience-designer, han-core:adversarial-security-analyst, or han-core:data-engineer is relevant, include them over nice-to-haves — the risks they surface rarely surface elsewhere.

Spec-aware mode roster rules (apply only when spec-aware mode was engaged in Step 1):

• Do NOT include han-core:structural-analyst, han-core:behavioral-analyst, han-core:concurrency-analyst, han-core:software-architect, han-core:system-architect, or han-core:data-engineer in the default roster. These specialists are named after mechanic-level analysis that belongs in plan-implementation, not in a behavioral spec review.
• If the user explicitly names one of the excluded specialists, honor the request — but issue a one-line warning that the specialist may surface implementation-level findings the spec will not absorb. Such findings get deferred to plan-implementation rather than edited into the spec.
• The required agents are han-core:junior-developer and han-core:adversarial-validator; han-core:evidence-based-investigator is conditionally mandatory by the codebase-claims heuristic above. All three are generalist

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: testdouble
• Source: testdouble/han
• License: MIT

Install and usage instructions live in the source repository linked above.