iterative-plan-review

Reviews and refines existing plan files through codebase-grounded iteration rounds with specialist agents.

Updated Sep 1, 2026
One-click install
npx skills add https://github.com/amirbiron/Han --skill iterative-plan-review-amirbiron
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: iterative-plan-review
Source: https://github.com/amirbiron/Han/tree/main/han-planning/skills/iterative-plan-review
Command: npx skills add https://github.com/amirbiron/Han --skill iterative-plan-review-amirbiron

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Plans often contain unverified assumptions, overlap with existing code, and unscoped scope creep. This Skill stress-tests an existing plan file against the actual codebase, editing it in place and recording every finding so the plan converges before implementation begins. ## Core Features & Use Cases - Codebase-grounded review rounds: Challenges plan assumptions with concrete file:line evidence, checks overlap against existing utilities, and applies YAGNI and evidence-quality gates to every plan item. - Two review modes: Lightweight self-review for small plans, or team mode that dispatches specialist agents (security, concurrency, UX, data, and more) with domain-scoped briefs for medium and large plans. - Cross-referenced audit trail: Records every finding in review-findings.md and every round in review-iteration-history.md under the plan's artifacts/ folder, with a validation script that verifies cross-reference integrity. - Spec-aware mode: Detects feature-specification.md files and enforces behavioral-level language, routing implementation mechanics into a technical-notes companion file. - Use Case: After drafting a feature plan, run this Skill to have adversarial and domain specialists refute weak assumptions, flag missing failure modes, and tighten the plan across up to three rounds before writing any code. ## Quick Start Ask the AI to iteratively review and tighten the plan at ~/.claude/plans/my-feature.md using a medium-sized specialist team.

Frequently Asked Questions about iterative-plan-review

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review and improve an existing implementation plan?▼

Invoke the iterative-plan-review skill with the path to your plan file. It reads the full plan, challenges assumptions against codebase evidence, edits the plan in place, and records every finding in companion files under the plan's artifacts folder.

What review modes does iterative plan review support?▼

It supports lightweight mode, a checklist-driven self-review for small plans capped at one iteration, and team mode, which launches specialist agents in parallel for medium plans (two rounds) and large plans (three rounds).

Can I control the review size or team composition?▼

Yes. Pass small, medium, large, or dynamic as the size argument, or set default-swarm-size in the project .han/config.md. You can also name specific specialist agents, and explicit user choices override the automatic selection.

Does iterative-plan-review write new plans or implement code?▼

No. It only refines existing plans and never generates plans from scratch, writes test plans, reviews code, or implements plan steps. Use plan-a-feature for new plans and plan-implementation for building.

Where are review findings and iteration history stored?▼

Findings go in review-findings.md and round history in review-iteration-history.md, both inside the plan folder's artifacts subfolder. A check-cross-references.sh script verifies that every finding and round entry cross-reference resolves correctly.