design

Design a change — create a change container (if needed) and generate spec artifacts.

<decision_boundary>

Use for:

• Creating a new Beat change and generating spec artifacts (proposal, gherkin, design.md)
• Resuming artifact generation for an existing change that has pending spec artifacts
• Choosing which spec artifacts to include (presets: Full, Standard, Minimal, Technical, Custom)

NOT for:

• Breaking down tasks or creating execution plans (use /beat:plan)
• Exploring ideas or thinking through a problem before committing (use /beat:explore)
• Implementing code (use /beat:apply)
• Reviewing or verifying implementation (use /beat:verify)

Trigger examples:

• "Design a user authentication feature" / "Create a change for login" / "Generate specs for X"
• Should NOT trigger: "break down the tasks" / "let me think about this" / "implement the change"

</decision_boundary>

Before writing gherkin scenarios: you MUST run the four-challenge CONTEXT.md check (see step 4 below) and ensure every project-specific term used in scenarios is defined in beat/CONTEXT.md. Create the glossary lazily — only when the first term is added.

After writing each artifact: you MUST run the four-check spec self-review (placeholder / consistency / scope / ambiguity). Fix issues inline.

While writing design.md: you MUST run the three-condition ADR gate (hard-to-reverse + surprising + real trade-off — see references/adr-format.md) on each Key Decision. When all three hold, offer to lift the decision into a new ADR under docs/adr/. The user may decline.

Invoke in order: worktrees first (isolate), then brainstorming (design).

If a prerequisite skill is unavailable (not installed), continue with fallback — but NEVER skip because you judged it unnecessary.

Prerequisites (invoke before proceeding)

Skill	When	Priority
superpowers:using-git-worktrees	Before first file write	MUST
superpowers:brainstorming	Before creating proposal or design	MUST
mattpocock-skills:grill-with-docs	When CONTEXT.md ambiguity is complex enough that a full grilling session is warranted	OPTIONAL

If a prerequisite skill is unavailable (skill not installed), skip and continue. For optional skills (grill-with-docs), offer to invoke when applicable; if the user declines or it isn't installed, proceed with the four-challenge check inline.

Rationalization Prevention

Thought	Reality
"I don't need a worktree for just writing specs"	Without a worktree, artifacts live in the main workspace and won't carry into apply. Isolate from the start.
"brainstorming isn't needed, the user already described what they want"	A description is not a design. brainstorming surfaces assumptions, alternatives, and edge cases.
"The user wants speed, invoking superpowers will slow us down"	Skipping prerequisites produces lower-quality artifacts that cause rework during apply and verify.
"This change is simple enough to skip brainstorming"	Simple changes finish brainstorming quickly. Complex changes need it most. There is no middle ground where skipping helps.
"The domain terms are obvious, no need to update CONTEXT.md"	Obvious to you, not to future-you or anyone else reading the feature in six months. Glossary entries are two lines. Add them inline.
"Spec self-review is overkill, the artifact is short"	Self-review catches placeholders, contradictions, and ambiguities that compound through plan and apply. The four checks take 30 seconds.
"This decision is just for this change, no ADR needed"	Run the three-condition gate. If it's hard-to-reverse, surprising, and a real trade-off, future changes will trip over it — that's the ADR's job. Decisions that are change-specific don't pass the gate; let the gate decide, not your gut.
"We'll lift this into an ADR later"	"Later" rarely arrives. The decision is fresh now; the ADR is 1-3 sentences. Write it inline.