From 42e5d9b57013b845d2609057f1248cf85fe4c63a Mon Sep 17 00:00:00 2001 From: Brummel Date: Sat, 9 May 2026 14:21:14 +0200 Subject: [PATCH] =?UTF-8?q?feat:=20skill=20plan=20=E2=80=94=20spec=20to=20?= =?UTF-8?q?executable=20plan=20with=20no-placeholders=20rule?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/plan/SKILL.md | 216 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 skills/plan/SKILL.md diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md new file mode 100644 index 0000000..50be39d --- /dev/null +++ b/skills/plan/SKILL.md @@ -0,0 +1,216 @@ +--- +name: plan +description: 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. + +This skill adapts `superpowers:writing-plans` to the AILang +project conventions: plans live at `docs/plans/.md`, +header references the parent spec, commit-per-task pattern +matches the existing JOURNAL style. + +## When to Use / Skipping + +Triggers: +- A spec at `docs/specs/.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. +``` + +Lifted verbatim from `superpowers:writing-plans`. Non-negotiable. + +## The Process + +### Step 1 — Read the parent spec + +Read `docs/specs/.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 + +Before defining tasks, list every file the iteration will create or +modify, and what each one is responsible for. This is where +decomposition decisions are locked in. + +```markdown +**Files this plan creates or modifies:** + +- Create: `crates/ailang-codegen/src/.rs` — +- Modify: `crates/ailang-check/src/typeclass.rs` — adds + +- Test: `crates/ail/tests/e2e.rs` — adds +``` + +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: + +```markdown +### Task N: + +**Files:** +- Create: `` +- Modify: `:` +- Test: `` + +- [ ] **Step 1: Write the failing test** + +```rust +#[test] +fn test_() { + let result = function(input); + assert_eq!(result, expected); +} +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: `cargo test --workspace -p test_` +Expected: FAIL with "" + +- [ ] **Step 3: Write minimal implementation** + +```rust +fn function(input: T) -> U { + // exact code +} +``` + +- [ ] **Step 4: Run test to verify it passes** + +Run: `cargo test --workspace -p test_` +Expected: PASS + +- [ ] **Step 5: Commit** + +```bash +git add +git commit -m "iter .: " +``` +``` + +### Step 4 — Plan header + +Every plan starts with this header: + +```markdown +# — Implementation Plan + +> **Parent spec:** `docs/specs/.md` +> +> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement` +> to run this plan. Steps use `- [ ]` checkboxes for tracking. + +**Goal:** + +**Architecture:** <2-3 sentences> + +**Tech Stack:** + +--- +``` + +### 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 + +```bash +git add docs/plans/.md +git commit -m "plan: " +``` + +Hand off to `implement` with: path to the plan file + optional +task focus ("only Tasks 1-3 this run"). + +## Handoff Contract + +| Direction | Carrier | +|-----------|---------| +| `brainstorm` → `plan` | path to `docs/specs/.md` + iteration scope ("this iteration covers spec section X+Y") | +| `plan` → `implement` | path to `docs/plans/.md` + optional task-range focus | +| `plan` → `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 + +- **Upstream pattern:** `superpowers:writing-plans` — source of the + bite-sized + No-Placeholders rule. +- **Input source:** `skills/brainstorm/SKILL.md` — produces the + spec this skill consumes. +- **Output target:** `skills/implement/SKILL.md` — runs the plan + task-by-task. +- **No private agents.** This skill is dialogue-driven (orchestrator + + spec).