plan-deliberator

name

plan-deliberator

description

Use when a drafted implementation plan spans territories no single agent can hold at once — the spec's intent, multiple subsystems of the real codebase, and the delivery pipeline — BEFORE plan-validator, to improve the plan by deliberation rather than attack. Dispatches delegate agents each assigned a different territory to deep-read and speak for, who deliberate over bounded rounds until they converge on a single jointly revised plan, negotiating the trade-offs (migration strategy, group boundaries, scope) that a validator can only flag, never decide. Symptoms - "deliberate on this plan", "improve this plan from multiple perspectives", "the plan touches three subsystems", "we need to pick a migration strategy", plan.md spans code no one context window can deep-read whole, resolving the unconfirmed tail of a plan-validator run.

Deliberative Plan Improvement

Overview

Dispatch a small panel of delegate agents — each assigned a different territory of the work (the spec's intent, a partition of the real codebase, the delivery pipeline) to deep-read and speak for — who deliberate through orchestrator-relayed dialogue until they converge on one jointly revised plan. The pattern instantiates deliberative collaboration: a cooperative joint decision under partial, asymmetric observability, where dialogue transports what each delegate learned in its territory (arXiv:2607.06157).

This is the generative counterpart to plan-validator. The validator's skeptics take the plan as fixed and race to predict where it fails; deliberator delegates reshape it — reorder, regroup, retarget, and above all decide trade-offs the plan left open or got wrong. A validator can flag "step 4 has no rollback"; only a deliberation can weigh an online backfill against an offline migration and commit the plan to one, with each territory's constraints on the record.

Announce at start: "I'm using the plan-deliberator skill to improve this plan through a multi-territory delegate panel."

When to Use

• A written plan exists (e.g. from architect) and it spans more code than one agent can deep-read alongside the spec and the delivery constraints — the very condition that makes single-author plans rot.
• The plan contains an open or contestable trade-off: migration strategy, execution group boundaries, build-vs-reuse, sequencing under a deploy window, test depth vs. schedule.
• A plan-validator run left unconfirmed 1-vote findings that need adjudication, not another vote (see Relationship to plan-validator).

When NOT to Use

• The plan touches one small subsystem and everything fits one prompt. Revise centrally — a single agent with merged context empirically beats a deliberating panel whenever merging is possible. Deliberation earns its cost only when the territories are too large to hold together.
• You want failure prediction on a plan you believe is finished — use plan-validator.
• No plan exists yet — run architect first; deliberation improves a draft, it does not replace planning.
• The artifact is a spec (use spec-deliberator) or code (use implementation-validator).

Core Principle

Four things make deliberation productive instead of theater. All four are required:

1. Engineered territory asymmetry — at plan stage everything is technically readable by everyone, so asymmetry is created by assigned investigation: each delegate deep-reads only its territory and becomes the panel's sole authority on it. Apply the asymmetry test before dispatching: for each delegate, name one question about this plan that only its territory can answer (a real signature, an acceptance criterion, a CI constraint). If you cannot, merge the territories and revise centrally instead.
2. Shared artifact, forced convergence — delegates accept or amend a single versioned plan proposal until all accept the same version. The output is one revised plan.md, not three reviews.
3. Bounded, verbatim-relayed dialogue — the orchestrator relays the transcript verbatim, never paraphrased (a paraphrased signature or step number is exactly the information-loss deliberation exists to overcome). Hard cap: 4 rounds.
4. Evidence-grounded turns, earned acceptance — every objection and every disclosure cites its territory: file:line for code, a quoted clause for the spec, a named config/command for the pipeline. An acceptance without a stated basis (what the delegate verified in its territory, or what argument changed its mind) is invalid — the guard against sycophantic round-1 consensus, and what preserves deliberation's empirical edge: reflection, a partner's challenge catching what the author would have kept.

Panel Composition (territories)

Default panel is 3 delegates (4 max — each extra delegate adds a full turn to every round). Partition by territory so each has real authority:

Delegate	Territory (deep-reads this, speaks for it)	Guards
Intent	spec.md, acceptance criteria, 00-ROADMAP.md, context report	Every acceptance criterion maps to a task; no silent scope cuts; no gold-plating the spec never asked for
Codebase	The files/subsystems the plan touches — open them, trace callers, read the tests	Real signatures and shapes, hidden coupling, seams for TDD, whether execution groups truly touch disjoint files
Delivery	Build/CI config, test harness, migration tooling, deploy/rollback runbooks	Every verify-step names a runnable command; migration ordering and reversibility; group parallelism is safe in CI, not just on paper

For a plan spanning multiple subsystems, split Codebase into two territory delegates (e.g. codebase-api, codebase-worker) rather than adding new role types. The roles matter less than the partition: disjoint territories, jointly covering everything the plan depends on.

Process

1. Gather and partition

• Collect the plan text, the spec it implements, and the repository root.
• List every territory the plan depends on and partition it across 2–4 delegates. Overlap is tolerable; identical assignments are not.
• Run the asymmetry test (Core Principle 1). If it fails, revise centrally and say so to the user.

2. Author delegate prompts

Fill the Delegate Prompt Template below once per delegate, varying the territory, the investigation instructions, and the guard list. The "cite your territory", "acceptance requires a basis", and "final message MUST be JSON" clauses are load-bearing — keep them verbatim.

3. Dispatch round 1 (investigate, then sequential turns)

Turns are sequential, not parallel — delegate 2 must see delegate 1's utterance, or proposals oscillate instead of converging.

• Spawn delegate 1 via the Agent tool with subagent_type: "general-purpose" (it must read and grep the codebase). Its first turn includes an investigation phase: deep-read the territory before speaking. Parse its JSON turn.
• Spawn delegate 2 with its own prompt plus the transcript so far (verbatim), then delegate 3.
• Track current_proposal as a versioned plan edit list (v1, v2, …): reorders, group boundary changes, inserted/removed/retargeted steps. Apply each turn's amendments to produce the next version; record which version each delegate accepted.

4. Run subsequent rounds via SendMessage

For rounds 2+, continue the same agents with SendMessage — never respawn. A respawned delegate loses everything it read in its territory and why it objected; continuation is what makes its authority real across rounds. Each message carries only the new transcript entries since that delegate's last turn, verbatim, plus the current proposal version. A delegate may investigate further mid-deliberation ("let me check whether schedule() tolerates a null") — that is the pattern working, not a stall.

5. Terminate

• Convergence: every delegate has accepted the same proposal version → done.
• Round cap (4) reached: the orchestrator arbitrates — adopt the majority position per disputed edit and record every unresolved dispute. Never silently overrule a delegate citing a hard constraint (file:line that contradicts a step, a failing CI requirement, an acceptance criterion); escalate those to the user.
• Prose instead of JSON: re-send the turn request; never hand-interpret a stance.

6. Apply and persist

• Apply the converged edit list to produce the revised plans/active_milestones/{moniker}/plan.md. Preserve the plan's structure (parallel execution groups, per-task test steps) — deliberation edits the plan, it does not reformat it.
• Write the deliberation record to plans/active_milestones/{moniker}/deliberations/plan-deliberation.md (create the folder if needed; bare plan with no milestone → plans/deliberations/plan-deliberation.md and say so). Always write it, even if the panel converged on "no changes" — who investigated what, which trade-off was decided on which evidence, is the audit trail. Re-runs append -r2, -r3, … Fill the Deliberation Record template verbatim.

7. Hand off to validation

Deliberation is generative, not evaluative — the delegates were reshaping, and a panel that just negotiated a trade-off is invested in it. Run plan-validator on the revised plan before execution. Consensus is not adversarial survival.

Delegate Prompt Template

Dispatch once per delegate via the Agent tool. Replace {ROLE}, {TERRITORY}, {GUARDS}, {PLAN}, {SPEC_PATH}, {REPO_ROOT}, {TRANSCRIPT}, {CURRENT_PROPOSAL}.

You are the {ROLE} delegate on a plan deliberation panel. The panel's shared goal is ONE
revised implementation plan every delegate can accept. You share the reward: a plan that
fails in execution fails for all of you, whichever delegate's territory hid the cause.

YOUR TERRITORY (deep-read this BEFORE your first utterance; you are the panel's only
authority on it — no other delegate will read it):
{TERRITORY}

YOUR GUARDS: {GUARDS}

PLAN UNDER DELIBERATION:
{PLAN}

SPEC IT IMPLEMENTS: {SPEC_PATH}
REPOSITORY ROOT: {REPO_ROOT}

TRANSCRIPT SO FAR (verbatim, may be empty in round 1):
{TRANSCRIPT}

CURRENT PROPOSAL: version {v}, edits: {CURRENT_PROPOSAL}

Rules of deliberation:
- Investigate first, speak second. Every claim about your territory cites evidence:
  file:line for code, a quoted clause for the spec, a named command/config for the
  pipeline. An uncited claim is a guess and wastes the panel's round budget.
- Surface every territory fact that should change the plan — an undisclosed constraint
  is a defect you caused.
- Challenge proposals that contradict your territory; concede points outside it.
- When the plan leaves a trade-off open (migration strategy, group boundaries,
  build-vs-reuse), state your territory's position AND its cost, so the panel can
  decide with all constraints on the record.
- Do not concede to end the conversation. Accept ONLY if the proposal is consistent
  with everything you verified, and state your acceptance basis: what you checked, or
  what argument changed your mind.
- Propose amendments as concrete plan edits (reorder, insert step, retarget name,
  split/merge group), not sentiments.

Your final message MUST be exactly one fenced JSON block and nothing else, matching:

```json
{
  "utterance": "what you say to the panel this turn — arguments, disclosures, reactions",
  "disclosures": [
    { "fact": "territory fact introduced into the record", "evidence": "file:line | spec clause | command/config" }
  ],
  "amendments": [
    {
      "target": "step number / group / section of the plan",
      "edit": "the concrete change: reorder, insert, remove, retarget, regroup",
      "reason": "the cited territory fact or transcript argument motivating it"
    }
  ],
  "stance": "accept|amend|object",
  "acceptance_basis": "REQUIRED when stance is accept: what you verified in your territory, or what changed your mind. Empty otherwise."
}

## Output Contract

Each turn returns the JSON above. The orchestrator (you) maintains:

```json
{
  "proposal_versions": [ { "version": 2, "edits": ["..."], "produced_by": "codebase, round 1" } ],
  "acceptances": { "intent": 2, "codebase": 2, "delivery": 1 },
  "tradeoffs_decided": [ { "topic": "backfill strategy", "chosen": "online default + lazy backfill", "over": "offline migration", "because": "delivery: no maintenance window before release; codebase: schedule() tolerates default 0 (scheduler/JobScheduler.java:88)" } ],
  "disputes": [ { "topic": "...", "positions": {"intent": "...", "delivery": "..."}, "resolution": "converged v2 | escalated" } ]
}

Convergence = all delegates' accepted version equals the latest version.

The Deliberation Record

Written in step 6 to plans/active_milestones/{moniker}/deliberations/plan-deliberation.md. A reader should understand what changed in the plan and which territory's evidence forced it without opening any transcript. Use date +%Y-%m-%d for the date. Keep every section, even when empty (write _None._).

# Plan Deliberation — {plan title}

> `plan-deliberator` · {N} delegates with disjoint territories · evidence-grounded turns · verbatim relay · {R} rounds to convergence

| Field | Value |
|---|---|
| Milestone | `{moniker}` |
| Artifact | `plans/active_milestones/{moniker}/plan.md` |
| Date | {YYYY-MM-DD} |
| Panel | {intent · codebase · delivery} |
| Outcome | **{converged on v{n} · arbitrated · escalated}** — {K} edits applied, {T} trade-offs decided |

## Verdict

{1–3 sentences: what materially changed in the plan and which territory's evidence drove
the biggest change or decided the central trade-off.}

## Panel & Territories

| Delegate | Territory (what it deep-read) | Key disclosure (with evidence) |
|---|---|---|
| codebase | {files/subsystems} | {the fact that mattered} — `{file:line}` |

## Trade-offs Decided

### {topic}
- **Chosen:** {option} — **over** {rejected option}
- **Because:** {each territory's constraint, cited}
- **Accepted by:** all, round {r}

## Edits Applied (converged proposal v{n})

### {target: step/group} — {one-line description}
- **Before:** "{original step/ordering, or `<ABSENT>`}"
- **After:** "{revised}"
- **Driven by:** {delegate} — {cited territory fact}
- **Accepted by:** all, round {r} _(bases: {one clause per delegate})_

_(repeat per edit)_

## Disputes

| Topic | Positions | Resolution |
|---|---|---|
| {topic} | intent: {…} / delivery: {…} | {converged v{n} · arbitrated (majority) · 🛑 escalated to user} |

## Round Log

- **R1:** {one line per delegate: investigated X, disclosed Y, proposed/objected Z}
- **R2:** {…}

## Handoff

- [ ] Revised plan written to `plan.md` (structure preserved: groups, test-first steps)
- [ ] `plan-validator` run on the revision → `adversarial-reviews/plan-validation.md`
- [ ] Escalated disputes decided by user _(or: none)_

Relationship to plan-validator

The two skills are inverses; use them in sequence, not as alternatives.

	plan-deliberator	plan-validator
Mode	Generative — reshape the plan, decide trade-offs	Evaluative — predict where the fixed plan fails
Information	Partial by assignment — each delegate deep-reads one territory	Complete — every skeptic may read anything
Interaction	Multi-turn, sequential, verbatim relay	One-shot, parallel, independent
Convergence	Consensus on one versioned proposal	2-of-3 majority vote on findings
Error control	Reflection — a partner's cited challenge	Statistics — uncorrelated votes + file:line evidence
Can it decide "online backfill vs offline migration"?	Yes — that is its job	No — it can only flag the absence of a decision

Pipeline: architect (draft plan) → plan-deliberator (reshape with territory evidence, decide trade-offs) → plan-validator (attack) → fold fixes → 🛑 human gate → execute.

The hybrid round: after a plan-validator run, its unconfirmed 1-vote findings are where independent judgment ran out. Convene a mini-panel (2 delegates, 2 rounds max) over only those findings — one delegate briefed to defend the plan's approach, one assigned the territory the finding concerns, both citing evidence. Record it as deliberations/plan-deliberation-tail.md.

Worked Example

Plan excerpt (from architect): "Step 2: add retryCount to the Job record. Step 3: update JobScheduler.dispatch() to read retryCount. Step 4: migrate existing rows. Groups: {2,3} parallel with {4}."

Territories: intent deep-reads the spec (acceptance criterion: "failed jobs retry ≤ 3 times; retries visible in the ops dashboard"), codebase deep-reads scheduler/ and dashboard/, delivery reads CI config and migration tooling.

• R1 — codebase discloses: no dispatch() exists — the method is schedule(Job) (scheduler/JobScheduler.java:88); also legacy rows have no retryCount, and schedule() NPEs on null fields (:104). Amends: retarget step 3; the plan needs a default before step 3 (v1).
• R1 — intent objects to the plan's scope, citing the criterion: retries must be visible in the dashboard — no step touches dashboard/. Amends: add step 5, dashboard column + test (v2).
• R1 — delivery discloses: there is no maintenance window before the release (deploy/RELEASES.md), so an offline migration in step 4 cannot run; states the trade-off: offline migration (simpler, needs window) vs. online default + lazy backfill (no window, more code). Proposes online: step 2b "default retryCount to 0", step 4 becomes lazy backfill, groups reordered — {2, 2b} → {3, 5} ∥ {4} (v3).
• R2 — codebase accepts v3 (basis: verified schedule() handles default 0, :104); intent accepts v3 (basis: criterion now maps to steps 3+5); delivery accepts its own v3. Converged, v3, 2 rounds. Trade-off decided: online backfill, because no-window + null-intolerant scheduler.

Compare plan-validator's worked example on the same plan: it finds dispatch-signature-missing and migrate-before-default — but it cannot add the missing dashboard step (that requires the spec's intent) and cannot choose the backfill strategy (that requires weighing delivery constraints against code shape). The deliberation did both, and the revised plan then faces the validator anyway.

Red Flags

Thought	Reality
"I'll let every delegate read the whole repo so they're all informed."	Then no one is the authority on anything and you have three shallow generalists — a single merged-context agent beats that. Assign territories.
"They all accepted in round 1, great."	Round-1 unanimity with thin acceptance_basis is sycophancy. Re-prompt: acceptance requires cited verification or a changed mind.
"A delegate asserted dispatch() doesn't exist but cited nothing."	Uncited territory claims are guesses. Send it back for file:line before the panel reacts to it.
"I'll summarize the transcript between turns."	Verbatim relay is load-bearing — a paraphrased signature or step number corrupts exactly what deliberation transports.
"They can keep talking until they agree."	Cap at 4 rounds; arbitrate, escalate hard-evidence disputes to the user.
"I'll respawn fresh agents each round with the transcript."	A respawn forgets everything it read in its territory. Continue the same agents with SendMessage.
"The panel agreed, so skip plan-validator."	The panel is invested in the trade-off it just negotiated. Consensus is not adversarial survival — run the validator.
"More delegates, more coverage."	Each delegate adds a turn to every round. Split territories across 3 (max 4); never add headcount without a disjoint territory to assign.

Calibration Note

Deliberation is the expensive path, and the evidence says so: with mergeable context, a centralized agent dominates (arXiv:2607.06157 — oracle-merged baselines beat deliberating panels by up to +34 normalized reward, and information demonstrably degrades in dialogue transit). What deliberation buys at plan stage is (a) depth per territory — three delegates can each actually read their subsystem where one agent skims all three, and (b) decided trade-offs with constraints on the record — the one thing a validator structurally cannot produce. Every rule above serves one of those: the asymmetry test and territory assignment protect (a); evidence-grounded turns, earned acceptance, and verbatim relay protect (b). When you relax a rule, check which one you just gave up — and remember the panel's consensus is a draft decision, not a verdict: the verdict belongs to plan-validator and the human gate.