{"id":"f9300974-2eaa-4c26-9e5d-252a5ec6cdac","shortId":"CCKuh9","kind":"skill","title":"spec-brainstorm","tagline":"Conversational design workshop for new features. Interviews the human one question at a time, explores 2-3 approaches with trade-offs, then produces a focused spec. Combines requirements discovery with codebase research and architecture design. Use when the user says \"create a sp","description":"# Spec Brainstorm\n\nConversational design workshop that produces a focused, reviewed spec.\n\nOne question at a time. Multiple approaches explored. Ruthless scope control.\nNo implementation until design is approved.\n\n## Artifact\n\n```\ndocs/specs/YYYY-MM-DD-<topic>-design.md  ← This skill's output\n```\n\nRequirements are inline — no separate requirements.json needed.\n\n---\n\n## Lessons\n\nThese principles apply to every spec, every time.\n\n### \"Too simple for a design\" is an anti-pattern\n\nEvery project goes through this process. No exceptions. The five-minute conversation\noften reveals assumptions that would cost hours in implementation. If it's truly trivial,\nthe spec will be short — but it still gets written.\n\n### Design for isolation and clarity\n\nBreak 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.\n\n### Working in existing codebases\n\nExplore the current structure first. Follow existing patterns. Targeted improvements only.\nNo unrelated refactoring. Understand why things are the way they are before proposing\nchanges.\n\n### Decomposition\n\nIf the request describes multiple independent subsystems, flag it immediately. Decompose\ninto sub-projects before diving into details. Each sub-project gets its own spec and its\nown plan. A spec that tries to cover three subsystems helps no one.\n\n### YAGNI ruthlessly\n\nRemove 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.\n\n---\n\n## Step 1: Orient\n\nBefore diving in, understand where you are.\n\n1. **Read project context** — AGENTS.md, README, existing architecture docs\n2. **Check existing specs** — Scan `docs/specs/` for previous work. What domain model\n   exists? What patterns are established? What has been built before?\n3. **Read recent specs** — What was the last thing built? Is this feature building\n   on existing work, extending it, or something greenfield?\n\nThis is silent — don't narrate it. Let the context inform where you focus.\n\n---\n\n## Step 2: Discovery\n\nAsk questions to understand what to build. Skip this step if requirements are already\nclear from context (existing specs, human provided details, etc.).\n\n### Interview style\n\nAsk **one question at a time**. Multiple choice preferred when possible — give 2-4\nconcrete options rather than open-ended prompts. Keep the conversation moving.\n\n**Good:** \"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.\"\n\n**Bad:** \"How should the data synchronization work?\"\n\n### When to skip discovery\n\n- Human provides clear, detailed requirements\n- Feature extends existing work with well-defined scope\n- Human says \"spec out X\" and X is specific enough\n\n### Decomposition check\n\nBefore 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\"):\n\n1. **Flag it immediately:** \"This looks like multiple independent projects. Let me\n   propose a decomposition.\"\n2. **Break it down:** Identify the subsystems and their dependencies.\n3. **Get agreement:** \"Which of these should we spec first?\"\n\nDo not try to spec everything in one document.\n\n### YAGNI check\n\nDuring discovery, push back on scope:\n\n- \"Do you need this in the first version, or is it a nice-to-have?\"\n- \"Can we ship without this and add it later if needed?\"\n- \"This feature adds significant complexity — is the use case real or hypothetical?\"\n\nIf the human insists, include it — but flag the trade-off in the spec.\n\n### Discovery questions\n\nAdapt these to context. Not all are needed every time.\n\n1. **What problem are we solving?** — Concrete problem statement, not solution description\n2. **Who has this problem?** — User roles\n3. **How do they solve it today?** — Current workflow and pain points\n4. **What does success look like?** — Measurable outcomes\n5. **What does this integrate with?** — Existing systems, APIs\n6. **What constraints exist?** — Technical, business, regulatory\n\nIf you already know answers from orientation, confirm rather than ask.\n\n**Tell the human:** \"Based on my research, here's my understanding of what we're building.\nDoes this look right?\"\n\n**STOP. Wait for human confirmation.**\n\n---\n\n## Step 3: Research\n\nRead the relevant codebase deeply. Not signatures — implementations, edge cases, error\nhandling, data flows. Trace callers and callees. Read tests to understand expected\nbehaviour.\n\nWrite findings directly into the spec as the foundation.\n\n**Tell the human:** \"I've written the research section of the spec. Ready for you to\nreview before I continue with the design.\"\n\n**STOP. Wait for human review.**\n\n---\n\n## Step 4: Design — Explore Approaches\n\nBefore settling on a design, present **2-3 approaches** with trade-offs.\n\n### Approach exploration\n\nFor each approach, address:\n\n1. **What it looks like** — Brief architecture sketch\n2. **Pros** — What makes this approach good\n3. **Cons** — What's painful, expensive, or risky\n4. **Complexity estimate** — Rough sense of implementation effort\n\nThen make a recommendation and explain why.\n\n**Example:**\n\n> **Approach A: Single table with JSON columns**\n> - Simple schema, fast to implement\n> - Querying inside JSON is limited, migration pain later\n> - Complexity: Low\n>\n> **Approach B: Normalized relational tables**\n> - Clean queries, easy to evolve schema\n> - More joins, more migration files, more code\n> - Complexity: Medium\n>\n> **Recommendation:** Approach B — the query flexibility matters more here than\n> implementation speed.\n\n### Design approval gate\n\nGet explicit approval on the chosen approach before writing the full spec.\n\n**Tell the human:** \"Which approach should we go with? Or should I explore a different\ndirection?\"\n\n**STOP. Wait for human to choose an approach.**\n\n### Write the spec\n\nOnce an approach is chosen, write the full spec document.\n\nUse the Skill tool to invoke **oracle-architect** for component design, domain modeling,\nand layer boundaries.\n\n### What the spec should contain\n\n```markdown\n# 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```\n\nScale each section to complexity — a few sentences if straightforward, detailed if\nnuanced.\n\n### Reference implementations\n\nIf human provides reference code — from open source, from elsewhere in codebase — use it\nas a concrete guide. Working from a reference produces dramatically better designs.\n\n---\n\n## Step 5: Self-Review\n\nBefore presenting the spec to the human, run this checklist silently:\n\n### 1. Placeholder scan\n\nAre there any TBD, TODO, FIXME, or incomplete sections? Every section should have real\ncontent or be removed.\n\n### 2. Internal consistency\n\nDo sections contradict each other? If the Architecture section says \"stateless\" but the\nData Model includes session state, resolve the conflict before presenting.\n\n### 3. Scope check\n\nIs this focused enough for a single implementation plan? If the spec covers more than\none independent subsystem, it should have been decomposed in Step 2. If it's still too\nbroad, flag it now.\n\n### 4. Ambiguity check\n\nCould any requirement be interpreted two ways? If so, pick one interpretation, state it\nexplicitly, and let the human correct you.\n\nFix any issues found. Then present.\n\n**Tell the human:** \"The spec is complete. Ready for your review.\"\n\n**STOP. Wait for human review.**\n\n---\n\n## Step 6: Annotation\n\nHuman may annotate the spec directly — adding corrections, rejections, domain knowledge,\nor \"remove this section entirely.\"\n\nWhen they say \"I added notes\":\n\n1. Re-read the full document\n2. Address every note\n3. Update the spec\n4. Run the self-review checklist again (Step 5)\n5. **Do not move to planning**\n\nThis may repeat 1-6 times. Spec is not approved until human explicitly says so.\n\n---\n\n## Handoff\n\nWhen the spec is approved, the next step is **spec-plan**.\n\n> \"Spec is approved. Ready to write the implementation plan?\"\n\nIf planning reveals design flaws, loop back to research. See **spec-orchestrator**\nfor iteration patterns.\n\nDo not start planning without explicit approval. Do not write code.","tags":["spec","brainstorm","atelier","martinffx","agent-skills","agentic-coding","anthropic","claude-code","claude-skills","code-review","codex","codex-skill"],"capabilities":["skill","source-martinffx","skill-spec-brainstorm","topic-agent-skills","topic-agentic-coding","topic-anthropic","topic-claude-code","topic-claude-skills","topic-code-review","topic-codex","topic-codex-skill","topic-opencode","topic-prompt-engineering","topic-sdd","topic-spec-driven-development"],"categories":["atelier"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/martinffx/atelier/spec-brainstorm","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add martinffx/atelier","source_repo":"https://github.com/martinffx/atelier","install_from":"skills.sh"}},"qualityScore":"0.461","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 23 github stars · SKILL.md body (9,397 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:05:24.127Z","embedding":null,"createdAt":"2026-05-18T07:04:59.318Z","updatedAt":"2026-05-18T19:05:24.127Z","lastSeenAt":"2026-05-18T19:05:24.127Z","tsv":"'-1':1030 '-3':20,820 '-4':428 '-6':1381 '1':311,320,535,653,832,1190,1346,1380 '2':19,329,388,427,550,665,819,840,1211,1265,1353 '3':351,560,672,745,847,1237,1357 '30s':462 '4':684,809,855,1275,1361 '5':692,1175,1370,1371 '6':701,1322 'access':1111 'action':1036 'ad':1330,1344 'adapt':643 'add':609,616 'address':831,1354 'admin':533 'agents.md':324 'aggreg':1088 'agreement':562 'alreadi':403,710 'altern':1118 'ambigu':1276 'annot':1323,1326 'answer':712 'anti':107 'anti-pattern':106 'anyth':1128 'api':700,1096 'appli':93 'approach':21,65,812,821,826,830,845,871,893,914,934,944,963,969,1103,1122 'approv':75,926,930,1386,1397,1407,1436 'architect':985 'architectur':38,327,838,1076,1221 'artifact':76 'ask':390,415,509,718 'assess':513 'assumpt':124,1073 'b':458,894,915 'back':304,584,1420 'bad':471 'base':722 'batch':450 'batch-process':449 'behaviour':770 'benefit':1039 'better':1172 'boundari':993 'brainstorm':3,49 'break':151,551 'brief':837 'broad':1271 'build':295,364,396,523,734 'built':349,360 'busi':706,1051,1090 'c':463 'calle':764 'caller':762 'capabl':273,1021 'case':622,756 'chang':219 'check':330,507,580,1239,1277 'checklist':1188,1367 'choic':422 'choos':961 'chosen':933,971 'clariti':150 'clean':898 'clear':158,404,484 'code':910,1152,1440 'codebas':35,194,750,1159 'column':877 'combin':31 'complet':1311 'complex':618,856,891,911,1137 'compon':987,1077 'con':848 'concret':429,659,1164 'confirm':715,743 'conflict':1234 'consid':1119 'consist':1213 'constraint':703,1048,1052 'contain':998 'content':1207 'context':323,382,406,646,1053 'continu':799 'contract':1100,1105 'contradict':1216 'control':69 'convent':1067 'convers':4,50,121,439 'core':1080 'correct':1297,1331 'cost':127,293 'could':1278 'cover':257,1252 'creat':45 'creep':307 'current':197,679 'dashboard':534 'data':475,759,1107,1227 'debt':1075 'decompos':231,1262 'decomposit':220,506,549 'deepli':751 'defer':1026 'defin':163,494 'demand':466 'depend':559,1068 'describ':224,518 'descript':664 'design':5,39,51,73,103,146,270,802,810,817,925,988,1097,1110,1173,1417 'design.md':78 'detail':239,411,485,511,1143 'differ':954 'direct':773,955,1329 'discoveri':33,309,389,481,582,641 'dive':237,314 'doc':328 'docs/specs':334 'docs/specs/yyyy-mm-dd-':77 'document':578,976,1352 'doesn':283 'domain':339,989,1083,1333 'dramat':1171 'e.g':522 'easi':900 'edg':755,1082 'effect':1081 'effort':862 'elsewher':1157 'email':528 'end':435,1061,1063 'end-to-end':1060 'endpoint':1098 'enough':505,1243 'entir':1339 'entiti':1085 'error':757,1101 'establish':345 'estim':857 'etc':412 'event':1104 'everi':95,97,109,289,461,651,1202,1355 'everyth':575 'evolv':902 'exampl':870 'except':116 'exist':193,201,326,331,341,366,407,489,698,704,1055,1064 'expect':769 'expens':852 'explain':178,868 'explicit':929,1025,1292,1389,1435 'explor':18,66,195,811,827,952 'extend':368,488 'fast':880 'featur':9,267,290,363,487,615,1000 'file':908 'find':772 'first':199,279,569,593 'five':119 'five-minut':118 'fix':1299 'fixm':1198 'flag':228,536,633,1272 'flaw':1418 'flexibl':918 'flow':760 'focus':29,56,386,1242 'follow':200 'found':1302 'foundat':779 'full':938,974,1351 'function':1079 'gate':927 'get':144,244,561,928 'give':426 'given':1040 'go':285,947 'goe':111 'good':441,846 'gotcha':1072 'greenfield':372 'guid':1165 'handl':758,1102 'handoff':1392 'help':260 'hour':128 'human':12,409,482,496,628,721,742,782,806,942,959,1131,1149,1185,1296,1307,1319,1324,1388 'hypothet':625 'identifi':554 'immedi':230,538 'implement':71,130,754,861,882,923,1147,1247,1412 'improv':204 'includ':630,1229 'incomplet':1200 'independ':169,172,226,520,543,1256 'inform':383 'inlin':85 'input':1132 'insid':884 'insist':629 'integr':696,1070 'interfac':164 'intern':1212 'interpret':1282,1289 'interview':10,413 'invok':982 'io':1094 'isn':274 'isol':148 'issu':1301 'iter':1428 'job':182 'join':905 'json':876,885 'keep':437 'know':711 'knowledg':1334 'known':1124 'last':358 'later':302,611,890 'layer':992 'lesson':90 'let':380,545,1294 'like':541,689,836 'limit':887,1125 'live':1092,1095 'logic':1091 'look':540,688,737,835 'loop':1419 'low':892 'maintain':299 'make':843,864 'markdown':999 'matter':919 'may':1325,1378 'measur':690 'medium':912 'migrat':888,907,1113 'minut':120 'model':340,990,1084,1108,1228 'move':440,1374 'much':190 'multipl':64,225,421,519,542 'must/should/could':1047 'name':1001 'narrat':378 'need':89,276,589,613,650,1114,1130 'new':8 'next':1399 'nice':600 'nice-to-hav':599 'normal':895 'note':1345,1356 'notif':525 'nuanc':1145 'object':1087 'off':25,825,1117 'often':122 'on-demand':464 'one':13,59,157,184,262,416,577,1255,1288 'open':434,1126,1154 'open-end':433 'option':430 'oracl':984 'oracle-architect':983 'orchestr':1426 'orient':312,714 'outcom':691 'output':82 'pain':682,851,889 'pattern':108,202,343,1065,1112,1429 'period':459 'pick':1287 'placehold':1191 'plan':251,1248,1376,1404,1413,1415,1433 'point':683,1071 'poll':460 'possibl':425 'prefer':423 'present':818,1180,1236,1304 'previous':336 'principl':92 'prioriti':1046 'problem':655,660,669,1002,1004,1011 'process':114,451 'produc':27,54,1170 'project':110,235,243,322,544 'prompt':436 'propos':218,547 'pros':841 'provid':410,483,1150 'published/consumed':1106 'purpos':159 'push':303,530,583 'queri':883,899,917 'question':14,60,391,417,512,642,1127 'rather':431,716 're':733,1348 're-read':1347 'read':321,352,747,765,1349 'readi':792,1312,1408 'readm':325 'real':446,454,623,1206 'real-tim':445,453 'recent':353 'recommend':866,913 'refactor':208 'refer':1146,1151,1169 'regulatori':707 'reject':1332 'relat':896 'relev':749 'remov':265,1210,1336 'repeat':1379 'request':223,469,517 'request/response':1099 'requir':32,83,401,486,1280 'requirements.json':88 'research':36,725,746,787,1422 'resolv':1232 'reveal':123,1416 'review':57,796,807,1178,1315,1320,1366 'right':738 'riski':854 'role':671,1033 'rough':858 'run':1186,1362 'ruthless':67,264 'say':44,497,1223,1342,1390 'scale':1133 'scan':333,1192 'schema':879,903,1109 'scope':68,306,495,514,586,1017,1019,1024,1238 'section':788,1135,1201,1203,1215,1222,1338 'see':1423 'self':1177,1365 'self-review':1176,1364 'sens':859 'sentenc':185,1140 'separ':87 'session':1230 'settl':814 'ship':605 'short':140 'signatur':753 'signific':617 'silent':375,1189 'simpl':100,878 'singl':873,1246 'sketch':839 'skill':80,979 'skill-spec-brainstorm' 'skip':397,480 'sms':529 'solut':663 'solv':658,676,1007,1014 'someth':371 'sourc':1155 'source-martinffx' 'sp':47 'spec':2,30,48,58,96,137,247,253,288,332,354,408,498,568,574,640,776,791,939,966,975,996,1182,1251,1309,1328,1360,1383,1395,1403,1405,1425 'spec-brainstorm':1 'spec-orchestr':1424 'spec-plan':1402 'specif':504,1020 'speed':924 'start':1432 'state':1231,1290 'stateless':1224 'statement':661 'step':310,387,399,744,808,1174,1264,1321,1369,1400 'still':143,1269 'stop':739,803,956,1316 'stori':281,1028 'straightforward':1142 'structur':198,1078 'style':414 'sub':234,242 'sub-project':233,241 'subsystem':227,259,521,556,1257 'success':687 'synchron':476 'system':153,526,699 'tabl':874,897 'target':203 'tbd':1196 'technic':705,1049,1074 'tell':719,780,940,1305 'test':297,766 'testabl':173 'thing':211,359 'three':258 'time':17,63,98,420,447,455,652,1382 'today':678,1016,1056 'todo':1197 'tool':980 'topic-agent-skills' 'topic-agentic-coding' 'topic-anthropic' 'topic-claude-code' 'topic-claude-skills' 'topic-code-review' 'topic-codex' 'topic-codex-skill' 'topic-opencode' 'topic-prompt-engineering' 'topic-sdd' 'topic-spec-driven-development' 'trace':761 'trade':24,636,824,1116 'trade-off':23,635,823,1115 'tri':255,572 'trivial':135 'truli':134 'two':1283 'understand':170,209,301,316,393,729,768 'unit':155,168,180 'unnecessari':266 'unrel':207 'unresolv':1129 'updat':1358 'us':1029 'use':40,621,977,1160 'user':43,280,468,670,1027 'valu':1086 've':784 'version':594 'via':456 'wait':740,804,957,1317 'want':1035 'way':214,1284 'websocket':457 'well':162,493 'well-defin':161,492 'win':1123 'without':606,1434 'work':191,337,367,477,490,1059,1166 'workflow':680 'workshop':6,52 'would':126 'write':771,936,964,972,1410,1439 'written':145,785 'x':500,502,1041 'y':1043 'yagni':263,579 'z':1045","prices":[{"id":"e548cf3b-15ac-48a7-8c8c-d00aee8f55be","listingId":"f9300974-2eaa-4c26-9e5d-252a5ec6cdac","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"martinffx","category":"atelier","install_from":"skills.sh"},"createdAt":"2026-05-18T07:04:59.318Z"}],"sources":[{"listingId":"f9300974-2eaa-4c26-9e5d-252a5ec6cdac","source":"github","sourceId":"martinffx/atelier/spec-brainstorm","sourceUrl":"https://github.com/martinffx/atelier/tree/main/skills/spec-brainstorm","isPrimary":false,"firstSeenAt":"2026-05-18T07:04:59.318Z","lastSeenAt":"2026-05-18T19:05:24.127Z"}],"details":{"listingId":"f9300974-2eaa-4c26-9e5d-252a5ec6cdac","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"martinffx","slug":"spec-brainstorm","github":{"repo":"martinffx/atelier","stars":23,"topics":["agent-skills","agentic-coding","anthropic","claude-code","claude-skills","code-review","codex","codex-skill","opencode","prompt-engineering","sdd","spec-driven-development"],"license":"mit","html_url":"https://github.com/martinffx/atelier","pushed_at":"2026-05-18T06:56:45Z","description":"An atelier for Opencode, Claude Code, and other coding agents: spec-driven workflows, deep thinking, and code quality.","skill_md_sha":"d7eea785653abe71b27ca17d454bafca7bc0e850","skill_md_path":"skills/spec-brainstorm/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/martinffx/atelier/tree/main/skills/spec-brainstorm"},"layout":"multi","source":"github","category":"atelier","frontmatter":{"name":"spec-brainstorm","description":"Conversational design workshop for new features. Interviews the human one question at a time, explores 2-3 approaches with trade-offs, then produces a focused spec. Combines requirements discovery with codebase research and architecture design. Use when the user says \"create a spec\", \"design this feature\", \"let's brainstorm\", \"what should we build\", or at the start of any feature/refactor/complex-bug workflow."},"skills_sh_url":"https://skills.sh/martinffx/atelier/spec-brainstorm"},"updatedAt":"2026-05-18T19:05:24.127Z"}}