iterative-plan-review
Sharpens and stress-tests an existing plan file through multiple codebase-grounded review passes, editing it in place and recording every finding and iteration in cross-referenced companion files. Use this skill whenever the user wants to iterate on, refine, tighten, or improve a plan. Also use it when the user asks to verify, validate, or confirm feasibility of an approach. Does not implement plan steps, write test plans, review code, or investigate bugs, and does not generate new plans from scratch — use plan-a-feature for a new plan.
npx skills add testdouble/han --skill iterative-plan-review --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
The skill sharpens and stress-tests an existing plan file through multiple codebase-grounded review passes, editing it in place and recording every finding and iteration in cross-referenced companion files. It is invoked when the user wants to iterate on, refine, tighten, or improve a plan, or when asked to verify, validate, or confirm feasibility of an approach. It does not implement plan steps, write test plans, review code, or investigate bugs, and it does not generate new plans from scratch — use plan-a-feature for a new plan.
How it works
As the first action, it uses the Read tool on .han/config.md in the personal configuration directory, then applies project configuration rules if content is present. It locates the target plan file based on the user’s argument or by Globbing ~/.claude/plans/*.md (most recent by modification time). It reads the full plan and understands structure, scope, and current state. It determines whether spec-aware mode should engage by checking the plan filename against feature-specification.md or by the presence of top-level spec headings. If spec-aware mode engages, it may create or reference companion files under {plan-dir}/artifacts, including review-findings.md, review-iteration-history.md, and feature-technical-notes.md as needed. It then selects a review mode and size (default small unless signals push scope higher) and proceeds with iterations following the checklist in Step 4, editing the plan with Edit as changes are found. It bases findings on codebase evidence, avoids introducing implementation details in the spec, and keeps cross-references in companion artifacts.
When to use it
Use this skill whenever you want to iterate on, refine, tighten, or improve an existing plan, or when asked to verify, validate, or confirm the feasibility of an approach. It explicitly does not generate new plans from scratch. If a user requests a new plan, use plan-a-feature instead.
What it can touch
It operates with the following tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *). It will read configuration, locate and read the plan, and edit the plan in place as findings are recorded in companion artifacts under {plan-dir}/artifacts/ (review-findings.md and review-iteration-history.md), creating those files only when needed.
Caveats
License: MIT. Spec-aware mode creates and references companion files in artifacts/ and adheres to the cross-reference rules described in the review approach. It avoids generating new plans from scratch and relies on existing plan structure and evidence in the codebase for findings.
## 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: !`echo "${CLAUDE_CONFIG_DIR:-$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](../../references/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
- Project Context
- Review Approach
- Step 1: Locate the Plan and Set Up Companion Files
- Spec-aware mode detection
- Step 2: Choose Review Mode and Size
- Step 3: Select the Team (team mode only)
- Step 4: Lightweight Iteration Loop (lightweight mode only)
- Step 5: Team Iteration Rounds (team mode only)
- Step 6: Update the Plan's Review History Section
- Step 6.5: Readability Self-Check
- Step 7: User Review
What does the iterative-plan-review skill do?
Sharpens and stress-tests an existing plan file through multiple codebase-grounded review passes, editing it in place and recording every finding and iteration in cross-referenced companion files. Use this skill whenever the user wants to iterate on, refine, tighten, or improve a plan. Also use it when the user asks to verify, validate, or confirm feasibility of an approach. Does not implement plan steps, write test plans, review code, or investigate bugs, and does not generate new plans from scratch — use plan-a-feature for a new plan.
How do I install it?
Run `npx skills add testdouble/han --skill iterative-plan-review --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From testdouble/han, a repository with 154 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.