{"id":"2b23de16-1d7d-42c9-9cae-d95b07adde00","shortId":"RUMdTg","kind":"skill","title":"architecture-audit","tagline":"Explore a codebase to surface architectural friction and propose refactors toward deep modules (simple interface, large implementation) as GitHub issue RFCs. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make ","description":"# Architecture Audit\n\nA **deep module** has a simple interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the seam instead of inside. See [references/deep-modules.md](references/deep-modules.md) for examples and anti-patterns.\n\n## Glossary\n\nUse these terms exactly in every suggestion — don't drift into \"component,\" \"service,\" \"API,\" or \"boundary.\" Consistent language is the point. Full definitions in [references/language.md](references/language.md).\n\n- **Module** — anything with an interface and an implementation (function, class, package, slice).\n- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.\n- **Implementation** — the code inside.\n- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.\n- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not \"boundary.\")\n- **Adapter** — a concrete thing satisfying an interface at a seam.\n- **Leverage** — what callers get from depth.\n- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.\n\nKey principles:\n\n- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.\n- **The interface is the test surface.**\n- **One adapter = hypothetical seam. Two adapters = real seam.**\n\n## Workflow\n\n### 1. Explore\n\nUse the Agent tool with subagent_type=Explore to navigate the codebase organically. Note where you experience friction:\n\n- Understanding one concept requires bouncing between many small **modules**\n- A module's **interface** is nearly as complex as its **implementation** (shallow module)\n- Pure functions extracted just for testability, but real bugs hide in how they're called\n- Tightly-coupled modules create integration risk at the **seams** between them\n- A module fails the **deletion test** — deleting it makes complexity vanish (pass-through), or its complexity is duplicated across N callers (earning its keep but in the wrong place)\n- Areas that are untested or hard to test\n\nThe friction you encounter IS the signal.\n\n### 2. Present candidates\n\nShow a numbered list. For each candidate:\n\n- **Cluster**: which modules/concepts are involved\n- **Why they're coupled**: shared types, call patterns, co-ownership of a concept\n- **Dependency category**: see [references/dependency-categories.md](references/dependency-categories.md)\n- **Test impact**: what existing tests would be replaced by tests at the new seam\n\nDo NOT propose interfaces yet. Ask: \"Which candidate would you like to explore?\" — list each candidate as an option with its cluster name as label and coupling summary as description. Use AskUserQuestion when available; otherwise present as a numbered list.\n\n### 3. User picks a candidate\n\n### 4. Frame the problem space\n\nWrite a user-facing explanation of the chosen candidate:\n\n- Constraints any new interface must satisfy\n- Dependencies it would need to rely on\n- A rough illustrative code sketch to ground the constraints (not a proposal)\n\nShow this to the user, then immediately proceed to Step 5. User reads while sub-agents work.\n\n### 5. Design multiple interfaces\n\nSpawn 3+ sub-agents in parallel using the Agent tool. Each produces a **radically different** interface. Give each a separate technical brief (file paths, coupling details, dependency category). Assign distinct constraints:\n\n- Agent 1: \"Minimize — aim for 1–3 entry points max\"\n- Agent 2: \"Maximize flexibility — support many use cases and extension\"\n- Agent 3: \"Optimize for the most common caller — make the default case trivial\"\n- Agent 4 (if applicable): \"Design around ports & adapters for cross-boundary dependencies\"\n\nEach sub-agent outputs:\n1. Interface signature\n2. Usage example\n3. What complexity it hides internally\n4. Dependency strategy (see [references/dependency-categories.md](references/dependency-categories.md))\n5. Trade-offs\n\nPresent designs sequentially, compare in prose, then give your own recommendation. Be opinionated — if elements from multiple designs combine well, propose a hybrid.\n\n### 6. User picks an interface\n\nAsk: \"Which interface design should we use?\" — list each design as an option with preview showing the interface signature. Add \"Your recommendation\" as first option (Recommended) with the hybrid/recommended design in preview. Use AskUserQuestion when available; otherwise present as a numbered list.\n\n### 7. Write improvement PRD\n\nSave a markdown file named `architecture-<cluster-name>.md` using the template in [references/improvement-template.md](references/improvement-template.md). If `.specs/prds/` exists, save there; otherwise, save in `prds/`.\n\nFill with concrete details: file paths, function names, migration steps. Share the file path with the user when done.\n\n## Rules\n\n- Never propose an interface before the user picks a candidate (Step 3)\n- Old unit tests on shallow modules are waste once seam tests exist — note them for deletion\n- Classify every candidate's dependency type before designing interfaces\n- Show the problem space framing (Step 4) before sub-agents finish — don't wait\n- PRD must reference concrete files and functions, not abstract concepts\n- Don't introduce a new seam unless something actually varies across it (one adapter = hypothetical, two = real)\n\n## Error Handling\n\n- If exploration reveals a candidate scope much larger than expected → surface this and ask user to re-scope before proceeding","tags":["architecture","audit","agent","skills","helderberto","agent-skills","ai-tools","antigravity","claude-code","cursor","developer-tools","gemini-cli"],"capabilities":["skill","source-helderberto","skill-architecture-audit","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/architecture-audit","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 (5,708 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:11.443Z","embedding":null,"createdAt":"2026-05-18T13:14:51.349Z","updatedAt":"2026-05-18T19:09:11.443Z","lastSeenAt":"2026-05-18T19:09:11.443Z","tsv":"'1':262,564,568,614 '2':376,574,617 '3':464,532,569,584,620,763 '4':469,597,626,795 '5':519,527,632 '6':659 '7':706 'abstract':812 'across':239,350,824 'actual':822 'adapt':190,254,258,603,827 'add':683 'agent':266,525,535,540,563,573,583,596,612,799 'ai':62 'ai-navig':61 'aim':566 'alter':181 'anti':81 'anti-pattern':80 'anyth':111 'api':97 'applic':599 'architectur':2,9,31,42,715 'architecture-audit':1 'area':361 'around':601 'ask':429,664,846 'askuserquest':455,697 'assign':560 'audit':3,43 'avail':457,699 'behaviour':155,178 'behind':156 'bounc':286 'boundari':99,189,607 'brief':553 'bug':213,312 'call':318,397 'caller':125,202,241,352,590 'candid':378,385,431,439,468,483,761,782,837 'case':580,594 'categori':406,559 'chang':212 'chosen':482 'class':119 'classifi':780 'cluster':386,445 'co':400 'co-ownership':399 'code':145,500 'codebas':6,275 'combin':654 'common':589 'compar':639 'complex':167,228,237,298,340,347,622 'compon':95 'concentr':215 'concept':284,404,813 'concret':192,734,807 'config':137 'consist':100 'consolid':35 'constraint':484,505,562 'coupl':38,321,394,450,556 'creat':323 'cross':606 'cross-boundari':605 'deep':15,45,55,160 'default':593 'definit':106 'delet':221,224,335,337,779 'depend':405,490,558,608,627,784 'depth':147,205,211 'descript':453 'design':528,600,637,653,667,673,693,787 'detail':557,735 'differ':546 'distinct':561 'done':750 'drift':93 'duplic':349 'earn':244,353 'edit':183 'element':650 'encount':372 'entri':570 'error':134,831 'everi':89,781 'everyth':123 'exact':87 'exampl':78,619 'exist':413,725,775 'expect':842 'experi':280 'explan':479 'explor':4,263,271,436,834 'extens':582 'extract':306 'face':478 'fail':333 'file':554,713,736,744,808 'fill':732 'find':32 'finish':800 'first':687 'flexibl':576 'frame':470,793 'friction':10,281,370 'full':105 'function':118,305,738,810 'get':203,209 'github':22 'give':548,643 'glossari':83 'ground':503 'handl':832 'hard':366 'hide':51,313,624 'high':161 'hybrid':658 'hybrid/recommended':692 'hypothet':255,828 'illustr':499 'imagin':223 'immedi':515 'impact':411 'implement':20,54,117,143,170,301 'improv':30,708 'insid':73,146 'instead':71 'integr':324 'interfac':18,50,114,122,151,159,164,174,196,248,294,427,487,530,547,615,663,666,681,755,788 'intern':625 'introduc':816 'invari':133 'involv':390 'issu':23 'keep':246,355 'key':219 'know':127 'knowledg':214 'label':448 'languag':101 'larg':19,53 'larger':840 'let':65 'leverag':148,162,200 'like':434 'list':382,437,463,671,705 'live':175 'local':206 'lot':153 'maintain':208 'make':41,339,591 'mani':288,578 'markdown':712 'max':572 'maxim':575 'md':716 'migrat':740 'minim':565 'mode':135 'modul':16,39,46,56,110,131,226,290,292,303,322,332,769 'modules/concepts':388 'much':839 'multipl':529,652 'must':126,488,805 'n':240,351 'name':446,714,739 'navig':63,273 'near':165,296 'need':493 'never':752 'new':422,486,818 'note':277,776 'number':381,462,704 'off':635 'old':764 'one':217,253,283,826 'opinion':648 'opportun':34 'optim':585 'option':442,676,688 'order':136 'organ':276 'otherwis':458,700,728 'output':613 'ownership':401 'packag':120 'parallel':537 'pass':234,343 'pass-through':233,342 'path':555,737,745 'pattern':82,398 'pick':466,661,759 'place':177,185,218,360 'point':104,571 'port':602 'prd':709,804 'prds':731 'present':377,459,636,701 'preview':678,695 'principl':220 'problem':472,791 'proceed':516,853 'produc':543 'propos':12,426,508,656,753 'prose':641 'pure':304 'radic':545 're':317,393,850 're-scop':849 'read':521 'real':259,311,830 'reappear':238 'recommend':646,685,689 'refactor':13,33 'refer':806 'references/deep-modules.md':75,76 'references/dependency-categories.md':408,409,630,631 'references/improvement-template.md':721,722 'references/language.md':108,109 'reli':495 'replac':417 'requir':285 'reveal':835 'rfcs':24 'risk':325 'rough':498 'rule':751 'satisfi':194,489 'save':710,726,729 'scope':838,851 'seam':70,171,199,256,260,328,423,773,819 'see':74,407,629 'separ':551 'sequenti':638 'servic':96 'shallow':163,302,768 'share':395,742 'show':379,509,679,789 'signal':375 'signatur':142,616,682 'simpl':17,49 'sketch':501 'skill' 'skill-architecture-audit' 'slice':121 'small':158,289 'someth':821 'source-helderberto' 'space':473,792 'spawn':531 'specs/prds':724 'step':518,741,762,794 'strategi':628 'sub':524,534,611,798 'sub-ag':523,533,610,797 'subag':269 'suggest':90 'summari':451 'support':577 'surfac':8,252,843 'technic':552 'templat':719 'term':86 'test':67,222,251,336,368,410,414,419,766,774 'testabl':59,309 'thing':193 'tight':37,320 'tightly-coupl':36,319 'tool':267,541 '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' 'toward':14 'trade':634 'trade-off':633 'trivial':595 'two':257,829 'type':132,141,270,396,785 'understand':282 'unit':765 'unless':820 'untest':364 'usag':618 'use':25,84,129,186,264,454,538,579,670,696,717 'user':27,465,477,513,520,660,748,758,847 'user-fac':476 'vanish':229,341 'vari':823 'wait':803 'want':28 'wast':771 'well':655 'without':182 'work':526 'workflow':261 'would':415,432,492 'write':474,707 'wrong':359 'yet':428","prices":[{"id":"ca1d2aea-5fc7-4bd8-94d7-943fa2c4c1f3","listingId":"2b23de16-1d7d-42c9-9cae-d95b07adde00","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:51.349Z"}],"sources":[{"listingId":"2b23de16-1d7d-42c9-9cae-d95b07adde00","source":"github","sourceId":"helderberto/agent-skills/architecture-audit","sourceUrl":"https://github.com/helderberto/agent-skills/tree/main/skills/architecture-audit","isPrimary":false,"firstSeenAt":"2026-05-18T13:14:51.349Z","lastSeenAt":"2026-05-18T19:09:11.443Z"}],"details":{"listingId":"2b23de16-1d7d-42c9-9cae-d95b07adde00","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"helderberto","slug":"architecture-audit","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":"e3194e6e9fb6ea312ba58aa05fc9b78c7d1ace90","skill_md_path":"skills/architecture-audit/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/helderberto/agent-skills/tree/main/skills/architecture-audit"},"layout":"multi","source":"github","category":"agent-skills","frontmatter":{"name":"architecture-audit","description":"Explore a codebase to surface architectural friction and propose refactors toward deep modules (simple interface, large implementation) as GitHub issue RFCs. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Don't use for small one-off refactors or single-file cleanups."},"skills_sh_url":"https://skills.sh/helderberto/agent-skills/architecture-audit"},"updatedAt":"2026-05-18T19:09:11.443Z"}}