feat: skill brainstorm — milestone spec generator with hard-gate
This commit is contained in:
@@ -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/<milestone>.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-<milestone>.md`.
|
||||
|
||||
Structure:
|
||||
|
||||
```markdown
|
||||
# <Title> — 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.
|
||||
Reference in New Issue
Block a user