diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md new file mode 100644 index 0000000..606ab7e --- /dev/null +++ b/skills/brainstorm/SKILL.md @@ -0,0 +1,216 @@ +--- +name: brainstorm +description: Use when a new milestone is starting — gathers requirements, explores 2-3 approaches with trade-offs, presents a sectioned design with user approval, writes the spec to docs/specs/. Hard-gate before any plan or code work; applies even when the user says they have a clear vision. +--- + +# brainstorm — milestone spec generator + +> **Violating the letter of these rules is violating the spirit.** + +## Overview + +The spec is where the orchestrator does the design work. It is the +artefact that future iterations, the architect agent, and any future +LLM read to understand WHAT the milestone delivers and WHY. Skipping +the spec means shipping the user's intuition unfiltered, which is +exactly the reactive-deference failure mode AILang's orchestrator +discipline exists to prevent. + +This skill adapts `superpowers:brainstorming` to the AILang project, +producing specs at `docs/specs/.md`. + +## When to Use / Skipping + +Triggers: +- A new milestone is starting (e.g. user proposes a new feature + area, a new subsystem, or a major refactor of an existing one). +- A milestone-scope spec is missing for an existing line of work + and one is needed retroactively. + +**Skipping is permitted only** for: +- A bug-fix iteration (use `debug` directly). +- A tidy iteration (use `audit` directly). +- A trivial mechanical edit (≤1 file, ≤30 LOC, no design judgement). + +**Skipping is not permitted** for: +- A user request framed as "I have a clear vision, just plan it". +- A milestone described as "small, only two iterations". +- A milestone where you are confident you know what to build. + +The first two cases above are the most common pressure to skip; +both are explicitly resisted by this skill (see Common +Rationalisations). + +## The Hard-Gate + +``` +NO IMPLEMENTATION, SCAFFOLDING, OR DOWNSTREAM SKILL INVOCATION +UNTIL A SPEC HAS BEEN PRESENTED AND THE USER HAS APPROVED IT. +``` + +The hard-gate applies regardless of perceived simplicity. The spec +can be short for a small milestone (a few sections), but it MUST +exist and be approved before any plan or code work begins. + +## The Process + +### Step 1 — Explore project context + +Before asking any clarifying questions: +- Read the latest entries in `docs/JOURNAL.md` (most recent + milestones, current state). +- Skim `docs/DESIGN.md` for the invariants the new milestone + might touch. +- `git log --oneline -20` to see what just shipped. +- Identify scope: is this one milestone, or does it need to be + decomposed into sub-milestones first? If multi-subsystem, decompose. + +### Step 2 — Ask clarifying questions, one at a time + +Multiple-choice when possible (easier to answer). One question per +message — no batching. Focus on: +- **Purpose:** what problem does this solve? +- **Constraints:** what semantic / performance / compatibility + invariants must hold? +- **Success criteria:** how do we know it shipped? +- **Scope:** what is OUT of scope? + +### Step 3 — Propose 2-3 approaches with trade-offs + +Lead with your recommended option and explain why. Each approach +gets: +- core idea (1-2 sentences) +- substantive trade-offs (semantic fit, schema impact, performance, + composability) +- effort observation (NOT effort as rationale — see CLAUDE.md + "Design rationale ≠ implementation effort") + +Wait for user choice before proceeding. + +### Step 4 — Apply the feature-acceptance criterion + +A feature ships only if: +- An LLM author (= future me) naturally produces code that uses it, + AND +- The feature measurably improves correctness or removes redundancy. + +Aesthetic appeal does not count. Human ergonomics do not count. If +the answer to either criterion is "I'm not sure", the feature is +probably not ready. The full criterion lives in `docs/DESIGN.md` +("Feature-acceptance criterion"); this skill is the gate that +applies it during spec writing. + +### Step 5 — Present design in sections + +Scale each section to its complexity (a few sentences if +straightforward, up to 200-300 words if nuanced). Cover: +- Architecture +- Components +- Data flow +- Error handling +- Testing strategy + +Ask after each section whether it looks right. Be ready to revisit +earlier sections if a later one surfaces a contradiction. + +### Step 6 — Write the spec + +Path: `docs/specs/YYYY-MM-DD-.md`. + +Structure: + +```markdown +# — Design Spec + +**Date:** YYYY-MM-DD +**Status:** Draft — awaiting user spec review +**Authors:** Brummel (orchestrator) + Claude + +## Goal +## Architecture +## Components +## Data flow +## Error handling +## Testing strategy +## Acceptance criteria +``` + +### Step 7 — Self-review + +Inline checklist (not a subagent dispatch): + +1. **Placeholder scan:** any "TBD", "TODO", incomplete sections, + vague requirements? Fix. +2. **Internal consistency:** sections must not contradict. + Architecture must match component descriptions. +3. **Scope check:** focused enough for one plan, or does it need + sub-milestone decomposition? +4. **Ambiguity check:** could any requirement be interpreted two + ways? If so, pick one and make it explicit. + +Fix issues inline. No need to re-review — fix and commit. + +### Step 8 — Commit + user-review gate + +```bash +git add docs/specs/<filename>.md +git commit -m "spec: <milestone> <topic>" +``` + +Tell the user: + +> Spec written and committed to `<path>`. Please review it and +> let me know if you want to make any changes before we start the +> implementation plan. + +Wait for the user's response. If they request changes, make them +and re-run Step 7. Only proceed to the next step after approval. + +### Step 9 — Hand off to `plan` + +The terminal state of `brainstorm` is invoking `plan`. NO other +skill is invoked from `brainstorm`. NO direct jump to `implement`. + +Hand off carries: +- path to `docs/specs/<milestone>.md` +- iteration scope ("the first iteration covers section X+Y of the + spec") + +## Handoff Contract + +| Direction | Carrier | +|-----------|---------| +| user → `brainstorm` | new milestone request | +| `brainstorm` → `plan` | path to spec + iteration scope | + +## Common Rationalisations + +| Excuse | Reality | +|--------|---------| +| "User says 'clear vision, just plan it' — skip the spec" | "Clear vision" is a starting point, not a spec. The user's intuition hasn't priced in semantic commitments (RC, uniqueness, codegen, schema). Write the spec; frame it as "load-bearing decisions this idea forces on us". | +| "Milestone is small, two iterations, no spec needed" | Iteration count isn't the metric — feature surface is. A two-iter feature touching DESIGN.md invariants needs a spec; a CLI flag does not. Assess what the feature changes in invariants. | +| "Three approaches in, none feel right, ship the least bad" | Three unsatisfying approaches usually means the problem is mis-framed. Stop, write a JOURNAL entry capturing the three approaches and what fails about each, sleep on it. End-of-day pressure is the worst signal to resolve a design fork. | +| "User is busy, present my own design without Q&A" | Reactive deference disguised as decisiveness. The Q&A surfaces constraints the user hasn't articulated; skipping it means shipping the user's defaults, not their intent. | +| "Spec exists from previous milestone, append to it" | New milestone = new spec file. The architect agent reads spec files per milestone; mixing scopes makes drift review unreadable. | +| "Approaches A, B, C are all bad — proceed with A" | This is exactly the moment to surface "the problem is mis-framed" rather than ratify a known-bad shape into DESIGN.md. JOURNAL the impasse, escalate to user. | + +## Red Flags — STOP + +- "Skip the spec" thoughts (any flavour) +- "One paragraph is enough" +- "User said it's clear, who am I to push back" +- "The 2-3 approaches all suck, just pick one" +- Skipping Step 7 self-review because "I wrote it carefully" +- Jumping straight from spec to `implement` (must go via `plan`) +- Inventing a design rationale that's actually about effort, not + semantics + +## Cross-references + +- **Upstream pattern:** `superpowers:brainstorming` — source of + the hard-gate, sectioned design, user-review gate. +- **Project source:** `docs/DESIGN.md` "Feature-acceptance + criterion" — gate this skill applies during spec writing. +- **Output target:** `skills/plan/SKILL.md` — only valid next + skill. +- **No private agents.** This skill is dialogue-driven.