{"id":"dc455f9b-f6db-4f47-b0a9-cf532a775d97","shortId":"kceDu3","kind":"skill","title":"spec-research","tagline":"Discovery, research, and architecture for new features. Produces spec.md — a living specification that covers what exists, what we're building, and how it fits together. Combines requirements discovery with codebase research and design. Use when the user says \"create a spec\", \"wh","description":"# Spec Research\n\nDiscovery + Research + Architecture = spec.md\n\nOne skill to understand what to build, what exists, and how to build it. Get approval.\nThen move to planning.\n\n## Artifact\n\n```\ndocs/specs/YYYY-MM-DD-<feature-name>/\n└── spec.md  ← This skill's output\n```\n\nRequirements are inline in spec.md — no separate requirements.json needed.\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 new 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 your research.\n\n---\n\n## Step 2: Discovery (if needed)\n\nAsk questions to understand what to build. Skip this step if requirements are already clear\nfrom context (existing specs, human provided details, etc.).\n\n### When to do discovery\n\n- Problem space is unclear\n- New feature with new users/workflows\n- Human says \"what should we build\", \"let's figure out requirements\"\n\n### When to skip\n\n- Human provides clear requirements\n- Feature extends existing work with clear scope\n- \"I want to spec out X\" — already has context\n\n### Questions (if needed)\n\nAsk one at a time. Don't overwhelm with a wall of questions.\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 behaviour.\n\nWrite findings directly into spec.md as the foundation.\n\n**Tell the human:** \"I've written the research section of spec.md. Ready for you to review\nbefore I continue with the design.\"\n\n**STOP. Wait for human review.**\n\n---\n\n## Step 4: Design\n\nOnce research is approved, build spec.md with architecture and design decisions.\n\nUse the Skill tool to invoke **oracle-architect** for component design, domain modeling,\nand layer boundaries.\n\n### What spec.md 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 nuanced.\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**Tell the human:** \"spec.md is complete. Ready for your review.\"\n\n**STOP. Wait for human review.**\n\n---\n\n## Step 5: Annotation\n\nHuman may annotate spec.md 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. **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 spec.md 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","research","atelier","martinffx","agent-skills","agentic-coding","anthropic","claude-code","claude-skills","code-review","codex","codex-skill"],"capabilities":["skill","source-martinffx","skill-spec-research","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-research","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 (4,931 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-18T01:04:24.758Z","embedding":null,"createdAt":"2026-05-10T07:03:13.151Z","updatedAt":"2026-05-18T01:04:24.758Z","lastSeenAt":"2026-05-18T01:04:24.758Z","tsv":"'-1':478 '-6':686 '1':89,98,259,661,685 '2':107,169,271,668 '3':129,278,351,672 '4':290,413,676 '5':298,638 '6':307 'access':559 'action':484 'ad':645,659 'address':669 'agents.md':102 'aggreg':536 'alreadi':186,240,316 'altern':566 'annot':639,642 'answer':318 'anyth':576 'api':306,544 'approach':551,570 'approv':67,418,691,701,711,740 'architect':434 'architectur':7,50,105,422,524 'artifact':72 'ask':173,246,324 'assumpt':521 'back':724 'base':328 'behaviour':376 'benefit':487 'better':620 'boundari':442 'build':23,58,64,143,179,214,340,419 'built':127,138 'busi':312,499,538 'calle':370 'caller':368 'capabl':469 'case':362 'check':108 'clear':187,225,232 'code':600,744 'codebas':33,356,607 'combin':29 'complet':627 'complex':585 'compon':436,525 'concret':265,612 'confirm':321,349 'consid':567 'constraint':309,496,500 'contain':446 'context':101,161,189,242,501 'continu':403 'contract':548,553 'convent':515 'core':528 'correct':646 'cover':17 'creat':42 'current':285 'data':365,555 'debt':523 'decis':425 'deepli':357 'defer':474 'depend':516 'descript':270 'design':36,406,414,424,437,545,558,621,721 'detail':194,591 'direct':379,644 'discoveri':4,31,48,170,199 'dive':92 'doc':106 'docs/specs':112 'docs/specs/yyyy-mm-dd-':73 'document':667 'domain':117,438,531,648 'dramat':619 'edg':361,530 'effect':529 'elsewher':605 'end':509,511 'end-to-end':508 'endpoint':546 'entir':654 'entiti':533 'error':363,549 'establish':123 'etc':195 'event':552 'everi':670 'exist':19,60,104,109,119,145,190,229,304,310,503,512 'expect':375 'explicit':473,694,739 'extend':147,228 'featur':10,142,205,227,448 'figur':217 'find':378 'fit':27 'flaw':722 'flow':366 'focus':165 'foundat':384 'full':666 'function':527 'get':66 'given':488 'gotcha':520 'greenfield':151 'guid':613 'handl':364,550 'handoff':697 'human':192,209,223,327,348,387,410,579,597,624,635,640,693 'implement':360,595,716 'inform':162 'inlin':81 'input':580 'integr':302,518 'invok':431 'io':542 'iter':732 'know':317 'knowledg':649 'known':572 'last':136 'layer':441 'let':159,215 'like':295 'limit':573 'live':14,540,543 'logic':539 'look':294,343 'loop':723 'markdown':447 'may':641,683 'measur':296 'migrat':561 'model':118,439,532,556 'move':69,679 'must/should/could':495 'name':449 'narrat':157 'need':87,172,245,562,578 'new':9,141,204,207 'next':703 'note':660,671 'nuanc':593 'object':535 'off':565 'one':52,247 'open':574,602 'oracl':433 'oracle-architect':432 'orchestr':730 'orient':90,320 'outcom':297 'output':78 'overwhelm':253 'pain':288 'pattern':121,513,560,733 'plan':71,681,708,717,719,737 'point':289,519 'previous':114 'prioriti':494 'problem':200,261,266,275,450,452,459 'produc':11,618 'project':100 'provid':193,224,598 'published/consumed':554 'question':174,243,258,575 'rather':322 're':22,339,663 're-read':662 'read':99,130,353,371,664 'readi':396,628,712 'readm':103 'recent':131 'refer':594,599,617 'regulatori':313 'reject':647 'relev':355 'remov':651 'repeat':684 'request/response':547 'requir':30,79,184,219,226 'requirements.json':86 'research':3,5,34,47,49,167,331,352,392,416,726 'reveal':720 'review':400,411,631,636 'right':344 'role':277,481 'say':41,210,657,695 'scale':581 'scan':111 'schema':557 'scope':233,465,467,472 'section':393,583,653 'see':727 'sentenc':588 'separ':85 'signatur':359 'silent':154 'skill':53,76,428 'skill-spec-research' 'skip':180,222 'solut':269 'solv':264,282,455,462 'someth':150 'sourc':603 'source-martinffx' 'space':201 'spec':2,44,46,110,132,191,237,675,688,707,709,729 'spec-orchestr':728 'spec-plan':706 'spec-research':1 'spec.md':12,51,74,83,381,395,420,444,625,643,699 'specif':15,468 'start':736 'statement':267 'step':88,168,182,350,412,637,704 'stop':345,407,632 'stori':476 'straightforward':590 'structur':526 'success':293 'system':305 'technic':311,497,522 'tell':325,385,622 'test':372 'thing':137 'time':250,687 'today':284,464,504 'togeth':28 'tool':429 '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':367 'trade':564 'trade-off':563 'unclear':203 'understand':55,94,176,335,374 'unresolv':577 'updat':673 'us':477 'use':37,426,608 'user':40,276,475 'users/workflows':208 'valu':534 've':389 'wait':346,408,633 'wall':256 'want':235,483 'wh':45 'win':571 'without':738 'work':115,146,230,507,614 'workflow':286 'write':377,714,743 'written':390 'x':239,489 'y':491 'z':493","prices":[{"id":"9d65d48b-1839-4aab-aa80-1760b2182511","listingId":"dc455f9b-f6db-4f47-b0a9-cf532a775d97","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-10T07:03:13.151Z"}],"sources":[{"listingId":"dc455f9b-f6db-4f47-b0a9-cf532a775d97","source":"github","sourceId":"martinffx/atelier/spec-research","sourceUrl":"https://github.com/martinffx/atelier/tree/main/skills/spec-research","isPrimary":false,"firstSeenAt":"2026-05-10T07:03:13.151Z","lastSeenAt":"2026-05-18T01:04:24.758Z"}],"details":{"listingId":"dc455f9b-f6db-4f47-b0a9-cf532a775d97","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"martinffx","slug":"spec-research","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-15T06:51:36Z","description":"An atelier for Opencode, Claude Code, and other coding agents: spec-driven workflows, deep thinking, and code quality.","skill_md_sha":"c4bc021b5bb7f154dd0bf65626595ed6f2812554","skill_md_path":"skills/spec-research/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/martinffx/atelier/tree/main/skills/spec-research"},"layout":"multi","source":"github","category":"atelier","frontmatter":{"name":"spec-research","description":"Discovery, research, and architecture for new features. Produces spec.md — a living specification that covers what exists, what we're building, and how it fits together. Combines requirements discovery with codebase research and design. Use when the user says \"create a spec\", \"what should we build\", \"design this feature\", or at the start of any feature/refactor/complex-bug workflow."},"skills_sh_url":"https://skills.sh/martinffx/atelier/spec-research"},"updatedAt":"2026-05-18T01:04:24.758Z"}}