{"id":"43590a54-83f8-4b3c-9464-b3fbcb2b61c9","shortId":"hCmzt9","kind":"skill","title":"create-adr","tagline":"Record an Architecture Decision Record (ADR) — a 1–3 sentence note capturing what was decided and why. Use when user says \"create an ADR\", \"record this decision\", \"/create-adr\", or just decided something architecturally significant. Don't use for forward-looking specs (use hb:prd","description":"# Create ADR\n\nCapture architectural decisions as durable, minimal records future-you (and future-Claude) can read instead of guessing from code.\n\n## Gate — write an ADR only if all three are true\n\n1. **Hard to reverse** — changing your mind later costs meaningful effort (migration, rewrite, vendor lock-in).\n2. **Surprising without context** — a future reader will look at the code and wonder \"why did they do it this way?\"\n3. **Real trade-off** — there were genuine alternatives, and you picked one for specific reasons.\n\nIf any criterion is missing, **say so and skip the ADR.** Easy-to-reverse decisions get reversed; obvious decisions don't need recording; non-decisions (\"we did the only thing that worked\") aren't ADRs.\n\nCheap rejections prevent ADR sprawl. When in doubt, refuse and ask the user to confirm the decision really meets all three.\n\n## What qualifies\n\n- **Architectural shape** — \"monorepo,\" \"event-sourced write model + projected read model\"\n- **Integration patterns between modules/contexts** — \"Ordering and Billing communicate via events, not synchronous HTTP\"\n- **Technology choices with lock-in** — database, message bus, auth provider, deployment target. Not every library — only ones that take a quarter to swap.\n- **Boundary and ownership decisions** — \"Customer data is owned by Customer; other contexts reference by ID.\"\n- **Deliberate deviations from the obvious path** — \"manual SQL instead of an ORM because X.\" Stops the next engineer \"fixing\" a deliberate choice.\n- **Constraints not visible in code** — \"no AWS due to compliance,\" \"must respond <200ms due to partner SLA.\"\n- **Rejected alternatives when the rejection is non-obvious** — considered GraphQL, picked REST for subtle reasons. Otherwise someone re-suggests it in six months.\n\n## Workflow\n\n### 1. Verify the gate\n\nRestate the decision in one sentence. Check it against all three criteria explicitly. If it fails, tell the user which criterion failed and stop.\n\n### 2. Locate `docs/adr/`\n\n- If `docs/adr/` exists, scan for the highest `NNNN-*.md` filename and increment.\n- If it doesn't exist, create it lazily — only now that there's something to write.\n- Numbering: zero-padded 4 digits (`0001`, `0002`, …).\n\n### 3. Draft\n\nWrite `docs/adr/NNNN-<kebab-slug>.md` using the template below. Slug should be short and search-friendly (`postgres-for-write-model`, not `decision-about-database-choice`).\n\n```md\n# {Short title of the decision}\n\n{1–3 sentences: context, what was decided, and why.}\n```\n\nThat's it. **An ADR can be a single paragraph.** The value is recording *that* a decision was made and *why* — not filling out sections.\n\n### 4. Optional sections — include only when they add genuine value\n\nMost ADRs won't need any of these.\n\n- **Status frontmatter** (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions get revisited.\n- **Considered Options** — only when rejected alternatives are worth remembering (e.g., \"considered GraphQL\" so it doesn't get re-suggested).\n- **Consequences** — only when non-obvious downstream effects need calling out.\n\n### 5. Show the user\n\nPrint the file path and the rendered content. Don't auto-commit — let the user stage it (matches their git rules).\n\n## Rules\n\n- Never write an ADR that fails the gate. Refuse and say which criterion failed.\n- Never create `docs/adr/` until you have a real ADR to put in it (lazy creation).\n- Never use `git add` here — the user stages explicitly.\n- Title is the decision, not the question. \"Use Postgres for write model\" — not \"Which database for write model?\"\n- Sentences should be tight and present-tense. No hedging, no \"we are considering.\"\n- ADR ≠ PRD. If the work is forward-looking (specs, plans, user stories), redirect to `/hb:prd`.\n- ADR ≠ CLAUDE.md. If it's a repo convention, gotcha, or general rule, redirect to `learn`/`learner`.\n\n## Example\n\n✅ Good — passes gate:\n\n> # 0003 — Manual SQL instead of an ORM\n>\n> The query patterns are write-heavy and join-shaped in ways ORMs handle poorly; we hit perf cliffs in the spike. We accept the boilerplate cost in exchange for predictable plans and explicit transactions. Considered Prisma and Drizzle.\n\n❌ Reject — fails \"hard to reverse\":\n\n> \"We decided to use Prettier for formatting.\"\n\nReversible in one PR. Not an ADR — that's a `.prettierrc` and maybe a line in CLAUDE.md.\n\n❌ Reject — fails \"surprising without context\":\n\n> \"We decided to write tests.\"\n\nNobody will wonder why.","tags":["create","adr","agent","skills","helderberto","agent-skills","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli"],"capabilities":["skill","source-helderberto","skill-create-adr","topic-agent-skills","topic-ai-tools","topic-antigravity","topic-claude-code","topic-cursor","topic-developer-tools","topic-gemini-cli","topic-markdown","topic-plugin","topic-sdlc","topic-skills","topic-tracer-bullet"],"categories":["agent-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/helderberto/agent-skills/create-adr","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add helderberto/agent-skills","source_repo":"https://github.com/helderberto/agent-skills","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (4,445 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:09:12.648Z","embedding":null,"createdAt":"2026-05-18T13:14:52.635Z","updatedAt":"2026-05-18T19:09:12.648Z","lastSeenAt":"2026-05-18T19:09:12.648Z","tsv":"'/create-adr':31 '/hb':635 '0001':389 '0002':390 '0003':657 '1':11,82,324,425 '2':99,352 '200ms':293 '3':12,120,391,426 '4':387,459 '5':523 'accept':480,688 'add':466,582 'adr':3,9,27,50,75,146,172,176,438,470,485,553,572,620,637,722 'adr-nnnn':484 'altern':128,299,497 'architectur':6,36,52,196 'aren':170 'ask':183 'auth':229 'auto':538 'auto-commit':537 'aw':287 'bill':213 'boilerpl':690 'boundari':244 'bus':228 'call':521 'captur':15,51 'chang':86 'cheap':173 'check':334 'choic':221,280,418 'claud':64 'claude.md':638,732 'cliff':683 'code':71,110,285 'commit':539 'communic':214 'complianc':290 'confirm':187 'consequ':512 'consid':307,492,502,619,700 'constraint':281 'content':534 'context':102,255,428,737 'convent':644 'cost':90,691 'creat':2,25,49,372,565 'create-adr':1 'creation':578 'criteria':339 'criterion':138,348,562 'custom':248,253 'data':249 'databas':226,417,602 'decid':18,34,431,710,739 'decis':7,30,53,151,155,162,189,247,330,415,424,450,489,591 'decision-about-database-choic':414 'deliber':259,279 'deploy':231 'deprec':481 'deviat':260 'digit':388 'docs/adr':354,356,566 'docs/adr/nnnn-':394 'doesn':369,506 'doubt':180 'downstream':518 'draft':392 'drizzl':703 'due':288,294 'durabl':55 'e.g':501 'easi':148 'easy-to-revers':147 'effect':519 'effort':92 'engin':276 'event':200,216 'event-sourc':199 'everi':234 'exampl':653 'exchang':693 'exist':357,371 'explicit':340,587,698 'fail':343,349,555,563,705,734 'file':529 'filenam':364 'fill':456 'fix':277 'format':715 'forward':43,627 'forward-look':42,626 'friend':407 'frontmatt':478 'futur':59,63,104 'future-claud':62 'future-you':58 'gate':72,327,557,656 'general':647 'genuin':127,467 'get':152,490,508 'git':547,581 'good':654 'gotcha':645 'graphql':308,503 'guess':69 'handl':678 'hard':83,706 'hb':47 'heavi':670 'hedg':615 'highest':361 'hit':681 'http':219 'id':258 'includ':462 'increment':366 'instead':67,267,660 'integr':207 'join':673 'join-shap':672 'later':89 'lazi':577 'lazili':374 'learn':651 'learner':652 'let':540 'librari':235 'line':730 'locat':353 'lock':97,224 'lock-in':96,223 'look':44,107,628 'made':452 'manual':265,658 'match':545 'mayb':728 'md':363,395,419 'meaning':91 'meet':191 'messag':227 'migrat':93 'mind':88 'minim':56 'miss':140 'model':203,206,412,599,605 'modules/contexts':210 'monorepo':198 'month':322 'must':291 'need':158,473,520 'never':550,564,579 'next':275 'nnnn':362,486 'nobodi':743 'non':161,305,516 'non-decis':160 'non-obvi':304,515 'note':14 'number':383 'obvious':154,263,306,517 'one':132,237,332,718 'option':460,493 'order':211 'orm':270,663,677 'otherwis':314 'own':251 'ownership':246 'pad':386 'paragraph':443 'partner':296 'pass':655 'path':264,530 'pattern':208,666 'perf':682 'pick':131,309 'plan':630,696 'poor':679 'postgr':409,596 'postgres-for-write-model':408 'pr':719 'prd':48,621,636 'predict':695 'present':612 'present-tens':611 'prettier':713 'prettierrc':726 'prevent':175 'print':527 'prisma':701 'project':204 'propos':479 'provid':230 'put':574 'qualifi':195 'quarter':241 'queri':665 'question':594 're':317,510 're-suggest':316,509 'read':66,205 'reader':105 'real':121,571 'realli':190 'reason':135,313 'record':4,8,28,57,159,447 'redirect':633,649 'refer':256 'refus':181,558 'reject':174,298,302,496,704,733 'rememb':500 'render':533 'repo':643 'respond':292 'rest':310 'restat':328 'revers':85,150,153,708,716 'revisit':491 'rewrit':94 'rule':548,549,648 'say':24,141,560 'scan':358 'search':406 'search-friend':405 'section':458,461 'sentenc':13,333,427,606 'shape':197,674 'short':403,420 'show':524 'signific':37 'singl':442 'six':321 'skill' 'skill-create-adr' 'skip':144 'sla':297 'slug':400 'someon':315 'someth':35,380 'sourc':201 'source-helderberto' 'spec':45,629 'specif':134 'spike':686 'sprawl':177 'sql':266,659 'stage':543,586 'status':477 'stop':273,351 'stori':632 'subtl':312 'suggest':318,511 'supersed':482 'surpris':100,735 'swap':243 'synchron':218 'take':239 'target':232 'technolog':220 'tell':344 'templat':398 'tens':613 'test':742 'thing':167 'three':79,193,338 'tight':609 'titl':421,588 'topic-agent-skills' 'topic-ai-tools' 'topic-antigravity' 'topic-claude-code' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'topic-markdown' 'topic-plugin' 'topic-sdlc' 'topic-skills' 'topic-tracer-bullet' 'trade':123 'trade-off':122 'transact':699 'true':81 'use':21,40,46,396,487,580,595,712 'user':23,185,346,526,542,585,631 'valu':445,468 'vendor':95 'verifi':325 'via':215 'visibl':283 'way':119,676 'without':101,736 'won':471 'wonder':112,745 'work':169,624 'workflow':323 'worth':499 'write':73,202,382,393,411,551,598,604,669,741 'write-heavi':668 'x':272 'zero':385 'zero-pad':384","prices":[{"id":"59a50297-623c-4507-94ab-e71bc1a589cf","listingId":"43590a54-83f8-4b3c-9464-b3fbcb2b61c9","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"helderberto","category":"agent-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:14:52.635Z"}],"sources":[{"listingId":"43590a54-83f8-4b3c-9464-b3fbcb2b61c9","source":"github","sourceId":"helderberto/agent-skills/create-adr","sourceUrl":"https://github.com/helderberto/agent-skills/tree/main/skills/create-adr","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:52.635Z","lastSeenAt":"2026-05-18T19:09:12.648Z"}],"details":{"listingId":"43590a54-83f8-4b3c-9464-b3fbcb2b61c9","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"helderberto","slug":"create-adr","github":{"repo":"helderberto/agent-skills","stars":8,"topics":["agent-skills","ai","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli","markdown","plugin","sdlc","skills","tracer-bullet"],"license":"mit","html_url":"https://github.com/helderberto/agent-skills","pushed_at":"2026-05-14T11:37:47Z","description":"My personal SDLC toolbelt for AI coding agents — PRD to ship.","skill_md_sha":"1925b9c6c54868d76ffc42b837412a2586c0a7cb","skill_md_path":"skills/create-adr/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/helderberto/agent-skills/tree/main/skills/create-adr"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"create-adr","description":"Record an Architecture Decision Record (ADR) — a 1–3 sentence note capturing what was decided and why. Use when user says \"create an ADR\", \"record this decision\", \"/create-adr\", or just decided something architecturally significant. Don't use for forward-looking specs (use hb:prd) or general repo conventions (use CLAUDE.md)."},"skills_sh_url":"https://skills.sh/helderberto/agent-skills/create-adr"},"updatedAt":"2026-05-18T19:09:12.648Z"}}