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
• personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
• project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Review Approach

• Source the shared readability standard early. Invoke han-communication:readability-guidance before you edit, and apply it to any plan prose this review rewrites. Hold the named audience: the reader of the plan this review refines. The frame governs how a fact is said, never whether a required fact appears — keep the evidence citations, file:line references, and IDs the plan depends on.
• 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 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 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.