{"slug":"spec-brainstorm","title":"spec-brainstorm","summary":"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 codeb","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-29T15:21:48.629031Z","repo":{"url":"https://github.com/martinffx/atelier","stars":50,"forks":5,"license":"MIT","updatedAt":"2026-11-13T11:26:55Z"},"bodyHtml":"<hr>\n<h2>name: spec-brainstorm\ndescription: &gt;\nConversational design workshop for substantial work. Interviews the human one question\nat a time, explores 2-3 approaches with trade-offs, and presents the design\nsection by section for approval before writing only design.md, then stops. Combines\nrequirements discovery with codebase research and architecture design.\nUse when the user explicitly requests a spec or when atelier-orchestrator selects a\nSpec-backed Plan. Ambiguous design or discovery requests route through atelier-orchestrator.\nuser-invocable: true\nargument-hint: </h2>\n<h1>Spec Brainstorm</h1>\n<p>Conversational design workshop for substantial work that produces a focused, reviewed spec.</p>\n<p>One question at a time. Multiple approaches explored. Design approved in\nsections. Ruthless scope control. No implementation until design is approved.</p>\n<p>Run this skill only after <code>atelier-orchestrator</code> selects a Spec-backed Plan or the human\nexplicitly requests a spec. Bounded work should go directly to <code>spec-plan</code> for an Inline\nPlan. Do not reclassify the planning mode here.</p>\n<h2>Artifact</h2>\n<pre><code>docs/specs/YYYY-MM-DD-&lt;feature&gt;/\n└── design.md  ← This skill's output\n</code></pre>\n<p>Requirements are inline — no separate requirements.json needed.</p>\n<h3>Exclusive output contract</h3>\n<p>This skill may create or update only the <code>design.md</code> shown above. It may inspect the\nrepository and discuss drafts in conversation, but it must not modify any other file, create\n<code>plan.json</code>, create tracker entries, invoke another workflow skill, or write implementation\ncode. This boundary still applies when the human asks to brainstorm, plan, and implement in\none request. Finish <code>design.md</code>, report it, and stop.</p>\n<hr>\n<h2>Lessons</h2>\n<p>These principles apply to every spec, every time.</p>\n<h3>Specs must earn their cost</h3>\n<p>Persisted specs are for work whose discovery, architecture, dependencies, or coordination\nneeds justify a durable artifact. Do not pull bounded work into this workflow merely because\nit touches multiple files or takes time. That work belongs in an Inline Plan.</p>\n<h3>Design for isolation and clarity</h3>\n<p>Break the system into units with one clear purpose each. Well-defined interfaces between\nthem. Each unit independently understandable and independently testable. If you can't\nexplain a unit's job in one sentence, it's doing too much.</p>\n<h3>Working in existing codebases</h3>\n<p>Explore the current structure first. Follow existing patterns. Targeted improvements only.\nNo unrelated refactoring. Understand why things are the way they are before proposing\nchanges. Treat loaded skills as relevant guidance, not as a requirement to apply every pattern\nthey contain.</p>\n<h3>Decomposition</h3>\n<p>If the request describes multiple independent subsystems, flag it immediately. Decompose\ninto sub-projects before diving into details. Each substantial sub-project gets its own spec\nand plan; bounded sub-projects can use Inline Plans. A spec that tries to cover three\nsubsystems helps no one.</p>\n<p>Keep migrations separate from authorization, product behavior, infrastructure, schema, and\ntest-platform projects. Do not use a migration as permission to redesign adjacent systems.</p>\n<h3>YAGNI ruthlessly</h3>\n<p>Remove unnecessary features from all designs. If a capability isn't needed for the first\nuser story, it doesn't go in the spec. Every feature is a cost — to build, to test,\nto maintain, to understand later. Push back on scope creep during discovery.</p>\n<p>Future consumers do not justify shared infrastructure. A \"reusable foundation\" may describe\nan architectural quality, but it is not a user story or a current requirement.</p>\n<hr>\n<h2>Step 1: Orient</h2>\n<p>Before diving in, understand where you are.</p>\n<ol>\n<li><strong>Read project context</strong> — AGENTS.md, README, existing architecture docs</li>\n<li><strong>Check existing specs</strong> — Scan <code>docs/specs/</code> for previous work. What domain model\nexists? What patterns are established? What has been built before?</li>\n<li><strong>Read recent specs</strong> — What was the last thing built? Is this feature building\non existing work, extending it, or something greenfield?</li>\n</ol>\n<p>This is silent — don't narrate it. Let the context inform where you focus.</p>\n<hr>\n<h2>Step 2: Discovery</h2>\n<p>Ask questions to understand what to build. Skip this step if requirements are already\nclear from context (existing specs, human provided details, etc.).</p>\n<h3>Interview style</h3>\n<p>Ask <strong>one question at a time</strong>. Multiple choice preferred when possible — give 2-4\nconcrete options rather than open-ended prompts. Keep the conversation moving.</p>\n<p><strong>Good:</strong> \"Should this be real-time or batch-processed? (a) Real-time via WebSocket,\n(b) Periodic polling every 30s, (c) On-demand when user requests it.\"</p>\n<p><strong>Bad:</strong> \"How should the data synchronization work?\"</p>\n<h3>When to skip discovery</h3>\n<ul>\n<li>Human provides clear, detailed requirements</li>\n<li>Feature extends existing work with well-defined scope</li>\n<li>Human says \"spec out X\" and X is specific enough</li>\n</ul>\n<h3>Decomposition check</h3>\n<p>Before asking any detail questions, assess scope. If the request describes multiple\nindependent subsystems (e.g., \"build a notification system with email, SMS, push, and\nan admin dashboard\"):</p>\n<ol>\n<li><strong>Flag it immediately:</strong> \"This looks like multiple independent projects. Let me\npropose a decomposition.\"</li>\n<li><strong>Break it down:</strong> Identify the subsystems and their dependencies.</li>\n<li><strong>Get agreement:</strong> \"Which of these should we spec first?\"</li>\n</ol>\n<p>Do not try to spec everything in one document.</p>\n<h3>YAGNI check</h3>\n<p>During discovery, push back on scope:</p>\n<ul>\n<li>\"Do you need this in the first version, or is it a nice-to-have?\"</li>\n<li>\"Can we ship without this and add it later if needed?\"</li>\n<li>\"This feature adds significant complexity — is the use case real or hypothetical?\"</li>\n</ul>\n<p>If the human insists, include it — but flag the trade-off in the spec.</p>\n<h3>Discovery questions</h3>\n<p>Adapt these to context. Not all are needed every time.</p>\n<ol>\n<li><strong>What problem are we solving?</strong> — Concrete problem statement, not solution description</li>\n<li><strong>Who has this problem?</strong> — User roles</li>\n<li><strong>How do they solve it today?</strong> — Current workflow and pain points</li>\n<li><strong>What does success look like?</strong> — Measurable outcomes</li>\n<li><strong>What does this integrate with?</strong> — Existing systems, APIs</li>\n<li><strong>What constraints exist?</strong> — Technical, business, regulatory</li>\n</ol>\n<p>If you already know answers from orientation, confirm rather than ask.</p>\n<p><strong>Tell the human:</strong> \"Based on my research, here's my understanding of what we're building.\nDoes this look right?\"</p>\n<p><strong>STOP. Wait for human confirmation.</strong></p>\n<hr>\n<h2>Step 3: Research</h2>\n<p>Read the relevant codebase deeply. Not signatures — implementations, edge cases, error\nhandling, data flows. Trace callers and callees. Read tests to understand expected\nbehaviour.</p>\n<p>Collect research findings for the spec as the foundation. Do not write <code>design.md</code> until the\napproved design sections are assembled in Step 4c.</p>\n<p>The research section must map each relevant concern to the code that already handles it and\nthe current requirement that drives the decision:</p>\n<table>\n<thead>\n<tr>\n<th>Concern</th>\n<th>Existing solution</th>\n<th>Decision</th>\n<th>Current requirement</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>IDs</td>\n<td>Shared parser and ID type</td>\n<td>reuse</td>\n<td>Parse route parameters</td>\n</tr>\n</tbody>\n</table>\n<p>Use only <code>reuse</code>, <code>modify</code>, <code>delete</code>, or <code>new</code> in the Decision column. Every <code>new</code> concept must\nmap to a present requirement; a future or hypothetical consumer does not qualify.</p>\n<p><strong>Tell the human:</strong> \"I've written the research section of the spec. Ready for you to\nreview before I continue with the design.\"</p>\n<p><strong>STOP. Wait for human review.</strong></p>\n<hr>\n<h2>Step 4: Design</h2>\n<p>Design happens in three phases: explore approaches, present the design in sections,\nthen write the spec file.</p>\n<h3>4a. Explore approaches</h3>\n<p>Before settling on a design, present <strong>2-3 approaches</strong> with trade-offs.</p>\n<p>The first approach must keep the existing architecture and make the smallest correct change.\nPresent broader approaches only when a current requirement makes their extra cost relevant.</p>\n<p>For each approach, address:</p>\n<ol>\n<li><strong>What it looks like</strong> — Brief architecture sketch</li>\n<li><strong>Pros</strong> — What makes this approach good</li>\n<li><strong>Cons</strong> — What's painful, expensive, or risky</li>\n<li><strong>Complexity estimate</strong> — Rough sense of implementation effort</li>\n</ol>\n<p>Lead with your recommended option and explain why it wins.</p>\n<p>Before asking the human to approve an approach or design batch, remove anything justified only\nby completeness, consistency, or hypothetical reuse.</p>\n<p><strong>Example:</strong></p>\n<blockquote>\n<p><strong>Approach A: Single table with JSON columns</strong></p>\n<ul>\n<li>Simple schema, fast to implement</li>\n<li>Querying inside JSON is limited, migration pain later</li>\n<li>Complexity: Low</li>\n</ul>\n<p><strong>Approach B: Normalized relational tables</strong></p>\n<ul>\n<li>Clean queries, easy to evolve schema</li>\n<li>More joins, more migration files, more code</li>\n<li>Complexity: Medium</li>\n</ul>\n<p><strong>Recommendation:</strong> Approach B — the query flexibility matters more here than\nimplementation speed.</p>\n</blockquote>\n<p>Get explicit approval on the chosen approach before presenting the design.</p>\n<p><strong>Tell the human:</strong> \"Which approach should we go with? Or should I explore a\ndifferent direction?\"</p>\n<p><strong>STOP. Wait for human to choose an approach.</strong></p>\n<h3>4b. Present the design in sections</h3>\n<p>Present the design in batches. Get approval after each batch before continuing.</p>\n<p>Sections already confirmed in earlier steps (Problem, Scope, Constraints, Context)\nare written into the spec from those confirmations — do not re-present them.</p>\n<p><strong>Batch A: User Stories</strong> — the contract you're designing against. Formal stories\nwith acceptance criteria and priorities. If rejected: revise. If the rejection\nreveals a scope misunderstanding, loop back to Discovery (Step 2).</p>\n<p><strong>Batch B: Architecture</strong> — component design, domain modeling, and layer\nboundaries. Use installed language-specific architecture or API-design skills as relevant to\nyour stack. Then present: component structure, domain model, where business\nlogic lives, where IO lives. If rejected: revise. If the rejection undermines\nthe chosen approach, offer to return to approach exploration (4a). If it\nreveals a fundamental gap, loop back to Research (Step 3). If the detail reveals\nthe work is far more complex than estimated, say so and offer to revisit the\napproach.</p>\n<p><strong>Batch C: API Design + Data Model</strong> — contracts derived from the approved\narchitecture. Skip sections that don't apply, but say so explicitly (\"No API\nchanges — moving to Trade-offs\"). Never skip silently. If rejected: revise. If\nthe rejection implicates the architecture, go back to Batch B.</p>\n<p><strong>Batch D: Trade-offs + Open Questions</strong> — alternatives considered, why this\napproach wins, known limitations, anything unresolved. Usually revisable inline.</p>\n<p>Each batch ends with:</p>\n<p><strong>Tell the human:</strong> \"Does this look right?\"</p>\n<p><strong>STOP. Wait for approval before continuing.</strong></p>\n<p>If you loop twice on the same batch, stop and ask:</p>\n<blockquote>\n<p>\"We've looped on [batch] twice. Should we reconsider the approach?\"</p>\n</blockquote>\n<p><strong>Terminology discipline:</strong> while drafting batches, challenge terms against <code>CONTEXT.md</code> and\nrecord resolved terminology in <code>design.md</code>. Do not update <code>CONTEXT.md</code> from this skill. If\ndomain confusion runs deep, suggest pausing for <strong>oracle-grill-me</strong> before continuing.</p>\n<h3>4c. Write the spec</h3>\n<p>Once all batches are approved, write the full spec document.</p>\n<h4>What the spec should contain</h4>\n<pre><code># Feature Name\n\n## Problem\n- What problem are we solving\n- Who has this problem\n- How they solve it today\n\n## Scope\n- **In scope:** [specific capabilities]\n- **Out of scope:** [explicitly deferred]\n\n## User Stories\n- US-1: As a [role], I want [action], so that [benefit]\n  - Given X, when Y, then Z\n- Priority: must/should/could\n\n## Constraints\n- [Technical or business constraints]\n\n## Context\n- What exists today, how it works end-to-end\n- Existing patterns and conventions\n- Dependencies and integration points\n- Gotchas, assumptions, technical debt\n\n## Architecture\n- Component structure (functional core / effectful edge)\n- Domain model: entities, value objects, aggregates\n- Where business logic lives, where IO lives\n\n## API Design\n- Endpoints, request/response contracts\n- Error handling approach\n- Event contracts (published/consumed)\n\n## Data Model\n- Schema design, access patterns\n- Migrations needed\n\n## Trade-offs\n- Alternatives considered\n- Why this approach wins\n- Known limitations\n\n## Open Questions\n- Anything unresolved needing human input\n</code></pre>\n<p>Scale each section to complexity — a few sentences if straightforward, detailed if\nnuanced.</p>\n<h4>Reference implementations</h4>\n<p>If the human provides reference code — from open source, from elsewhere in the\ncodebase — use it as a concrete guide. Working from a reference produces\ndramatically better designs.</p>\n<h4>Self-review</h4>\n<p>After writing the file, check it with fresh eyes:</p>\n<ol>\n<li><strong>Placeholder scan</strong> — Any TBD, TODO, FIXME, or incomplete sections? Every\nsection should have real content or be removed.</li>\n<li><strong>Internal consistency</strong> — Do sections contradict each other? If the\nArchitecture section says \"stateless\" but the Data Model includes session\nstate, resolve the conflict.</li>\n<li><strong>Scope check</strong> — Is this focused enough for a single implementation plan?\nIf the spec covers more than one independent subsystem, it should have been\ndecomposed in Step 2. If it's still too broad, flag it now.</li>\n<li><strong>Ambiguity check</strong> — Could any requirement be interpreted two ways? If so,\npick one interpretation, state it explicitly, and let the human correct you.</li>\n<li><strong>Necessity check</strong> — Delete concepts justified only by completeness, consistency, or\nhypothetical reuse. Confirm every remaining new concept maps to a current requirement.</li>\n</ol>\n<p><strong>Substance rule:</strong> if a fix changes the substance of an approved section,\nre-present that section for approval. Wording and consistency fixes go inline —\nnote them at handoff.</p>\n<hr>\n<h2>Step 5: Handoff</h2>\n<p><strong>Tell the human:</strong></p>\n<blockquote>\n<p>\"Brainstorm complete. Design written to <code>docs/specs/&lt;path&gt;/design.md</code>. A separate\n<code>spec-plan</code> invocation can create <code>plan.json</code> after you approve this document.\"</p>\n</blockquote>\n<p>If the human requests changes — in conversation or by annotating the file — address every note,\nupdate the spec, and re-run the self-review. If a change alters the substance of an approved\nsection, re-present that section for approval before continuing. Resolve questions that affect\nscope, architecture, contracts, data, security, or task ordering before handoff.</p>\n<p>Stop after reporting the completed <code>design.md</code>. Do not invoke <code>spec-plan</code>, offer to continue\nautomatically, create <code>plan.json</code>, or write code. The human must start the next phase with a\nseparate request.</p>\n<p>If planning reveals design flaws, loop back to research. See <strong>atelier-orchestrator</strong>\nfor iteration patterns.</p>\n","files":[{"path":"SKILL.md","sizeBytes":15217,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-11T20:11:35.41177Z","sha256":"691DB39309022A1844FA4F501C81C46AD2F8A2C556886C63B0F85BB7DD72B605","sizeBytes":6430},"review":null,"source":{"repositoryUrl":"https://github.com/martinffx/atelier","path":"skills/spec-brainstorm","license":"MIT","commit":"85bd2d55297e025dd36dc9c094c79a16ec2501ff","subtreeSha":"84D0957B4155E15EF6E2B6414BBF09DB859A67D135A5C191D3032F54F773A3BA","lastSyncedAt":"2026-11-14T00:39:00.182306Z"},"reviewedAt":"2026-10-11T20:16:21.375365Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/martinffx/atelier/tree/main/skills/spec-brainstorm"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install martinffx-atelier@llmmart"},{"target":"git","command":"git clone https://github.com/martinffx/atelier.git"}]}