Structured Planning

You plan before you act: emit a subgoal checklist with stable ids (S1, S1.1), execute one step against ground truth, record observations, refine the remainder. On failure, hand off to dynamic-routing — do not blind-retry.

Hard Rules

Trivial tasks (single step, obvious outcome) → skip formal plan; state "trivial — plan skipped." Non-trivial tasks → write plan to .agent-loom/plans/<task-id>.md per references/PLAN-SCHEMA.md. Generate full plan once; execute only the first pending step per cycle (ReCAP commit-one). Every step records: goal, action, precondition, expected observation, status, evidence. Run scripts/plan_lint.py after each plan write. Append plan changes to Plan delta log with reason — never silent edits.

---

Workflow

Step 1 — Triage complexity

Signal	Route
Single tool call / one file / clear outcome	Skip plan — execute directly
Multi-step, failure-prone, or user asked to plan	Continue

Step 2 — Draft full plan

1. Assign task_id slug and stable step ids.
2. Fill all fields per PLAN-SCHEMA.
3. Write file; run plan_lint.py.

Step 3 — Execute one step

1. Mark step in-progress.
2. Run the action; capture actual observation in evidence:.
3. Mark done or failed.

Step 4 — Refine remainder

Before the next step: update preconditions/expected fields for pending steps using new evidence. Log deltas.

Step 5 — On failure

Invoke dynamic-routing with failed step id + evidence. Apply revised plan; lint again.

Step 6 — Complete

All steps done or explicit aborted. Emit final plan path.

---

Gotchas

• Executing the whole plan without observation updates recreates one-shot fragility.
• Reusing step ids after revision breaks trace cross-reference with run-trace.
• Plans in chat only — not auditable; always persist to .agent-loom/plans/.

---

Output Format

## Structured plan — [task_id]

Plan file: `.agent-loom/plans/[task_id].md`
Steps: N total | done: N | pending: N | failed: N

Current step: **Sx** — [goal]
Observation: [actual vs expected]

Delta (if any): [step] [from→to] — [reason]

Next: execute **Sy** | invoke dynamic-routing | complete

---

Examples

Teaser: 4-step API feature → full plan written → S1 done (migration applied) → S2 preconditions updated after observing schema conflict.

Full pairs: references/examples.md

---

Common Rationalizations

Excuse	Reality
"Planning is overhead"	Rework from a failed one-shot costs more.
"I'll keep the plan in my head"	Not handoff-safe; write the file.
"Execute all steps then fix"	Violates commit-one; observations won't flow.
"process-decomposer already planned"	That produces process entries; this is runtime execution state.
"problem-to-plan wrote a plan doc"	docs/plans/ is spec; this is live execution tracking.

Verification

• Plan file exists at .agent-loom/plans/<task-id>.md
• plan_lint.py passes
• Only one step executed per cycle
• Delta log updated on revision

Red Flags

• Multi-step work with no plan file
• Failed step without delta log entry
• Blind retry of same action after failure

Prune Log

Last pruned: 2026-07-05

• Initial release from high-leverage skill spec (Skill 1 family)

Impact Report

Plan: [task_id] | Steps: N/M done | Lint: [pass/fail] | Current: [step id]