AILang/skills/planner/SKILL.md

name, description

name	description
planner	Use when a milestone spec exists in docs/specs/ and a new iteration is starting. Produces a placeholder-free, bite-sized implementation plan in docs/plans/ that the implement skill can execute task-by-task. Hard-gate before any implementation work.

plan — spec → executable plan

Violating the letter of these rules is violating the spirit.

Overview

A plan is the contract between design (spec) and execution (implement). It commits the file structure, names every file that will be created or modified, and decomposes work into bites small enough that a subagent can execute one in 2-5 minutes without making judgement calls outside its remit.

Plans live at docs/plans/<iteration>.md, the header references the parent spec, and the commit-per-task pattern matches the existing JOURNAL style.

When to Use / Skipping

Triggers:

• A spec at docs/specs/<milestone>.md is approved.
• A new iteration within an active milestone is starting.

May be skipped when:

• The work is a bug fix where the RED test from debug IS the plan (handoff goes straight to implement mini-mode).
• The work is a trivial mechanical edit (one file, ≤30 LOC, no design judgement).

Never skipped for a standard iteration within an active milestone. "I know the milestone, plan from memory" is exactly the failure mode this skill prevents.

The Iron Law

NO PLACEHOLDERS — TBD, TODO, "implement later", "similar to Task N",
or "add appropriate error handling" are PLAN FAILURES.
EVERY STEP THAT CHANGES CODE INCLUDES THE CODE.
EVERY STEP THAT RUNS A COMMAND INCLUDES THE COMMAND AND EXPECTED OUTPUT.

Non-negotiable.

The Process

Step 1 — Read the parent spec

Read docs/specs/<milestone>.md in full. NOT from memory. Even if the spec is recent and you wrote it yourself, re-read it before planning.

The spec is the source of truth; the plan is the projection of one iteration's worth of work onto a task list.

Step 2 — Map file structure

Dispatch ailang-plan-recon with the spec path and iteration scope. Read the returned file-map. Lift the relevant entries into the plan's "Files this plan creates or modifies" section; the Boss may add or amend entries that recon missed.

Dispatch carrier:

Field	Content
spec_path	path to the parent spec
iteration_scope	which sections of the spec this iteration covers
focus_hint	optional — subsystem or symbol to prioritise

Recon does NOT decide decomposition. Two recon dispatches per planner run is unusual but legitimate (e.g. one for the main spec sections, one with a sharper focus_hint for a tricky subsystem). Three or more is a smell — re-read the spec; the iteration scope is probably too broad.

The plan's "Files this plan creates or modifies" section keeps the same shape:

**Files this plan creates or modifies:**

- Create: `<exact path>` — <one-line responsibility>
- Modify: `<exact path>:<line range if known>`
- Test: `<exact path>` — <one-line case description>

Files that change together stay in the same task. Files that change independently get separate tasks.

Step 3 — Write tasks, bite-sized

Each task is a logical unit of change (one feature, one fix, one extension). Each task contains steps; each step is ONE action that takes 2-5 minutes:

### Task N: <Component Name>

**Files:**
- Create: `<exact path>`
- Modify: `<exact path>:<line range if known>`
- Test: `<exact path>`

- [ ] **Step 1: Write the failing test**

```rust
#[test]
fn test_<specific_behaviour>() {
    let result = function(input);
    assert_eq!(result, expected);
}

• Step 2: Run test to verify it fails

Run: cargo test --workspace -p <crate> test_<specific_behaviour> Expected: FAIL with ""

• Step 3: Write minimal implementation

fn function(input: T) -> U {
    // exact code
}

• Step 4: Run test to verify it passes

Run: cargo test --workspace -p <crate> test_<specific_behaviour> Expected: PASS

• Step 5: Commit

git add <paths>
git commit -m "iter <X>.<n>: <subject>"

### Step 4 — Plan header

Every plan starts with this header:

```markdown
# <Iteration Title> — Implementation Plan

> **Parent spec:** `docs/specs/<milestone>.md`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement`
> to run this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** <one sentence>

**Architecture:** <2-3 sentences>

**Tech Stack:** <key crates/libs touched>

---

Step 5 — Self-review

Before committing the plan, run this checklist inline:

1. Spec coverage: every spec section has a task that implements it. If a section has no task, add one.
2. Placeholder scan: grep for "TBD", "TODO", "implement later", "similar to Task", "add appropriate error handling". Any hit is a plan failure to fix.
3. Type consistency: function names, type names, file paths referenced across tasks must match. clearLayers() in Task 3 and clearFullLayers() in Task 7 is a bug.
4. Step granularity: every step is 2-5 minutes. If a step is "implement the parser", split it.

Fix issues inline. No need to re-review — fix and commit.

Step 6 — Commit and hand off

git add docs/plans/<iteration>.md
git commit -m "plan: <iteration> <subject>"

Hand off to implement with: path to the plan file + optional task focus ("only Tasks 1-3 this run").

Handoff Contract

Direction	Carrier
brainstorm → planner	path to docs/specs/<milestone>.md + iteration scope ("this iteration covers spec section X+Y")
planner → implement	path to docs/plans/<iteration>.md + optional task-range focus
planner → brainstorm (bounce)	spec contains placeholders or contradictions: name the offending section, request revision

Common Rationalisations

Excuse	Reality
"TBD in step 4 lets me ship the plan tonight, fill in tomorrow"	Half-decided plans get re-litigated mid-iteration, costing more than the night's sleep saved. Make the decision tonight or close the laptop.
"Bundle Tasks 3 and 4, both small, single commit"	The red-green-refactor cycle is the unit of verification. Bundled commits make bisection lie. If 3 and 4 are inseparable, they're one task — rewrite the decomposition.
"Spec is recent, I wrote it, plan from memory"	Memory diverges from disk. 15 minutes of re-reading is the cheapest insurance in the cycle.
"Step 5 'implement the parser' is fine, I'll detail it at execution time"	Then it's not a step, it's a wish. Steps are bite-sized OR the plan isn't done.
"Task 7 is similar to Task 4, just say so"	The executor may read tasks out of order. Repeat the code.
"The spec has a TBD too, I can pass it through"	Bounce back to brainstorm. Plans inherit spec gaps; spec gaps are not plan placeholders.

Red Flags — STOP

• Any of: "TBD", "TODO", "fill in later", "similar to", "add appropriate " — fix or bounce.
• Steps that describe what to do without showing how
• Function/type/path names that don't match across tasks
• Step descriptions longer than the code they describe
• Header missing parent spec reference
• Self-review skipped because "the plan looks fine"

Cross-references

• Input source: skills/brainstorm/SKILL.md — produces the spec this skill consumes.
• Output target: skills/implement/SKILL.md — runs the plan task-by-task.
• Agents dispatched:
  • skills/planner/agents/ailang-plan-recon.md — Step 2, file-structure mapping (read-only). Mandatory; the Boss does NOT do recon in-context.