mola-plan

Files (5)

• SKILL.md
• intent-clear.md · references/
• intent-unclear.md · references/
• plan-template.md · templates/
• spec-template.md · templates/

SKILL.md (first lines)

# Planning — from ground-check to approved plan

Produces a structured plan file decomposing work into sequenced, verifiable tasks.
For Architecture-class tasks, also produces a design spec before the plan.

## Anti-Patterns

- **"This Is Too Simple To Need A Spec"** — The most expensive mistakes come from unexamined assumptions on "simple" changes. A spec is 1-2 pages, not 50. Spec the simple things; save the expensive surprises for later.
- **Skipping ground before classify** — Ground reveals what is actually involved. Classify without ground is guessing. Always explore first.
- **Beginning implementation** — NEVER begin implementation (even "quick scaffolding" or "just a skeleton"). Outputs are plan files (+ optional spec for Architecture).
- **Skipping approval gates** — Present brief → wait for OK → write. Every section, every artifact.
- **Asking what the codebase can answer** — Explore first. User time is more expensive than search time.

## Workflow

Complete all 6 phases in order.

### Phase 1 - Ground Check

Explore the codebase to validate the problem exists and understand what is involved.
Run these in parallel when independent.

1. **Search** — affected files, entry points, call sites, dependency graph
2. **Pattern discovery** — existing implementations to reference, established conventions
3. **Context gathering** — codebase docs (`AGENTS.md`, README), external documentation, prior plans in `.zoo/plans/`

**Scope assessment:** If the work spans 2+ independent subsystems, stop and request decomposition: "Request decomposition needed: this spans [subsystems] which should be planned independently." Otherwise confirm scope coherent and proceed.

**Output of Ground:** A mental model answering four questions:
- Where do changes go? (files, modules, entry points)
- What exists already? (patterns to follow, tests to update)
- What is the scope? (how many files, how many modules, cross-boundary?)
- What is unknown? (gaps that need classification and user questions)

Do NOT interview the user during Ground. Note questions for Phase 3.

### Phase 2 - Classify

Based on Ground findings, determine the reference strategy:

| Ground signals | References to load |
|---|---|
| Files + approach + boundaries all clear, simple | `references/intent-clear.md` |
| Standard task, intent fuzzy, defaults needed | `references/intent-unclear.md` |
| Architecture-class, real tradeoffs, scope ambiguity | `grill` skill |
| ON THE FENCE | default to `grill` skill |

State the classification once: "Classification: [Clear|Unclear|Architecture]. Loading references: [...]."

**Graceful upgrade:** If mid-flow you realize the task is heavier than classified, load the `grill` skill. No need to restart or re-enter the Workflow. You can load the skill mid-interview and continue.

### Phase 3 - Interview

Load the classified reference(s) and execute their protocol. All three references share:

- **Two Filter discipline** for every question candidate:

  Filter 1: Can the codebase/docs answer this? → research it, don't ask. | Filter 2: Do best-practice defaults answer this? → adopt and inform, don't ask. | Genuine owner-decision → ask (≤2 per turn, recommended answer first).

- ≤2 questions per turn, multi-select when possible, recommended answer first (C3)
- Adopt defaults, inform user — do not interrogate (C4)

**intent-clear.md:** Topology lock → decision-fork questions only → clearance check.
**intent-unclear.md:** Research defaults → adopt → present assumptions ledger → minimal questions (0-2).
**grill skill:** Decision-tree traversal → depth-first branch resolution →
scenario stress testing → domain vocabulary refinement. The `grill` skill
is the single source of truth for Architecture-class interview — do not duplicate its protocol here. Load it via the skill tool.

Do NOT duplicate reference content in this SKILL. Each reference owns its protocol.

### Phase 4 - Present Design (Incremental)

After the interview resolves, present the design one section at a time. Scale each section to its complexity:

1. **Context** — what triggered this, code involved, user need
2. **Goals** — specific, measurable design objectives
3. **Key Decisions** — chosen approach with rationale
4. **Scope** — Must have + Must NOT have (explicit guardrails)
5. **Risks** — known risks and mitigations
6. **Success Criteria** — how we will know the design achieves its goals

2-3 sentences if straightforward, up to 200-300 words if nuanced. After EACH section, ask for user approval. If the user requests revision, revise that section and continue.

**Scale by classification:** Clear/Unclear → lightweight brief (Context/Approach/Scope/Risks in one pass). Architecture → section-by-section with full depth.

**Anti-patterns:**
- Dumping the whole design at once → user cannot give focused feedback
- Skipping pauses for approval → user surprise on final write
- Continuing past clear objections without resolving

### Phase 5 - Produce

#### If spec path (Architecture classification):

**Step 5a: Scaffold spec file**

Read `templates/spec-template.md` and adapt it into a spec file:

1. Derive the title from the slug (kebab-case → title case).
2. Compute today's date as `YYYYMMDD`.
3. Write the spec via the `write` tool to `.zoo/plans/<slug>-spec-<YYYYMMDD>.md`
   with this frontmatter:

   ```yaml
   ---
   title: "<Title>"
   slug: "<slug>-spec-<YYYYMMDD>"
   created: "<ISO timestamp>"
   updated: "<ISO timestamp>"
   status: awaiting-approval
   ---
   ```

   Then write the template body, replacing `{{TITLE}}` with the title and filling placeholder sections from the design interview.

**Step 5b: Fill sections** — via edit tool, fill each section per the inline placeholder guidance. Each decision entry includes: Chosen option, Alternatives considered, Scenarios tested.

**Step 5c: Self-review** — run 4 checks, fix findings inline:

From 418-teapot/ZooKeeper, MIT.

More from 418-teapot/ZooKeeper