{"id":"be050f4a-6ff8-46d5-94f5-d94a5448d2bb","shortId":"AK7DvZ","kind":"skill","title":"writing-specs-designs","tagline":"Create a build-ready spec + design doc (user flows, prototype brief, acceptance criteria). See also: writing-prds (decision-level PRD).","description":"# Writing Specs & Designs\n\n## Scope\n\n**Covers**\n- Producing a **Spec & Design Doc Pack** that helps product, design, and engineering quickly reach shared clarity\n- Converting “insights” into **concrete artifacts**: a low‑fidelity diagram, flows/states, prototype plan, and testable acceptance criteria\n- Mobile-specific **tap economy** (when relevant): explicitly optimizing taps and interaction cost\n\n**When to use**\n- “Write a spec / feature spec / technical spec for this feature.”\n- “Turn these notes into a design doc that engineering can build from.”\n- “Create a shaping-style doc with a diagram of the moving pieces.”\n- “We need a prototype plan to evaluate the feel of this interaction.”\n\n**When NOT to use**\n- You’re still validating *what problem to solve* (do discovery / problem definition first).\n- You need a high-level strategy/vision document (do product vision / north star work first).\n- You need a deep engineering architecture design (APIs, schemas, scaling, reliability) rather than product interaction clarity.\n- You only need pixel-perfect UI mocks (this produces specs and structured guidance, not final visuals).\n- You need a decision-level PRD with requirements and success metrics but not build-ready flows -> use `writing-prds`\n- You need expert design critique on an existing prototype -> use `running-design-reviews`\n- You need to validate designs with real users -> use `usability-testing`\n- You need to establish design-engineering handoff processes or design system standards -> use `design-engineering`\n\n## Inputs\n\n**Minimum required**\n- Feature/change: 1–2 sentence description\n- Target users + primary use case (happy path)\n- Platform(s): web / iOS / Android / desktop (call out mobile explicitly)\n- Goals + non-goals (v1 boundaries)\n- Constraints: timeline, dependencies, policy/legal/privacy, technical constraints\n- Success metrics (1–3) + guardrails (2–5)\n\n**Missing-info strategy**\n- Ask up to 5 questions from [references/INTAKE.md](references/INTAKE.md), then proceed.\n- If key info remains missing, state assumptions explicitly and provide 2–3 options (scope/flows/prototype approach).\n\n## Outputs (deliverables)\n\nProduce a **Spec & Design Doc Pack** in Markdown (in-chat; or as files if the user requests):\n\n1) **Context snapshot** (problem, why now, goals/non-goals, constraints, stakeholders)\n2) **Low‑fidelity diagram** of the moving pieces (≤10) + key decisions\n3) **User flows + states** (happy path + top edge cases) with clear entry/exit points\n4) **Prototype brief** (what to prototype, fidelity, timebox, data realism, success criteria)\n5) **Requirements + acceptance criteria** (testable; must/should/could)\n6) **Measurement plan** (metrics → data/events → owner → cadence)\n7) **Risks / Open questions / Next steps** (always included)\n\nTemplates: [references/TEMPLATES.md](references/TEMPLATES.md)\n\n## Workflow (8 steps)\n\n### 1) Choose the smallest artifact set that unblocks the team\n- **Inputs:** User request + constraints.\n- **Actions:** Decide whether to deliver: (a) Spec & Design Doc only, or (b) Spec & Design Doc + Prototype Brief emphasis (feel-critical).\n- **Outputs:** Artifact selection + rationale.\n- **Checks:** Artifacts match the decision being made (alignment vs build execution vs interaction feel).\n\n### 2) Intake + context snapshot\n- **Inputs:** [references/INTAKE.md](references/INTAKE.md).\n- **Actions:** Ask up to 5 questions; confirm audience/DRI, platform(s), constraints, and success metrics/guardrails.\n- **Outputs:** Context snapshot section.\n- **Checks:** You can state the problem, user, and success measure in 1–2 sentences.\n\n### 3) Lock scope boundaries (and define “tap budget” if mobile)\n- **Inputs:** Context snapshot.\n- **Actions:** Write goals, non-goals, out-of-scope, assumptions, dependencies. For mobile flows, define a “tap budget” (max taps to value) and where attention is most fragile.\n- **Outputs:** Scope boundaries + (optional) tap budget.\n- **Checks:** “What we are NOT doing” is explicit; mobile value path has a clear tap target.\n\n### 4) Draft the low‑fidelity diagram (the “shaping” output)\n- **Inputs:** Scope + constraints.\n- **Actions:** Produce a diagram that shows the moving pieces (≤10), data/hand-offs, and where UX decisions matter. Avoid pixel-level UI; prefer clarity of structure.\n- **Outputs:** Low‑fidelity diagram + annotated decisions.\n- **Checks:** A partner can say “I know what to build” without a meeting.\n\n### 5) Specify user flows + states (make edge cases concrete)\n- **Inputs:** Diagram + use case(s).\n- **Actions:** Document entry points, happy path, and top edge cases; include error/empty/loading states, permissions, and copy notes where ambiguity causes bugs.\n- **Outputs:** Flow + state table(s).\n- **Checks:** Another person can role-play the flow; each edge case has an intended outcome.\n\n### 6) Write the prototype brief (only where “feel” matters)\n- **Inputs:** Flows/states + unknowns.\n- **Actions:** Identify the 1–3 riskiest interaction uncertainties; specify prototype type (low-fi, hi-fi, or in-code), timebox, realism (use real data where possible), and what “good” feels like.\n- **Outputs:** Prototype brief.\n- **Checks:** Prototype plan is testable (scenarios + success criteria), and explicitly disposable if using throwaway code.\n\n### 7) Convert into testable requirements + acceptance criteria\n- **Inputs:** Flows/states + prototype learnings (if any).\n- **Actions:** Write requirements with acceptance criteria (must/should/could). Include non-functional needs (accessibility, performance, privacy) and instrumentation needs.\n- **Outputs:** Requirements section.\n- **Checks:** Engineering/QA can derive test cases without re-interpreting intent.\n\n### 8) Quality gate + finalize for circulation\n- **Inputs:** Full draft pack.\n- **Actions:** Run [references/CHECKLISTS.md](references/CHECKLISTS.md) and score with [references/RUBRIC.md](references/RUBRIC.md). Add Risks/Open questions/Next steps and clearly mark decisions vs assumptions.\n- **Outputs:** Final Spec & Design Doc Pack (shareable as-is).\n- **Checks:** Owners, metrics, and open questions are explicit; the diagram + flows remove the biggest ambiguities.\n\n## Quality gate (required)\n- Use [references/CHECKLISTS.md](references/CHECKLISTS.md) and [references/RUBRIC.md](references/RUBRIC.md).\n- Always include: **Risks**, **Open questions**, **Next steps**.\n\n## Examples\n\n**Example 1 (mobile flow):** “Write a spec + design doc for a new ‘invite friends’ flow in our iOS app. Goal: increase successful invites; minimize taps to first value.”  \nExpected: tap budget + flow/state tables, a low-fi diagram of screens/transitions, and a prototype brief for the critical interaction.\n\n**Example 2 (B2B web feature):** “Create a design doc/spec for ‘bulk edit roles’ for admins. Include edge cases and acceptance criteria.”  \nExpected: permissions-focused flows/states, requirements with acceptance criteria, and a measurement plan.\n\n**Boundary example (redirect):** “We need to decide whether to build this feature and align stakeholders on requirements and success metrics.”\nResponse: redirect to `writing-prds` -- this request is about decision-level alignment and requirements, not build-ready interaction specs and flows.\n\n**Boundary example (insufficient context):** “Write a spec to ‘improve engagement’ (no product context, no user, no success metric).”\nResponse: ask the minimum intake questions; if still missing, provide 2-3 scoped options + assumptions and recommend upstream discovery before committing to a spec.\n\n## Anti-patterns\n\nAvoid these common failure modes when writing specs and design docs:\n\n1. **Diagram-as-decoration** -- Including a diagram that restates the text without showing moving pieces, data flow, or decision points. The diagram should reveal structure that prose cannot.\n2. **Happy-path-only flows** -- Documenting only the ideal path and omitting error, empty, loading, and permission states. Edge cases discovered during build are 10x more expensive to handle.\n3. **Prototype without a question** -- Proposing a prototype brief without a clear hypothesis or success criteria. Every prototype must answer a specific design uncertainty.\n4. **Spec-as-PRD** -- Including strategic rationale, market context, or stakeholder alignment content that belongs in a PRD. Specs should assume the “what” and “why” are decided and focus on “how it works.”\n5. **Missing platform specifics** -- Writing platform-agnostic flows when the feature has mobile-specific constraints (tap economy, notifications, offline states). Always call out platform differences explicitly.","tags":["writing","specs","designs","lenny","skills","plus","liqiongyu","agent-skills","ai-agents","automation","claude","codex"],"capabilities":["skill","source-liqiongyu","skill-writing-specs-designs","topic-agent-skills","topic-ai-agents","topic-automation","topic-claude","topic-codex","topic-prompt-engineering","topic-refoundai","topic-skillpack"],"categories":["lenny_skills_plus"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/liqiongyu/lenny_skills_plus/writing-specs-designs","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add liqiongyu/lenny_skills_plus","source_repo":"https://github.com/liqiongyu/lenny_skills_plus","install_from":"skills.sh"}},"qualityScore":"0.474","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 49 github stars · SKILL.md body (8,601 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-04-22T00:56:26.658Z","embedding":null,"createdAt":"2026-04-18T22:17:17.592Z","updatedAt":"2026-04-22T00:56:26.658Z","lastSeenAt":"2026-04-22T00:56:26.658Z","tsv":"'-3':1025 '1':262,297,351,423,512,706,871,1052 '10':368,600 '10x':1106 '2':263,300,326,360,476,513,919,1024,1081 '3':298,327,371,515,707,1111 '4':384,579,1135 '5':301,309,396,487,635,1169 '6':402,691 '7':409,754 '8':421,799 'accept':17,63,398,759,771,937,946 'access':779 'action':437,483,528,591,649,703,767,809 'add':818 'admin':932 'agnost':1176 'align':469,965,985,1147 'also':20 'alway':415,862,1191 'ambigu':667,852 'android':277 'annot':620 'anoth':676 'answer':1130 'anti':1039 'anti-pattern':1038 'api':167 'app':888 'approach':330 'architectur':165 'artifact':53,427,459,463 'as-i':835 'ask':306,484,1015 'assum':1156 'assumpt':322,538,827,1028 'attent':553 'audience/dri':490 'avoid':607,1041 'b':448 'b2b':920 'belong':1150 'biggest':851 'boundari':288,518,559,952,996 'brief':16,386,453,695,738,913,1119 'budget':522,546,562,900 'bug':669 'build':8,101,208,471,631,961,990,1104 'build-readi':7,207,989 'bulk':928 'cadenc':408 'call':279,1192 'cannot':1080 'case':270,379,642,647,658,686,793,935,1101 'caus':668 'chat':343 'check':462,501,563,622,675,739,788,838 'choos':424 'circul':804 'clariti':48,175,613 'clear':381,576,823,1122 'code':723,753 'commit':1034 'common':1043 'concret':52,643 'confirm':489 'constraint':289,294,358,436,493,590,1185 'content':1148 'context':352,478,498,526,999,1008,1144 'convert':49,755 'copi':664 'cost':77 'cover':32 'creat':5,103,923 'criteria':18,64,395,399,746,760,772,938,947,1126 'critic':457,916 'critiqu':219 'data':392,728,1068 'data/events':406 'data/hand-offs':601 'decid':438,958,1162 'decis':25,197,370,466,605,621,825,983,1071 'decision-level':24,196,982 'decor':1056 'deep':163 'defin':520,543 'definit':143 'deliv':441 'deliver':332 'depend':291,539 'deriv':791 'descript':265 'design':4,11,30,36,42,96,166,218,227,233,246,251,256,336,444,450,831,877,925,1050,1133 'design-engin':245,255 'desktop':278 'diagram':57,111,363,584,594,619,645,847,907,1054,1059,1074 'diagram-as-decor':1053 'differ':1195 'discov':1102 'discoveri':141,1032 'dispos':749 'doc':12,37,97,108,337,445,451,832,878,1051 'doc/spec':926 'document':152,650,1087 'draft':580,807 'economi':69,1187 'edg':378,641,657,685,934,1100 'edit':929 'emphasi':454 'empti':1095 'engag':1005 'engin':44,99,164,247,257 'engineering/qa':789 'entri':651 'entry/exit':382 'error':1094 'error/empty/loading':660 'establish':244 'evalu':122 'everi':1127 'exampl':869,870,918,953,997 'execut':472 'exist':222 'expect':898,939 'expens':1108 'expert':217 'explicit':72,282,323,570,748,845,1196 'failur':1044 'featur':84,90,922,963,1180 'feature/change':261 'feel':124,456,475,698,734 'feel-crit':455 'fi':716,719,906 'fidel':56,362,390,583,618 'file':346 'final':191,802,829 'first':144,159,896 'flow':14,210,373,542,638,671,683,848,873,884,995,1069,1086,1177 'flow/state':901 'flows/states':58,701,762,943 'focus':942,1164 'fragil':556 'friend':883 'full':806 'function':777 'gate':801,854 'goal':283,286,530,533,889 'goals/non-goals':357 'good':733 'guardrail':299 'guidanc':189 'handl':1110 'handoff':248 'happi':271,375,653,1083 'happy-path-on':1082 'help':40 'hi':718 'hi-fi':717 'high':149 'high-level':148 'hypothesi':1123 'ideal':1090 'identifi':704 'improv':1004 'in-chat':341 'in-cod':721 'includ':416,659,774,863,933,1057,1140 'increas':890 'info':304,318 'input':258,433,480,525,588,644,700,761,805 'insight':50 'instrument':783 'insuffici':998 'intak':477,1018 'intend':689 'intent':798 'interact':76,127,174,474,709,917,992 'interpret':797 'invit':882,892 'io':276,887 'key':317,369 'know':628 'learn':764 'level':26,150,198,610,984 'like':735 'load':1096 'lock':516 'low':55,361,582,617,715,905 'low-fi':714,904 'made':468 'make':640 'mark':824 'markdown':340 'market':1143 'match':464 'matter':606,699 'max':547 'measur':403,510,950 'meet':634 'metric':204,296,405,840,971,1013 'metrics/guardrails':496 'minim':893 'minimum':259,1017 'miss':303,320,1022,1170 'missing-info':302 'mobil':66,281,524,541,571,872,1183 'mobile-specif':65,1182 'mock':183 'mode':1045 'move':114,366,598,1066 'must':1129 'must/should/could':401,773 'need':117,146,161,178,194,216,230,242,778,784,956 'new':881 'next':413,867 'non':285,532,776 'non-funct':775 'non-goal':284,531 'north':156 'note':93,665 'notif':1188 'offlin':1189 'omit':1093 'open':411,842,865 'optim':73 'option':328,560,1027 'out-of-scop':534 'outcom':690 'output':331,458,497,557,587,616,670,736,785,828 'owner':407,839 'pack':38,338,808,833 'partner':624 'path':272,376,573,654,1084,1091 'pattern':1040 'perfect':181 'perform':780 'permiss':662,941,1098 'permissions-focus':940 'person':677 'piec':115,367,599,1067 'pixel':180,609 'pixel-level':608 'pixel-perfect':179 'plan':60,120,404,741,951 'platform':273,491,1171,1175,1194 'platform-agnost':1174 'play':681 'point':383,652,1072 'policy/legal/privacy':292 'possibl':730 'prd':27,199,1139,1153 'prds':23,214,977 'prefer':612 'primari':268 'privaci':781 'problem':137,142,354,506 'proceed':315 'process':249 'produc':33,185,333,592 'product':41,154,173,1007 'propos':1116 'prose':1079 'prototyp':15,59,119,223,385,389,452,694,712,737,740,763,912,1112,1118,1128 'provid':325,1023 'qualiti':800,853 'question':310,412,488,843,866,1019,1115 'questions/next':820 'quick':45 'rather':171 'rational':461,1142 're':133,796 're-interpret':795 'reach':46 'readi':9,209,991 'real':235,727 'realism':393,725 'recommend':1030 'redirect':954,973 'references/checklists.md':811,812,857,858 'references/intake.md':312,313,481,482 'references/rubric.md':816,817,860,861 'references/templates.md':418,419 'relev':71 'reliabl':170 'remain':319 'remov':849 'request':350,435,979 'requir':201,260,397,758,769,786,855,944,968,987 'respons':972,1014 'restat':1061 'reveal':1076 'review':228 'risk':410,864 'riskiest':708 'risks/open':819 'role':680,930 'role-play':679 'run':226,810 'running-design-review':225 'say':626 'scale':169 'scenario':744 'schema':168 'scope':31,517,537,558,589,1026 'scope/flows/prototype':329 'score':814 'screens/transitions':909 'section':500,787 'see':19 'select':460 'sentenc':264,514 'set':428 'shape':106,586 'shaping-styl':105 'share':47 'shareabl':834 'show':596,1065 'skill' 'skill-writing-specs-designs' 'smallest':426 'snapshot':353,479,499,527 'solv':139 'source-liqiongyu' 'spec':3,10,29,35,83,85,87,186,335,443,449,830,876,993,1002,1037,1048,1137,1154 'spec-as-prd':1136 'specif':67,1132,1172,1184 'specifi':636,711 'stakehold':359,966,1146 'standard':253 'star':157 'state':321,374,504,639,661,672,1099,1190 'step':414,422,821,868 'still':134,1021 'strateg':1141 'strategi':305 'strategy/vision':151 'structur':188,615,1077 'style':107 'success':203,295,394,495,509,745,891,970,1012,1125 'system':252 'tabl':673,902 'tap':68,74,521,545,548,561,577,894,899,1186 'target':266,578 'team':432 'technic':86,293 'templat':417 'test':240,792 'testabl':62,400,743,757 'text':1063 'throwaway':752 'timebox':391,724 'timelin':290 'top':377,656 'topic-agent-skills' 'topic-ai-agents' 'topic-automation' 'topic-claude' 'topic-codex' 'topic-prompt-engineering' 'topic-refoundai' 'topic-skillpack' 'turn':91 'type':713 'ui':182,611 'unblock':430 'uncertainti':710,1134 'unknown':702 'upstream':1031 'usability-test':238 'usabl':239 'use':80,131,211,224,237,254,269,646,726,751,856 'user':13,236,267,349,372,434,507,637,1010 'ux':604 'v1':287 'valid':135,232 'valu':550,572,897 'vision':155 'visual':192 'vs':470,473,826 'web':275,921 'whether':439,959 'without':632,794,1064,1113,1120 'work':158,1168 'workflow':420 'write':2,22,28,81,213,529,692,768,874,976,1000,1047,1173 'writing-prd':21,212,975 'writing-specs-design':1","prices":[{"id":"ebc29a3a-acb3-4adb-96df-e7bd75914d1f","listingId":"be050f4a-6ff8-46d5-94f5-d94a5448d2bb","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"liqiongyu","category":"lenny_skills_plus","install_from":"skills.sh"},"createdAt":"2026-04-18T22:17:17.592Z"}],"sources":[{"listingId":"be050f4a-6ff8-46d5-94f5-d94a5448d2bb","source":"github","sourceId":"liqiongyu/lenny_skills_plus/writing-specs-designs","sourceUrl":"https://github.com/liqiongyu/lenny_skills_plus/tree/main/skills/writing-specs-designs","isPrimary":false,"firstSeenAt":"2026-04-18T22:17:17.592Z","lastSeenAt":"2026-04-22T00:56:26.658Z"}],"details":{"listingId":"be050f4a-6ff8-46d5-94f5-d94a5448d2bb","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"liqiongyu","slug":"writing-specs-designs","github":{"repo":"liqiongyu/lenny_skills_plus","stars":49,"topics":["agent-skills","ai-agents","automation","claude","codex","prompt-engineering","refoundai","skillpack"],"license":"apache-2.0","html_url":"https://github.com/liqiongyu/lenny_skills_plus","pushed_at":"2026-04-04T06:30:11Z","description":"86 agent-executable skill packs converted from RefoundAI’s Lenny skills (unofficial). Works with Codex + Claude Code.","skill_md_sha":"1df574d9bebd2e17ec0b46221fb1e913724c2fa8","skill_md_path":"skills/writing-specs-designs/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/liqiongyu/lenny_skills_plus/tree/main/skills/writing-specs-designs"},"layout":"multi","source":"github","category":"lenny_skills_plus","frontmatter":{"name":"writing-specs-designs","description":"Create a build-ready spec + design doc (user flows, prototype brief, acceptance criteria). See also: writing-prds (decision-level PRD)."},"skills_sh_url":"https://skills.sh/liqiongyu/lenny_skills_plus/writing-specs-designs"},"updatedAt":"2026-04-22T00:56:26.658Z"}}