iterative-plan-review

Name: iterative-plan-review
Author: testdouble

122stars12forks

How to install iterative-plan-review?

testdouble/han/iterative-plan-review

$npx -y skills add testdouble/han --skill iterative-plan-review

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	## Project Context
2
3	- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
4	- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
5
6	## Review Approach
7
8	- Read the full plan before challenging — an assumption that looks wrong in isolation may make sense in context.
9	- 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.
10	- Check overlap against existing code, not just the plan — the most valuable overlap findings are external utilities or patterns the codebase already has.
11	- Ask practical ambiguity questions — "Should this handle concurrent access?" is only useful if there's evidence concurrent access actually happens.
12	- 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.
13	- 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.
14	- 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.
15
16	# Iterative Plan Review
17
18	## Step 1: Locate the Plan and Set Up Companion Files
19
20	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.
21
22	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.
23
24	### Spec-aware mode detection
25
26	After reading the plan file, determine whether it

People who liked this also viewed

6 picks

Type

iterative-plan-review

122stars12forks

View on GitHub

How to install iterative-plan-review?

testdouble/han/iterative-plan-review

$npx -y skills add testdouble/han --skill iterative-plan-review

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## Project Context
2
3	- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
4	- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
5
6	## Review Approach
7
8	- Read the full plan before challenging — an assumption that looks wrong in isolation may make sense in context.
9	- 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.
10	- Check overlap against existing code, not just the plan — the most valuable overlap findings are external utilities or patterns the codebase already has.
11	- Ask practical ambiguity questions — "Should this handle concurrent access?" is only useful if there's evidence concurrent access actually happens.
12	- 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.
13	- 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.
14	- 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.
15
16	# Iterative Plan Review
17
18	## Step 1: Locate the Plan and Set Up Companion Files
19
20	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.
21
22	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.
23
24	### Spec-aware mode detection
25
26	After reading the plan file, determine whether it

People who liked this also viewed

6 picks

Type