{"id":"a3deebe3-1877-450b-888e-fcb4a9ea0594","shortId":"4Sh6B8","kind":"skill","title":"architecture","tagline":"Load before designing a new system, choosing between competing implementations, weighing tradeoffs across libraries or frameworks, or escalating an architectural question to a human. Fires at the moment a multi-option design decision appears, not during routine implementation.","description":"Use this when facing a software design decision with multiple valid approaches, hard-to-reverse consequences, or system boundary implications.\n\n## Design prerequisite check\n\nBefore evaluating options, check whether a prerequisite refactor would simplify the work. For any change touching domain logic, authorization, state machines, or anything enforced in more than one layer — read the relevant code and answer:\n\n- **Scattered enforcement:** is this concept already checked in multiple places? List callsites. If yes, is centralizing first a prerequisite?\n- **Coupling:** does this add a new dependency between modules that had no prior relationship?\n- **Extensibility:** is this the 2nd or 3rd instance of a pattern? Is there a single abstraction that serves all of them?\n\nIf a prerequisite refactor would simplify the work, surface it: propose a separate issue/PR, get user confirmation, do it first.\n\n## Steps\n\n1. **Gather context.** State the problem, constraints, and options. Use your `issues` capability for history and prior decisions if relevant. Research patterns, prior art, library docs.\n\n2. **Present options as a table.** Always include 2+ options — never one-option-as-fait-accompli.\n\n   | | Option A | Option B | … |\n   |---|---|---|---|\n   | **What it is** | … | … | … |\n   | **Pros** | … | … | … |\n   | **Cons** | … | … | … |\n   | **Best when** | … | … | … |\n\n3. **Score against software-architecture criteria:**\n\n   - **Reversibility:** how painful to undo in 6 months?\n   - **YAGNI:** real present problem or hypothetical?\n   - **Simplicity:** which would a new team member understand fastest?\n   - **Testability:** which is easiest to test in isolation?\n   - **Coupling:** does it create hard dependencies that constrain future changes?\n   - **Operational cost:** what does it add to deploy, monitor, debug?\n   - **DX:** which is less annoying day-to-day?\n\n   **Prefer reversibility and simplicity when criteria conflict. Complexity must earn its place.**\n\n4. **Call out system-level anti-patterns by name** when present in any option — use the catalog under your `code-quality` capability (Premature Abstraction, Wrong Layer, Leaky Abstraction, Distributed Monolith, Config as Code, Speculative Generality).\n\n5. **Escalate** when any of these are true; do not recommend unilaterally:\n\n   - Irreversible at the data layer (schema changes, migration strategy)\n   - Crosses service/team boundaries\n   - Significant operational cost (new infrastructure, new external dependency)\n   - You are genuinely uncertain after applying the framework\n\n6. **Recommend** with one concrete sentence naming the single most important reason. Never be vague. Never present one option as if no alternatives exist.\n\n## Writing the decision down\n\nIf the user asks for an ADR (architecture decision record), use `templates/adr.md` in this skill directory — covers status, context, decision, decision matrix, alternatives, consequences, and common mistakes. Apply the template to the user's situation; don't repeat it verbatim.","tags":["architecture","dotfiles","athal7","agent-skills"],"capabilities":["skill","source-athal7","skill-architecture","topic-agent-skills"],"categories":["dotfiles"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/athal7/dotfiles/architecture","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add athal7/dotfiles","source_repo":"https://github.com/athal7/dotfiles","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 6 github stars · SKILL.md body (3,026 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:14:33.853Z","embedding":null,"createdAt":"2026-05-18T13:22:28.272Z","updatedAt":"2026-05-18T19:14:33.853Z","lastSeenAt":"2026-05-18T19:14:33.853Z","tsv":"'1':175 '2':201,209 '2nd':137 '3':229 '3rd':139 '4':308 '5':346 '6':242,386 'abstract':148,334,338 'accompli':217 'across':14 'add':122,282 'adr':420 'alreadi':105 'altern':408,436 'alway':207 'annoy':291 'answer':99 'anti':315 'anti-pattern':314 'anyth':87 'appear':36 'appli':383,441 'approach':52 'architectur':1,21,234,421 'art':198 'ask':417 'author':83 'b':221 'best':227 'boundari':60,369 'call':309 'callsit':111 'capabl':187,332 'catalog':326 'central':115 'chang':79,276,364 'check':64,68,106 'choos':8 'code':97,330,343 'code-qu':329 'common':439 'compet':10 'complex':303 'con':226 'concept':104 'concret':390 'config':341 'confirm':170 'conflict':302 'consequ':57,437 'constrain':274 'constraint':181 'context':177,432 'cost':278,372 'coupl':119,267 'cover':430 'creat':270 'criteria':235,301 'cross':367 'data':361 'day':293,295 'day-to-day':292 'debug':286 'decis':35,48,192,412,422,433,434 'depend':125,272,377 'deploy':284 'design':4,34,47,62 'directori':429 'distribut':339 'doc':200 'domain':81 'dx':287 'earn':305 'easiest':262 'enforc':88,101 'escal':19,347 'evalu':66 'exist':409 'extens':133 'extern':376 'face':44 'fait':216 'fastest':258 'fire':26 'first':116,173 'framework':17,385 'futur':275 'gather':176 'general':345 'genuin':380 'get':168 'hard':54,271 'hard-to-revers':53 'histori':189 'human':25 'hypothet':249 'implement':11,40 'implic':61 'import':396 'includ':208 'infrastructur':374 'instanc':140 'irrevers':358 'isol':266 'issu':186 'issue/pr':167 'layer':93,336,362 'leaki':337 'less':290 'level':313 'librari':15,199 'list':110 'load':2 'logic':82 'machin':85 'matrix':435 'member':256 'migrat':365 'mistak':440 'modul':127 'moment':29 'monitor':285 'monolith':340 'month':243 'multi':32 'multi-opt':31 'multipl':50,108 'must':304 'name':318,392 'never':211,398,401 'new':6,124,254,373,375 'one':92,213,389,403 'one-option-as-fait-accompli':212 'oper':277,371 'option':33,67,183,203,210,214,218,220,323,404 'pain':238 'pattern':143,196,316 'place':109,307 'prefer':296 'prematur':333 'prerequisit':63,71,118,156 'present':202,246,320,402 'prior':131,191,197 'problem':180,247 'propos':164 'pros':225 'qualiti':331 'question':22 'read':94 'real':245 'reason':397 'recommend':356,387 'record':423 'refactor':72,157 'relationship':132 'relev':96,194 'repeat':451 'research':195 'revers':56,236,297 'routin':39 'scatter':100 'schema':363 'score':230 'sentenc':391 'separ':166 'serv':150 'service/team':368 'signific':370 'simplic':250,299 'simplifi':74,159 'singl':147,394 'situat':448 'skill':428 'skill-architecture' 'softwar':46,233 'software-architectur':232 'source-athal7' 'specul':344 'state':84,178 'status':431 'step':174 'strategi':366 'surfac':162 'system':7,59,312 'system-level':311 'tabl':206 'team':255 'templat':443 'templates/adr.md':425 'test':264 'testabl':259 'topic-agent-skills' 'touch':80 'tradeoff':13 'true':353 'uncertain':381 'understand':257 'undo':240 'unilater':357 'use':41,184,324,424 'user':169,416,446 'vagu':400 'valid':51 'verbatim':453 'weigh':12 'whether':69 'work':76,161 'would':73,158,252 'write':410 'wrong':335 'yagni':244 'yes':113","prices":[{"id":"26292708-8eca-4a44-a909-fd5435df2e8a","listingId":"a3deebe3-1877-450b-888e-fcb4a9ea0594","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"athal7","category":"dotfiles","install_from":"skills.sh"},"createdAt":"2026-05-18T13:22:28.272Z"}],"sources":[{"listingId":"a3deebe3-1877-450b-888e-fcb4a9ea0594","source":"github","sourceId":"athal7/dotfiles/architecture","sourceUrl":"https://github.com/athal7/dotfiles/tree/main/skills/architecture","isPrimary":false,"firstSeenAt":"2026-05-18T13:22:28.272Z","lastSeenAt":"2026-05-18T19:14:33.853Z"}],"details":{"listingId":"a3deebe3-1877-450b-888e-fcb4a9ea0594","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"athal7","slug":"architecture","github":{"repo":"athal7/dotfiles","stars":6,"topics":["agent-skills"],"license":null,"html_url":"https://github.com/athal7/dotfiles","pushed_at":"2026-05-18T18:53:57Z","description":null,"skill_md_sha":"b97d673d66b4697e2e63b8720e1d7118932048a5","skill_md_path":"skills/architecture/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/athal7/dotfiles/tree/main/skills/architecture"},"layout":"multi","source":"github","category":"dotfiles","frontmatter":{"name":"architecture","license":"MIT","description":"Load before designing a new system, choosing between competing implementations, weighing tradeoffs across libraries or frameworks, or escalating an architectural question to a human. Fires at the moment a multi-option design decision appears, not during routine implementation."},"skills_sh_url":"https://skills.sh/athal7/dotfiles/architecture"},"updatedAt":"2026-05-18T19:14:33.853Z"}}