spec-brainstorm
Conversational design workshop for substantial work. Interviews the human one question at a time, explores 2-3 approaches with trade-offs, and presents the design section by section for approval before writing only design.md, then stops. Combines requirements discovery with codebase research and architecture design. Use when the user explicitly requests a spec or when atelier-orchestrator selects a Spec-backed Plan. Ambiguous design or discovery requests route through atelier-orchestrator.
martinffx · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add martinffx/atelier --skill spec-brainstorm技能说明
name: spec-brainstorm description: > Conversational design workshop for substantial work. Interviews the human one question at a time, explores 2-3 approaches with trade-offs, and presents the design section by section for approval before writing only design.md, then stops. Combines requirements discovery with codebase research and architecture design. Use when the user explicitly requests a spec or when atelier-orchestrator selects a Spec-backed Plan. Ambiguous design or discovery requests route through atelier-orchestrator. user-invocable: true argument-hint:
Spec Brainstorm
Conversational design workshop for substantial work that produces a focused, reviewed spec.
One question at a time. Multiple approaches explored. Design approved in sections. Ruthless scope control. No implementation until design is approved.
Run this skill only after atelier-orchestrator selects a Spec-backed Plan or the human
explicitly requests a spec. Bounded work should go directly to spec-plan for an Inline
Plan. Do not reclassify the planning mode here.
Artifact
docs/specs/YYYY-MM-DD-<feature>/
└── design.md ← This skill's output
Requirements are inline — no separate requirements.json needed.
Exclusive output contract
This skill may create or update only the design.md shown above. It may inspect the
repository and discuss drafts in conversation, but it must not modify any other file, create
plan.json, create tracker entries, invoke another workflow skill, or write implementation
code. This boundary still applies when the human asks to brainstorm, plan, and implement in
one request. Finish design.md, report it, and stop.
Lessons
These principles apply to every spec, every time.
Specs must earn their cost
Persisted specs are for work whose discovery, architecture, dependencies, or coordination needs justify a durable artifact. Do not pull bounded work into this workflow merely because it touches multiple files or takes time. That work belongs in an Inline Plan.
Design for isolation and clarity
Break the system into units with one clear purpose each. Well-defined interfaces between them. Each unit independently understandable and independently testable. If you can't explain a unit's job in one sentence, it's doing too much.
Working in existing codebases
Explore the current structure first. Follow existing patterns. Targeted improvements only. No unrelated refactoring. Understand why things are the way they are before proposing changes. Treat loaded skills as relevant guidance, not as a requirement to apply every pattern they contain.
Decomposition
If the request describes multiple independent subsystems, flag it immediately. Decompose into sub-projects before diving into details. Each substantial sub-project gets its own spec and plan; bounded sub-projects can use Inline Plans. A spec that tries to cover three subsystems helps no one.
Keep migrations separate from authorization, product behavior, infrastructure, schema, and test-platform projects. Do not use a migration as permission to redesign adjacent systems.
YAGNI ruthlessly
Remove unnecessary features from all designs. If a capability isn't needed for the first user story, it doesn't go in the spec. Every feature is a cost — to build, to test, to maintain, to understand later. Push back on scope creep during discovery.
Future consumers do not justify shared infrastructure. A "reusable foundation" may describe an architectural quality, but it is not a user story or a current requirement.
Step 1: Orient
Before diving in, understand where you are.
- Read project context — AGENTS.md, README, existing architecture docs
- Check existing specs — Scan
docs/specs/for previous work. What domain model exists? What patterns are established? What has been built before? - Read recent specs — What was the last thing built? Is this feature building on existing work, extending it, or something greenfield?
This is silent — don't narrate it. Let the context inform where you focus.
Step 2: Discovery
Ask questions to understand what to build. Skip this step if requirements are already clear from context (existing specs, human provided details, etc.).
Interview style
Ask one question at a time. Multiple choice preferred when possible — give 2-4 concrete options rather than open-ended prompts. Keep the conversation moving.
Good: "Should this be real-time or batch-processed? (a) Real-time via WebSocket, (b) Periodic polling every 30s, (c) On-demand when user requests it."
Bad: "How should the data synchronization work?"
When to skip discovery
- Human provides clear, detailed requirements
- Feature extends existing work with well-defined scope
- Human says "spec out X" and X is specific enough
Decomposition check
Before asking any detail questions, assess scope. If the request describes multiple independent subsystems (e.g., "build a notification system with email, SMS, push, and an admin dashboard"):
- Flag it immediately: "This looks like multiple independent projects. Let me propose a decomposition."
- Break it down: Identify the subsystems and their dependencies.
- Get agreement: "Which of these should we spec first?"
Do not try to spec everything in one document.
YAGNI check
During discovery, push back on scope:
- "Do you need this in the first version, or is it a nice-to-have?"
- "Can we ship without this and add it later if needed?"
- "This feature adds significant complexity — is the use case real or hypothetical?"
If the human insists, include it — but flag the trade-off in the spec.
Discovery questions
Adapt these to context. Not all are needed every time.
- What problem are we solving? — Concrete problem statement, not solution description
- Who has this problem? — User roles
- How do they solve it today? — Current