{"id":"df186210-d83d-4f72-afaa-823f7e623b2f","shortId":"4rkZNj","kind":"skill","title":"pm-spec-writing","tagline":"Translate ideas, feature requests, or vague concepts into specific, actionable dev briefs. Use this skill whenever the user has an idea they want to build, a feature to spec out, a bug to file, a project to scope, or needs to convert a half-formed idea into a clear implementation","description":"# PM Spec Writing\n\nTake an idea (often vague) and turn it into a specification a developer or AI agent can actually build from. Stack-agnostic. Works for new features, bug fixes, content changes, or infrastructure work.\n\n---\n\n## When to use\n\n- Translating an idea into a buildable feature spec\n- Writing a PRD or product requirement document\n- Filing a bug report that someone else can act on\n- Scoping a project before kickoff\n- Prioritizing a backlog of feature requests\n- Writing acceptance criteria for an existing feature\n- Breaking a large initiative into shippable increments\n\n## When NOT to use\n\n- Quarterly or annual planning across multiple initiatives (use `roadmap-planning`)\n- Code review or debugging existing code (use `code-review-web`)\n- Design decisions for a feature already specced (use `design-standards`)\n- User research to validate an idea (use `ux-research`)\n\n---\n\n## Required inputs\n\n- The idea, request, or problem being addressed\n- The audience or user affected\n- Any existing constraints (stack, deadlines, dependencies)\n- The success metric (how will you know it worked?)\n\nIf the idea is vague, the workflow's first step is clarification. Do not write specs around vagueness.\n\n---\n\n## The framework: 4 phases\n\nEvery PM workflow follows the same arc. The phases are universal even if the specific outputs vary.\n\n### Phase 1: Clarify the idea\n\nBefore any spec, answer four questions. If any answer is \"I don't know,\" go back to the user.\n\n1. **What user problem does this solve?** Not \"what does it do.\" The problem comes first; the feature is the proposed solution.\n2. **Who specifically benefits?** Be precise. \"Users\" is not specific. \"First-time visitors who don't convert\" is.\n3. **What is the success metric?** How will you know it worked? Pick one primary metric.\n4. **Why now?** What changed that makes this the right time to build it? If \"nothing changed,\" it might not be the right time.\n\n### Phase 2: Scope by impact and effort\n\nPlot every candidate idea on the impact/effort grid:\n\n```\nHIGH IMPACT / LOW EFFORT       Ship immediately\n  Examples: copy fixes, contrast fixes, meta tags,\n            broken links, missing alt text, redirects\n\nHIGH IMPACT / HIGH EFFORT      Plan and batch\n  Examples: new page type, new feature, schema overhaul,\n            major redesign, new integration\n\nLOW IMPACT / LOW EFFORT        Nice-to-have batch\n  Examples: tooltip improvements, minor copy polish,\n            cosmetic UX touches\n\nLOW IMPACT / HIGH EFFORT       Skip or defer indefinitely\n  Examples: rebuilding what already works, exotic\n            edge case features, premature optimization\n```\n\nThis is not a perfect framework. Some \"low impact\" things are mandatory (compliance, accessibility, security). Note exceptions.\n\n### Phase 3: Write the spec\n\nThree formats based on the type of work.\n\n#### Format A: Feature spec (for new features)\n\n```\nTITLE: [Specific, action-oriented]\n\nPROBLEM\n[1-2 sentences. The user problem and current state.]\n\nUSERS\n[Who specifically benefits. Be precise about the user segment.]\n\nPROPOSAL\n[1 paragraph. The proposed solution. Stay at the conceptual level.]\n\nUSER STORIES\n- As a [user type], I want to [action], so that [outcome]\n- As a [user type], I want to [action], so that [outcome]\n\nACCEPTANCE CRITERIA\n- Given [context], when [action], then [expected outcome]\n- Given [context], when [action], then [expected outcome]\n\nOUT OF SCOPE\n[What this spec explicitly does NOT cover. Important for scope control.]\n\nDEPENDENCIES\n[Other systems, APIs, designs, content needed before this can ship.]\n\nSUCCESS METRIC\n[The one primary metric that tells us this worked. With current baseline if known.]\n\nESTIMATED EFFORT\n[Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (sprints)]\n\nPRIORITY\n[P0 launch blocker / P1 next sprint / P2 within quarter / P3 backlog]\n```\n\n#### Format B: Dev brief (for handing to a developer or AI agent)\n\nFor tactical, ready-to-build work. Lighter than a full spec.\n\n```\nCONTEXT: [1-2 sentences explaining why this matters]\n\nTASK: [Specific files, exact changes needed]\n\nCONSTRAINTS: [What must NOT change, what to preserve]\n\nVERIFY: [Exact steps to confirm the work is done correctly]\n```\n\nThe verify section is the most-skipped and most-important. Without it, \"done\" means whatever the implementer thinks done means.\n\n#### Format C: Bug report\n\n```\nURL or context: [Where it happens]\n\nSymptom: [What the user sees or experiences]\n\nExpected: [What should happen instead]\n\nSteps to reproduce:\n1. [Specific step]\n2. [Specific step]\n3. [Specific step]\n\nHypothesis: [Likely root cause if known]\n\nFiles to investigate: [Likely files involved if known]\n\nPriority:\n  P0 - blocking critical user flow, ship immediately\n  P1 - degrades UX significantly, fix this sprint\n  P2 - minor issue, fix when convenient\n  P3 - nice-to-have improvement\n\nBrowser/device: [If reproducibility might be browser-specific]\n```\n\n### Phase 4: Sequence and ship\n\nSpecs without sequencing become dust on a shelf.\n\nFor a single feature: identify the smallest shippable increment. What is the smallest version that delivers user value? Ship that first. Then iterate.\n\nFor a backlog: order by dependencies first, then by priority, then by impact/effort. The order matters more than the priority labels.\n\n---\n\n## Workflow\n\n1. **Clarify.** If the idea is vague, ask the four phase-1 questions before proceeding.\n2. **Scope.** Plot the work on the impact/effort grid.\n3. **Pick the right format.** Feature spec for new features, dev brief for tactical work, bug report for defects.\n4. **Write the spec.** Use the template format. Fill in every section. Empty sections are flags.\n5. **Define done.** Verify steps must be unambiguous. \"Test it\" is not a verify step.\n6. **Get buy-in.** Walk through the spec with whoever will build it before they start.\n7. **Sequence.** Identify the smallest shippable increment.\n\n---\n\n## Failure patterns\n\n- **Specs that describe solutions before problems.** Always start with the user problem. The solution is downstream.\n- **Specs without a success metric.** Without a metric, you cannot tell if the feature worked.\n- **Acceptance criteria that are not testable.** \"User experience is improved\" is not testable. \"User completes signup in under 60 seconds\" is.\n- **Specs that include the \"how\" instead of the \"what.\"** Implementation details belong in the dev brief, not the spec. The spec is the desired outcome.\n- **No \"out of scope\" section.** Without explicit boundaries, scope creeps.\n- **Bug reports without reproduction steps.** Cannot be acted on. Always include steps.\n- **Verify steps that are vague.** \"Make sure it works.\" Useless. Must be specific actions with observable outcomes.\n- **Skipping the smallest-shippable-increment exercise.** Leads to 6-month projects that should have been 2-week experiments.\n\n---\n\n## Output format\n\nOutput is one of three formats based on work type, all in markdown:\n\n- `spec-[feature-name].md` for feature specs\n- `brief-[task-name].md` for dev briefs\n- `bug-[summary].md` for bug reports\n\nFor larger initiatives, group related specs in a folder:\n```\nspecs/\n  initiative-name/\n    spec-feature-1.md\n    spec-feature-2.md\n    brief-task-1.md\n    README.md   (overview and sequencing)\n```\n\n---\n\n## Reference files\n\n- [`references/feature-spec-template.md`](references/feature-spec-template.md) - Full feature spec template.\n- [`references/dev-brief-template.md`](references/dev-brief-template.md) - Compact dev brief template for tactical work.\n- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Beyond impact/effort: RICE, weighted scoring, MoSCoW.","tags":["spec","writing","claude","skills","rampstackco","agent-skills","anthropic","awesome-claude-code","awesome-claude-prompts","awesome-claude-skills","claude-code","claude-skills"],"capabilities":["skill","source-rampstackco","skill-pm-spec-writing","topic-agent-skills","topic-anthropic","topic-awesome-claude-code","topic-awesome-claude-prompts","topic-awesome-claude-skills","topic-claude","topic-claude-code","topic-claude-skills","topic-good-first-issue","topic-mcp","topic-product-management","topic-seo"],"categories":["claude-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/rampstackco/claude-skills/pm-spec-writing","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add rampstackco/claude-skills","source_repo":"https://github.com/rampstackco/claude-skills","install_from":"skills.sh"}},"qualityScore":"0.540","qualityRationale":"deterministic score 0.54 from registry signals: · indexed on github topic:agent-skills · 181 github stars · SKILL.md body (7,633 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-18T18:55:18.758Z","embedding":null,"createdAt":"2026-04-30T01:01:29.500Z","updatedAt":"2026-05-18T18:55:18.758Z","lastSeenAt":"2026-05-18T18:55:18.758Z","tsv":"'-1':866 '-2':500,620,662 '-3':616 '1':262,285,499,519,615,619,661,739,855 '2':307,367,742,870,1087 '3':326,474,745,879 '4':242,342,798,898 '5':914 '6':929,1080 '60':1004 '7':946 'accept':133,553,986 'access':469 'across':154 'act':119,1049 'action':14,496,538,549,558,565,1067 'action-ori':495 'actual':76 'address':201 'affect':206 'agent':74,647 'agnost':81 'ai':73,646 'alreadi':177,448 'alt':397 'alway':961,1051 'annual':152 'answer':269,274 'api':586 'arc':250 'around':238 'ask':862 'audienc':203 'b':637 'back':281 'backlog':128,635,835 'base':480,1098 'baselin':607 'batch':406,427 'becom':805 'belong':1018 'benefit':310,511 'beyond':1166 'block':764 'blocker':627 'boundari':1039 'break':139 'brief':16,639,890,1022,1113,1120,1159 'brief-task-1.md':1142 'broken':394 'browser':795 'browser-specif':794 'browser/device':789 'bug':36,86,113,716,894,1042,1121,1125 'build':29,77,354,653,941 'buildabl':101 'buy':932 'buy-in':931 'c':715 'candid':375 'cannot':980,1047 'case':452 'caus':751 'chang':89,346,358,672,678 'clarif':233 'clarifi':263,856 'clear':54 'code':161,166,169 'code-review-web':168 'come':299 'compact':1157 'complet':1000 'complianc':468 'concept':11 'conceptu':527 'confirm':686 'constraint':209,674 'content':88,588 'context':556,563,660,720 'contrast':390 'control':582 'conveni':782 'convert':46,324 'copi':388,432 'correct':691 'cosmet':434 'cover':578 'creep':1041 'criteria':134,554,987 'critic':765 'current':506,606 'day':617 'deadlin':211 'debug':164 'decis':173 'defect':897 'defer':443 'defin':915 'degrad':771 'deliv':825 'depend':212,583,838 'describ':957 'design':172,181,587 'design-standard':180 'desir':1030 'detail':1017 'dev':15,638,889,1021,1119,1158 'develop':71,644 'document':110 'done':690,706,712,916 'downstream':970 'dust':806 'edg':451 'effort':372,384,403,422,440,611 'els':117 'empti':910 'estim':610 'even':255 'everi':244,374,908 'exact':671,683 'exampl':387,407,428,445 'except':472 'exercis':1077 'exist':137,165,208 'exot':450 'expect':560,567,731 'experi':730,993,1089 'explain':664 'explicit':575,1038 'failur':953 'featur':7,31,85,102,130,138,176,302,412,453,488,492,813,884,888,984,1107,1111,1152 'feature-nam':1106 'file':38,111,670,754,758,1148 'fill':906 'first':230,300,318,830,839 'first-tim':317 'fix':87,389,391,774,780 'flag':913 'flow':767 'folder':1135 'follow':247 'form':50 'format':479,486,636,714,883,905,1091,1097 'four':270,864 'framework':241,461 'full':658,1151 'get':930 'given':555,562 'go':280 'grid':380,878 'group':1130 'half':49 'half-form':48 'hand':641 'happen':723,734 'high':381,400,402,439 'hour':613 'hypothesi':748 'idea':6,25,51,61,98,188,196,224,265,376,859 'identifi':814,948 'immedi':386,769 'impact':370,382,401,420,438,464 'impact/effort':379,845,877,1167 'implement':55,710,1016 'import':579,703 'improv':430,788,995 'includ':1009,1052 'increment':145,818,952,1076 'indefinit':444 'infrastructur':91 'initi':142,156,1129,1138 'initiative-nam':1137 'input':194 'instead':735,1012 'integr':418 'investig':756 'involv':759 'issu':779 'iter':832 'kickoff':125 'know':219,279,335 'known':609,753,761 'label':853 'larg':141,618 'larger':1128 'launch':626 'lead':1078 'level':528 'lighter':655 'like':749,757 'link':395 'low':383,419,421,437,463 'major':415 'make':348,1059 'mandatori':467 'markdown':1104 'matter':667,848 'md':1109,1117,1123 'mean':707,713 'medium':614 'meta':392 'metric':215,331,341,595,599,975,978 'might':360,792 'minor':431,778 'miss':396 'month':1081 'moscow':1171 'most-import':701 'most-skip':697 'multipl':155 'must':676,919,1064 'name':1108,1116,1139 'need':44,589,673 'new':84,408,411,417,491,887 'next':629 'nice':424,785 'nice-to-hav':423,784 'note':471 'noth':357 'observ':1069 'often':62 'one':339,597,1094 'optim':455 'order':836,847 'orient':497 'outcom':541,552,561,568,1031,1070 'output':259,1090,1092 'overhaul':414 'overview':1144 'p0':625,763 'p1':628,770 'p2':631,777 'p3':634,783 'page':409 'paragraph':520 'pattern':954 'perfect':460 'phase':243,252,261,366,473,797,865 'pick':338,880 'plan':153,160,404 'plot':373,872 'pm':2,56,245 'pm-spec-writ':1 'polish':433 'prd':106 'precis':312,513 'prematur':454 'preserv':681 'primari':340,598 'priorit':126 'prioriti':624,762,842,852 'problem':199,288,298,498,504,960,966 'proceed':869 'product':108 'project':40,123,1082 'propos':305,518,522 'quarter':150,633 'question':271,867 'readi':651 'readme.md':1143 'ready-to-build':650 'rebuild':446 'redesign':416 'redirect':399 'refer':1147 'references/dev-brief-template.md':1155,1156 'references/feature-spec-template.md':1149,1150 'references/prioritization-frameworks.md':1164,1165 'relat':1131 'report':114,717,895,1043,1126 'reproduc':738,791 'reproduct':1045 'request':8,131,197 'requir':109,193 'research':184,192 'review':162,170 'rice':1168 'right':351,364,882 'roadmap':159 'roadmap-plan':158 'root':750 'schema':413 'scope':42,121,368,571,581,871,1035,1040 'score':1170 'second':1005 'section':694,909,911,1036 'secur':470 'see':728 'segment':517 'sentenc':501,663 'sequenc':799,804,947,1146 'shelf':809 'ship':385,593,768,801,828 'shippabl':144,817,951,1075 'signific':773 'signup':1001 'singl':812 'skill':19 'skill-pm-spec-writing' 'skip':441,699,1071 'small':612 'smallest':816,822,950,1074 'smallest-shippable-incr':1073 'solut':306,523,958,968 'solv':291 'someon':116 'source-rampstackco' 'spec':3,33,57,103,237,268,477,489,574,659,802,885,901,937,955,971,1007,1025,1027,1105,1112,1132,1136,1153 'spec-feature-1.md':1140 'spec-feature-2.md':1141 'specc':178 'specif':13,69,258,309,316,494,510,669,740,743,746,796,1066 'sprint':623,630,776 'stack':80,210 'stack-agnost':79 'standard':182 'start':945,962 'state':507 'stay':524 'step':231,684,736,741,744,747,918,928,1046,1053,1055 'stori':530 'success':214,330,594,974 'summari':1122 'sure':1060 'symptom':724 'system':585 'tactic':649,892,1162 'tag':393 'take':59 'task':668,1115 'task-nam':1114 'tell':601,981 'templat':904,1154,1160 'test':922 'testabl':991,998 'text':398 'thing':465 'think':711 'three':478,1096 'time':319,352,365 'titl':493 'tooltip':429 'topic-agent-skills' 'topic-anthropic' 'topic-awesome-claude-code' 'topic-awesome-claude-prompts' 'topic-awesome-claude-skills' 'topic-claude' 'topic-claude-code' 'topic-claude-skills' 'topic-good-first-issue' 'topic-mcp' 'topic-product-management' 'topic-seo' 'touch':436 'translat':5,96 'turn':65 'type':410,483,534,545,1101 'unambigu':921 'univers':254 'url':718 'us':602 'use':17,95,149,157,167,179,189,902 'useless':1063 'user':22,183,205,284,287,313,503,508,516,529,533,544,727,766,826,965,992,999 'ux':191,435,772 'ux-research':190 'vagu':10,63,226,239,861,1058 'valid':186 'valu':827 'vari':260 'verifi':682,693,917,927,1054 'version':823 'visitor':320 'walk':934 'want':27,536,547 'web':171 'week':621,1088 'weight':1169 'whatev':708 'whenev':20 'whoever':939 'within':632 'without':704,803,972,976,1037,1044 'work':82,92,221,337,449,485,604,654,688,874,893,985,1062,1100,1163 'workflow':228,246,854 'write':4,58,104,132,236,475,899 'xl':622","prices":[{"id":"6414aa15-0242-44e1-a906-762b0e1c7483","listingId":"df186210-d83d-4f72-afaa-823f7e623b2f","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"rampstackco","category":"claude-skills","install_from":"skills.sh"},"createdAt":"2026-04-30T01:01:29.500Z"}],"sources":[{"listingId":"df186210-d83d-4f72-afaa-823f7e623b2f","source":"github","sourceId":"rampstackco/claude-skills/pm-spec-writing","sourceUrl":"https://github.com/rampstackco/claude-skills/tree/main/skills/pm-spec-writing","isPrimary":false,"firstSeenAt":"2026-04-30T01:01:29.500Z","lastSeenAt":"2026-05-18T18:55:18.758Z"}],"details":{"listingId":"df186210-d83d-4f72-afaa-823f7e623b2f","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"rampstackco","slug":"pm-spec-writing","github":{"repo":"rampstackco/claude-skills","stars":181,"topics":["agent-skills","anthropic","awesome-claude-code","awesome-claude-prompts","awesome-claude-skills","claude","claude-code","claude-skills","good-first-issue","mcp","product-management","seo","show-hn","showcase","showdev","web-design","web-development"],"license":"mit","html_url":"https://github.com/rampstackco/claude-skills","pushed_at":"2026-05-10T22:40:22Z","description":"Stack-agnostic Claude Skills covering the full website lifecycle: brand, design, content, SEO, dev, ops, growth, and research. Build, ship, audit, optimize.","skill_md_sha":"abb72adb6693729081ce30c0f2a04e9456cb0ec0","skill_md_path":"skills/pm-spec-writing/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/rampstackco/claude-skills/tree/main/skills/pm-spec-writing"},"layout":"multi","source":"github","category":"claude-skills","frontmatter":{"name":"pm-spec-writing","description":"Translate ideas, feature requests, or vague concepts into specific, actionable dev briefs. Use this skill whenever the user has an idea they want to build, a feature to spec out, a bug to file, a project to scope, or needs to convert a half-formed idea into a clear implementation brief. Triggers on I want to add, we should build, can we make, what is the plan for, how do we implement, dev brief, feature spec, PRD, user story, acceptance criteria, scope this, prioritize. Also triggers when the user has a list of things they want to build and needs help converting them into well-formed tasks."},"skills_sh_url":"https://skills.sh/rampstackco/claude-skills/pm-spec-writing"},"updatedAt":"2026-05-18T18:55:18.758Z"}}