plan-iteration-gate v1.2.0A

Immutable. This exact content never changes and is served at /api/v1/blob/4ca5cc78f2b64458.

---
name: plan-iteration-gate
description: "Use when refining a draft plan, stuck iterating, or deciding whether to escalate to a human. Converges via 4Q loop."
version: 1.2.0
author: code-hygiene contributors
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [stuck, plan, convergence, escalation]
    related_skills: [socratic-spec, project-discovery, self-review-gate]
---

# Plan Iteration Gate

Convergent phase: from approved spec → plan.md with steps, each observable. Runs 4 questions per iteration — per latest fix (b) is "better way", not just "better split".

## Trigger

Complex tasks: ≥3 steps, ambiguous, irreversible, externally visible, high-stakes, or >2 iterations expected. Skip for trivial one-liner.

## Loop — 4 questions per iteration

For each iteration ask in order (a)..(d). Patch plan, re-ask all. Loop till clean sweep (no finding across all 4).

### (a) What's wrong with this plan?

Failure modes: tight loops, unbounded state/handled queue growth, stale handles, injected input, blind suppression (try/except pass), missing fallback, per-item cost unbounded, ambiguous ownership, irreversible without guard, no verification signal, existing workload breakage not checked.

Unstated premises are failure modes too: list what the plan assumes is true — a physical or geometric relation, an API's behaviour, a device's support, a file's format, a measurement's meaning — and verify each against source or a probe before building on it. One false premise invalidates every step that depends on it, so it is the cheapest thing on the list to check first, and it is the failure that survives the longest because everything above it looks internally consistent.

Automation belongs here as well: a plan that enables anything state-mutating ships it in propose/dry-run mode first, so the first run observes the target rather than acting on it, and the human sees the diff before it is applied.

### (b) Is there a materially better way?

Not just split — arch, tradeoff, reuse, ordering, cost.

Check:
- Simpler arch (fewer moving parts, existing generic mechanism in repo or dependency already does it).
- Cheaper/stronger tradeoff (batch vs per-item, push vs poll, memoize vs recompute, cache vs refetch).
- Steps parallelizable vs must serialize — does ordering buy earlier signal?
- Existing upstream tooling / library already provides it — avoid building.
- Different representation (data structure, API shape, file format) removes a seam that forced a split.
- DRY violation creating two implementations — one generic suffices?
- Premature generalization vs duplication threshold.
- If answer is genuinely "no better way beats chosen tradeoff", state explicitly why none beats — with tradeoff (correctness/simplicity/cost/robustness), not just assertion.

Critique given approach — don't redesign goal. An alternative solving different problem is scope creep, not better. Skip only for trivial one-liner.

### (c) Is something missing from this plan?

Most common plan failures are absence, not presence.

Checklist:

- Rollback / cleanup / undo for each irreversible step
- Ownership transfer spelled out (who owns resource after hand-off)
- Non-interference verification (existing workload still correct — which test/build/log proves)
- Boundary / capacity: empty, full, concurrent, re-entrant, boundary ±1
- Observability per step: log line, metric, health endpoint, artifact exists — so correctness (right thing/right params/right place) and non-interference checkable
- Failure notification: how human knows step failed (exit code, health, alert)
- Who owns decision when ambiguous during execution (human trigger owner)
- What unblocks downstream (tag / contract / API / file existence)
- What stays out of scope and why (Non-goals carry-over)

If missing is required for plan to be safe/verifiable, it's finding — not "nice to have".

### (d) Are prerequisites and boundaries explicit?

- Upstream CONTRIBUTING / CLAUDE / AGENTS found? Which file, which section?
- External dependency version pinned? Which artifact / control?
- Irreversible step guarded (backup, feature flag, canary, confirmation gate)?
- Existing tests/build listed as non-interference signal (cmd + expected)?
- Scope limits written (what this plan does NOT do and why — positive framing: say what *is* in scope clearly, link non-goals to separate doc if long)?

### Converged criteria

Converged = one full iteration with no new finding across (a)..(d). Iterating on plan cheap; iterating on implementation wastes cycles.

Watch trend, not count. Findings shrinking each round → converging regardless of iteration count. Recurring same scale/structural → wrong altitude, rescope/restart instead of grinding.

## Plan format

```markdown
# <slug> plan

Goal: one sentence — what it IS and provides (positive, checkable), not what it isn't.
Non-goals: out of scope + why (link to spec or provenance doc, don't define main goal by negation)
Deps discovered: CONTRIBUTING.md X, recent log Y, pinned version Z
Steps:
- [ ] 1. <step> — owner, inputs/outputs, observable (cmd/log/metric/artifact), non-interference check, rollback
- [ ] 2. ...
Risks + mitigations
Rollback: strategy per irreversible step
Verification: end-to-end cmd + expected
Ownership: who decides when ambiguous
Open Qs (should be 0 if socratic done, else triggers)
```

**Positive framing in goals:** Say what it provides (capability, checkable outcome) not list of excluded origins. Bad: "kernel-free, not X". Good: "installable skills + install script that probe ~/.claude/, ~/.hermes/, AGENTS.md with confirmation gate; factual-integrity, comment WHY, changelog one idea/para". Exclusion history / "started from X but ..." belongs in CONTRIBUTING provenance or references doc.

## Human escalation — when to ask

Ask only on 4 triggers + one implicit from (c)/(d) (keeps role disjoint from socratic which is pre-plan divergent):

1. Spec ambiguity not resolvable from written spec+discovery blocks step ordering.
2. Competing constraint tradeoff needs relaxation — e.g. "minimal fix" vs "extract helpers now", "perf target needs bigger change than allowed".
3. Irreversible / externally visible / high-stakes step would execute next and plan still has >1 viable path.
4. No convergence after 2 iters same finding same scale → need scope change signal.
5. Implicit from (c)/(d): missing boundary that only human can settle (e.g. rollback downtime acceptable? canary %?) — convert to (1) or (2) with options.

How to ask:

- 1 sentence context why blocked.
- 2-4 concrete options with tradeoff (correctness/simplicity/cost).
- Your recommendation + what will happen.
- What is blocked until answer.

## Boundary vs socratic-spec

- socratic-spec: divergent pre-plan, output spec.md, closes blocking Qs.
- plan-iteration-gate (this skill): convergent post-spec, output plan.md. Re-opens human Q only when can't proceed without tie-breaker. Document boundary in both so user sees.
- Also self-review-gate Gate2 repeats same 4 questions — this skill is standalone when you want loop definition without Gate1 self-review; keep in sync (b) wording must match: "materially better way", not "better split".

## Related

- socratic-spec for pre-plan.
- self-review-gate Gate1 for per-ship self-review, Gate2 same (a)..(d) — keep (b) wording in sync.
- project-discovery Stage 0 for upstream rules bounding plan.
- factual-integrity for how to source evidence claim in plan.
- generic-principles "Positive framing" section for how to phrase Goal.