[{"data":1,"prerenderedAt":1908},["ShallowReactive",2],{"blog-matt-pocock-improve-codebase-architecture":3},{"_path":4,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":8,"description":9,"publishedAt":10,"tags":11,"body":17,"_type":1902,"_id":1903,"_source":1904,"_file":1905,"_stem":1906,"_extension":1907},"\u002Fblog\u002Fmatt-pocock-improve-codebase-architecture","blog",false,"","The Most Underrated Agent Skill: How Matt Pocock's `improve-codebase-architecture` Cures Shallow Codebases","Why AI coding agents naturally produce shallow, fragmented abstractions, and how Matt Pocock's `improve-codebase-architecture` skill uses deep modules and visual reports to restore engineering leverage.","2026-09-12",[12,13,14,15,16],"AI Agents","Claude Code","Software Architecture","Refactoring","Developer Tools",{"type":18,"children":19,"toc":1888},"root",[20,45,50,55,67,91,95,102,121,160,169,174,224,227,233,238,245,920,925,965,971,983,1381,1386,1416,1419,1431,1443,1451,1456,1459,1465,1470,1482,1557,1560,1566,1571,1587,1606,1691,1712,1715,1721,1741,1746,1764,1769,1808,1811,1817,1822,1833,1838,1856,1861,1877,1882],{"type":21,"tag":22,"props":23,"children":24},"element","p",{},[25,28,35,37,43],{"type":26,"value":27},"text","Even when you move past raw \"vibe coding\" and enforce rigorous practices like test-driven development and dual-axis code reviews (as explored in our ",{"type":21,"tag":29,"props":30,"children":32},"a",{"href":31},"\u002Fblog\u002Fmatt-pocock-claude-code-skills-beyond-vibe-coding",[33],{"type":26,"value":34},"deep dive on Matt Pocock's Claude Code skills",{"type":26,"value":36},"), an insidious problem often creeps into agent-maintained projects: ",{"type":21,"tag":38,"props":39,"children":40},"strong",{},[41],{"type":26,"value":42},"architectural sprawl",{"type":26,"value":44},".",{"type":21,"tag":22,"props":46,"children":47},{},[48],{"type":26,"value":49},"Your tests are green. Your linting is spotless. Yet every time you prompt your agent to make a change, you find it bouncing between twelve different single-purpose files, anemic utility classes, and paper-thin wrappers that do little more than hand off parameters.",{"type":21,"tag":22,"props":51,"children":52},{},[53],{"type":26,"value":54},"What went wrong?",{"type":21,"tag":22,"props":56,"children":57},{},[58,60,65],{"type":26,"value":59},"Without architectural guidance, AI agents naturally default to ",{"type":21,"tag":38,"props":61,"children":62},{},[63],{"type":26,"value":64},"shallow modules",{"type":26,"value":66},". They create tiny classes and functions to satisfy local test requirements without considering holistic system design.",{"type":21,"tag":22,"props":68,"children":69},{},[70,72,89],{"type":26,"value":71},"That is why ",{"type":21,"tag":29,"props":73,"children":77},{"href":74,"rel":75},"https:\u002F\u002Fgithub.com\u002Fmattpocock\u002Fskills",[76],"nofollow",[78,80,87],{"type":26,"value":79},"Matt Pocock's ",{"type":21,"tag":81,"props":82,"children":84},"code",{"className":83},[],[85],{"type":26,"value":86},"improve-codebase-architecture",{"type":26,"value":88}," skill",{"type":26,"value":90}," is quietly the most powerful, underrated tool in the entire suite. It doesn't just check your code—it audits the structural geometry of your codebase, visualizes deepening opportunities in your browser, and guides you through eliminating architectural friction.",{"type":21,"tag":92,"props":93,"children":94},"hr",{},[],{"type":21,"tag":96,"props":97,"children":99},"h2",{"id":98},"the-shallow-module-trap-in-the-age-of-ai",[100],{"type":26,"value":101},"The Shallow Module Trap in the Age of AI",{"type":21,"tag":22,"props":103,"children":104},{},[105,107,113,115,120],{"type":26,"value":106},"In ",{"type":21,"tag":108,"props":109,"children":110},"em",{},[111],{"type":26,"value":112},"A Philosophy of Software Design",{"type":26,"value":114},", John Ousterhout introduced a foundational distinction that has become essential for developers working alongside AI: ",{"type":21,"tag":38,"props":116,"children":117},{},[118],{"type":26,"value":119},"Deep vs. Shallow modules",{"type":26,"value":44},{"type":21,"tag":122,"props":123,"children":124},"ul",{},[125,136],{"type":21,"tag":126,"props":127,"children":128},"li",{},[129,134],{"type":21,"tag":38,"props":130,"children":131},{},[132],{"type":26,"value":133},"Shallow Module",{"type":26,"value":135},": Has a wide, complex interface relative to its implementation. It requires callers to learn many methods and juggle intricate parameters, but contains almost no real behavior—frequently acting as a glorified pass-through.",{"type":21,"tag":126,"props":137,"children":138},{},[139,144,146,151,153,158],{"type":21,"tag":38,"props":140,"children":141},{},[142],{"type":26,"value":143},"Deep Module",{"type":26,"value":145},": Has a tiny, simple interface concealing rich internal complexity and robust invariants. It maximizes ",{"type":21,"tag":38,"props":147,"children":148},{},[149],{"type":26,"value":150},"leverage",{"type":26,"value":152}," for the caller and concentrates ",{"type":21,"tag":38,"props":154,"children":155},{},[156],{"type":26,"value":157},"locality",{"type":26,"value":159}," for the maintainer.",{"type":21,"tag":161,"props":162,"children":164},"pre",{"code":163},"┌─────────────────────────────────┐       ┌─────────────────────┐\n│       Large Interface           │       │   Small Interface   │  ← Few methods, simple params\n├─────────────────────────────────┤       ├─────────────────────┤\n│  Thin Implementation            │       │                     │\n└─────────────────────────────────┘       │  Deep Implementation│  ← Complexity hidden & tested\n       (Shallow Module)                   │                     │\n    High cognitive overhead,              └─────────────────────┘\n     brittle caller coupling                   (Deep Module)\n                                            Maximum caller leverage\n",[165],{"type":21,"tag":81,"props":166,"children":167},{"__ignoreMap":7},[168],{"type":26,"value":163},{"type":21,"tag":22,"props":170,"children":171},{},[172],{"type":26,"value":173},"Why do AI agents generate shallow modules by default?",{"type":21,"tag":175,"props":176,"children":177},"ol",{},[178,204,214],{"type":21,"tag":126,"props":179,"children":180},{},[181,186,188,194,196,202],{"type":21,"tag":38,"props":182,"children":183},{},[184],{"type":26,"value":185},"Path of least resistance",{"type":26,"value":187},": When an agent is prompted to add a capability, creating a new helper file (",{"type":21,"tag":81,"props":189,"children":191},{"className":190},[],[192],{"type":26,"value":193},"UserValidationHelper.ts",{"type":26,"value":195},", ",{"type":21,"tag":81,"props":197,"children":199},{"className":198},[],[200],{"type":26,"value":201},"OrderStatusCoordinator.ts",{"type":26,"value":203},") carries zero risk of breaking existing tests in neighboring files.",{"type":21,"tag":126,"props":205,"children":206},{},[207,212],{"type":21,"tag":38,"props":208,"children":209},{},[210],{"type":26,"value":211},"Mock-driven rot",{"type":26,"value":213},": When developers insist on unit testing in isolation, agents slice logic into hyper-granular units so they can mock every side effect. The result is a sprawling web of interfaces where the real bugs hide in the glue code between them.",{"type":21,"tag":126,"props":215,"children":216},{},[217,222],{"type":21,"tag":38,"props":218,"children":219},{},[220],{"type":26,"value":221},"Context window degradation",{"type":26,"value":223},": As shallow modules proliferate, future agent sessions become exponentially more expensive and error-prone. The agent must consume thousands of tokens jumping across fragmented files just to understand one cohesive business flow.",{"type":21,"tag":92,"props":225,"children":226},{},[],{"type":21,"tag":96,"props":228,"children":230},{"id":229},"deep-vs-shallow-in-practice",[231],{"type":26,"value":232},"Deep vs. Shallow in Practice",{"type":21,"tag":22,"props":234,"children":235},{},[236],{"type":26,"value":237},"Consider how an e-commerce checkout flow commonly evolves under unguided agent development:",{"type":21,"tag":239,"props":240,"children":242},"h3",{"id":241},"the-shallow-architecture-high-friction-low-locality",[243],{"type":26,"value":244},"The Shallow Architecture (High Friction, Low Locality)",{"type":21,"tag":161,"props":246,"children":250},{"code":247,"language":248,"meta":7,"className":249,"style":7},"\u002F\u002F Callers must coordinate 4 distinct shallow services and know the precise order of execution\nexport class CheckoutController {\n  constructor(\n    private validator: CartValidator,\n    private taxCalculator: TaxCalculator,\n    private inventoryReservation: InventoryReservationService,\n    private paymentProcessor: PaymentGatewayAdapter,\n    private orderRepo: OrderRepository\n  ) {}\n\n  async checkout(cartId: string, customerId: string, paymentToken: string) {\n    const cart = await this.orderRepo.getCart(cartId);\n    if (!this.validator.isValid(cart)) throw new Error(\"Invalid cart\");\n\n    const tax = await this.taxCalculator.calculate(cart.items, customerId);\n    const reservation = await this.inventoryReservation.reserve(cart.items);\n\n    try {\n      const charge = await this.paymentProcessor.charge(cart.total + tax, paymentToken);\n      return await this.orderRepo.createOrder(cart, charge.id);\n    } catch (err) {\n      await this.inventoryReservation.release(reservation.id);\n      throw err;\n    }\n  }\n}\n","typescript","language-typescript shiki shiki-themes github-light github-dark",[251],{"type":21,"tag":81,"props":252,"children":253},{"__ignoreMap":7},[254,266,293,307,337,363,389,415,437,446,456,529,573,642,650,690,730,738,751,802,833,852,879,893,902,911],{"type":21,"tag":255,"props":256,"children":259},"span",{"class":257,"line":258},"line",1,[260],{"type":21,"tag":255,"props":261,"children":263},{"style":262},"--shiki-default:#6A737D;--shiki-dark:#6A737D",[264],{"type":26,"value":265},"\u002F\u002F Callers must coordinate 4 distinct shallow services and know the precise order of execution\n",{"type":21,"tag":255,"props":267,"children":269},{"class":257,"line":268},2,[270,276,281,287],{"type":21,"tag":255,"props":271,"children":273},{"style":272},"--shiki-default:#D73A49;--shiki-dark:#F97583",[274],{"type":26,"value":275},"export",{"type":21,"tag":255,"props":277,"children":278},{"style":272},[279],{"type":26,"value":280}," class",{"type":21,"tag":255,"props":282,"children":284},{"style":283},"--shiki-default:#6F42C1;--shiki-dark:#B392F0",[285],{"type":26,"value":286}," CheckoutController",{"type":21,"tag":255,"props":288,"children":290},{"style":289},"--shiki-default:#24292E;--shiki-dark:#E1E4E8",[291],{"type":26,"value":292}," {\n",{"type":21,"tag":255,"props":294,"children":296},{"class":257,"line":295},3,[297,302],{"type":21,"tag":255,"props":298,"children":299},{"style":272},[300],{"type":26,"value":301},"  constructor",{"type":21,"tag":255,"props":303,"children":304},{"style":289},[305],{"type":26,"value":306},"(\n",{"type":21,"tag":255,"props":308,"children":310},{"class":257,"line":309},4,[311,316,322,327,332],{"type":21,"tag":255,"props":312,"children":313},{"style":272},[314],{"type":26,"value":315},"    private",{"type":21,"tag":255,"props":317,"children":319},{"style":318},"--shiki-default:#E36209;--shiki-dark:#FFAB70",[320],{"type":26,"value":321}," validator",{"type":21,"tag":255,"props":323,"children":324},{"style":272},[325],{"type":26,"value":326},":",{"type":21,"tag":255,"props":328,"children":329},{"style":283},[330],{"type":26,"value":331}," CartValidator",{"type":21,"tag":255,"props":333,"children":334},{"style":289},[335],{"type":26,"value":336},",\n",{"type":21,"tag":255,"props":338,"children":340},{"class":257,"line":339},5,[341,345,350,354,359],{"type":21,"tag":255,"props":342,"children":343},{"style":272},[344],{"type":26,"value":315},{"type":21,"tag":255,"props":346,"children":347},{"style":318},[348],{"type":26,"value":349}," taxCalculator",{"type":21,"tag":255,"props":351,"children":352},{"style":272},[353],{"type":26,"value":326},{"type":21,"tag":255,"props":355,"children":356},{"style":283},[357],{"type":26,"value":358}," TaxCalculator",{"type":21,"tag":255,"props":360,"children":361},{"style":289},[362],{"type":26,"value":336},{"type":21,"tag":255,"props":364,"children":366},{"class":257,"line":365},6,[367,371,376,380,385],{"type":21,"tag":255,"props":368,"children":369},{"style":272},[370],{"type":26,"value":315},{"type":21,"tag":255,"props":372,"children":373},{"style":318},[374],{"type":26,"value":375}," inventoryReservation",{"type":21,"tag":255,"props":377,"children":378},{"style":272},[379],{"type":26,"value":326},{"type":21,"tag":255,"props":381,"children":382},{"style":283},[383],{"type":26,"value":384}," InventoryReservationService",{"type":21,"tag":255,"props":386,"children":387},{"style":289},[388],{"type":26,"value":336},{"type":21,"tag":255,"props":390,"children":392},{"class":257,"line":391},7,[393,397,402,406,411],{"type":21,"tag":255,"props":394,"children":395},{"style":272},[396],{"type":26,"value":315},{"type":21,"tag":255,"props":398,"children":399},{"style":318},[400],{"type":26,"value":401}," paymentProcessor",{"type":21,"tag":255,"props":403,"children":404},{"style":272},[405],{"type":26,"value":326},{"type":21,"tag":255,"props":407,"children":408},{"style":283},[409],{"type":26,"value":410}," PaymentGatewayAdapter",{"type":21,"tag":255,"props":412,"children":413},{"style":289},[414],{"type":26,"value":336},{"type":21,"tag":255,"props":416,"children":418},{"class":257,"line":417},8,[419,423,428,432],{"type":21,"tag":255,"props":420,"children":421},{"style":272},[422],{"type":26,"value":315},{"type":21,"tag":255,"props":424,"children":425},{"style":318},[426],{"type":26,"value":427}," orderRepo",{"type":21,"tag":255,"props":429,"children":430},{"style":272},[431],{"type":26,"value":326},{"type":21,"tag":255,"props":433,"children":434},{"style":283},[435],{"type":26,"value":436}," OrderRepository\n",{"type":21,"tag":255,"props":438,"children":440},{"class":257,"line":439},9,[441],{"type":21,"tag":255,"props":442,"children":443},{"style":289},[444],{"type":26,"value":445},"  ) {}\n",{"type":21,"tag":255,"props":447,"children":449},{"class":257,"line":448},10,[450],{"type":21,"tag":255,"props":451,"children":453},{"emptyLinePlaceholder":452},true,[454],{"type":26,"value":455},"\n",{"type":21,"tag":255,"props":457,"children":459},{"class":257,"line":458},11,[460,465,470,475,480,484,490,494,499,503,507,511,516,520,524],{"type":21,"tag":255,"props":461,"children":462},{"style":272},[463],{"type":26,"value":464},"  async",{"type":21,"tag":255,"props":466,"children":467},{"style":283},[468],{"type":26,"value":469}," checkout",{"type":21,"tag":255,"props":471,"children":472},{"style":289},[473],{"type":26,"value":474},"(",{"type":21,"tag":255,"props":476,"children":477},{"style":318},[478],{"type":26,"value":479},"cartId",{"type":21,"tag":255,"props":481,"children":482},{"style":272},[483],{"type":26,"value":326},{"type":21,"tag":255,"props":485,"children":487},{"style":486},"--shiki-default:#005CC5;--shiki-dark:#79B8FF",[488],{"type":26,"value":489}," string",{"type":21,"tag":255,"props":491,"children":492},{"style":289},[493],{"type":26,"value":195},{"type":21,"tag":255,"props":495,"children":496},{"style":318},[497],{"type":26,"value":498},"customerId",{"type":21,"tag":255,"props":500,"children":501},{"style":272},[502],{"type":26,"value":326},{"type":21,"tag":255,"props":504,"children":505},{"style":486},[506],{"type":26,"value":489},{"type":21,"tag":255,"props":508,"children":509},{"style":289},[510],{"type":26,"value":195},{"type":21,"tag":255,"props":512,"children":513},{"style":318},[514],{"type":26,"value":515},"paymentToken",{"type":21,"tag":255,"props":517,"children":518},{"style":272},[519],{"type":26,"value":326},{"type":21,"tag":255,"props":521,"children":522},{"style":486},[523],{"type":26,"value":489},{"type":21,"tag":255,"props":525,"children":526},{"style":289},[527],{"type":26,"value":528},") {\n",{"type":21,"tag":255,"props":530,"children":532},{"class":257,"line":531},12,[533,538,543,548,553,558,563,568],{"type":21,"tag":255,"props":534,"children":535},{"style":272},[536],{"type":26,"value":537},"    const",{"type":21,"tag":255,"props":539,"children":540},{"style":486},[541],{"type":26,"value":542}," cart",{"type":21,"tag":255,"props":544,"children":545},{"style":272},[546],{"type":26,"value":547}," =",{"type":21,"tag":255,"props":549,"children":550},{"style":272},[551],{"type":26,"value":552}," await",{"type":21,"tag":255,"props":554,"children":555},{"style":486},[556],{"type":26,"value":557}," this",{"type":21,"tag":255,"props":559,"children":560},{"style":289},[561],{"type":26,"value":562},".orderRepo.",{"type":21,"tag":255,"props":564,"children":565},{"style":283},[566],{"type":26,"value":567},"getCart",{"type":21,"tag":255,"props":569,"children":570},{"style":289},[571],{"type":26,"value":572},"(cartId);\n",{"type":21,"tag":255,"props":574,"children":576},{"class":257,"line":575},13,[577,582,587,592,597,602,607,612,617,622,627,631,637],{"type":21,"tag":255,"props":578,"children":579},{"style":272},[580],{"type":26,"value":581},"    if",{"type":21,"tag":255,"props":583,"children":584},{"style":289},[585],{"type":26,"value":586}," (",{"type":21,"tag":255,"props":588,"children":589},{"style":272},[590],{"type":26,"value":591},"!",{"type":21,"tag":255,"props":593,"children":594},{"style":486},[595],{"type":26,"value":596},"this",{"type":21,"tag":255,"props":598,"children":599},{"style":289},[600],{"type":26,"value":601},".validator.",{"type":21,"tag":255,"props":603,"children":604},{"style":283},[605],{"type":26,"value":606},"isValid",{"type":21,"tag":255,"props":608,"children":609},{"style":289},[610],{"type":26,"value":611},"(cart)) ",{"type":21,"tag":255,"props":613,"children":614},{"style":272},[615],{"type":26,"value":616},"throw",{"type":21,"tag":255,"props":618,"children":619},{"style":272},[620],{"type":26,"value":621}," new",{"type":21,"tag":255,"props":623,"children":624},{"style":283},[625],{"type":26,"value":626}," Error",{"type":21,"tag":255,"props":628,"children":629},{"style":289},[630],{"type":26,"value":474},{"type":21,"tag":255,"props":632,"children":634},{"style":633},"--shiki-default:#032F62;--shiki-dark:#9ECBFF",[635],{"type":26,"value":636},"\"Invalid cart\"",{"type":21,"tag":255,"props":638,"children":639},{"style":289},[640],{"type":26,"value":641},");\n",{"type":21,"tag":255,"props":643,"children":645},{"class":257,"line":644},14,[646],{"type":21,"tag":255,"props":647,"children":648},{"emptyLinePlaceholder":452},[649],{"type":26,"value":455},{"type":21,"tag":255,"props":651,"children":653},{"class":257,"line":652},15,[654,658,663,667,671,675,680,685],{"type":21,"tag":255,"props":655,"children":656},{"style":272},[657],{"type":26,"value":537},{"type":21,"tag":255,"props":659,"children":660},{"style":486},[661],{"type":26,"value":662}," tax",{"type":21,"tag":255,"props":664,"children":665},{"style":272},[666],{"type":26,"value":547},{"type":21,"tag":255,"props":668,"children":669},{"style":272},[670],{"type":26,"value":552},{"type":21,"tag":255,"props":672,"children":673},{"style":486},[674],{"type":26,"value":557},{"type":21,"tag":255,"props":676,"children":677},{"style":289},[678],{"type":26,"value":679},".taxCalculator.",{"type":21,"tag":255,"props":681,"children":682},{"style":283},[683],{"type":26,"value":684},"calculate",{"type":21,"tag":255,"props":686,"children":687},{"style":289},[688],{"type":26,"value":689},"(cart.items, customerId);\n",{"type":21,"tag":255,"props":691,"children":693},{"class":257,"line":692},16,[694,698,703,707,711,715,720,725],{"type":21,"tag":255,"props":695,"children":696},{"style":272},[697],{"type":26,"value":537},{"type":21,"tag":255,"props":699,"children":700},{"style":486},[701],{"type":26,"value":702}," reservation",{"type":21,"tag":255,"props":704,"children":705},{"style":272},[706],{"type":26,"value":547},{"type":21,"tag":255,"props":708,"children":709},{"style":272},[710],{"type":26,"value":552},{"type":21,"tag":255,"props":712,"children":713},{"style":486},[714],{"type":26,"value":557},{"type":21,"tag":255,"props":716,"children":717},{"style":289},[718],{"type":26,"value":719},".inventoryReservation.",{"type":21,"tag":255,"props":721,"children":722},{"style":283},[723],{"type":26,"value":724},"reserve",{"type":21,"tag":255,"props":726,"children":727},{"style":289},[728],{"type":26,"value":729},"(cart.items);\n",{"type":21,"tag":255,"props":731,"children":733},{"class":257,"line":732},17,[734],{"type":21,"tag":255,"props":735,"children":736},{"emptyLinePlaceholder":452},[737],{"type":26,"value":455},{"type":21,"tag":255,"props":739,"children":741},{"class":257,"line":740},18,[742,747],{"type":21,"tag":255,"props":743,"children":744},{"style":272},[745],{"type":26,"value":746},"    try",{"type":21,"tag":255,"props":748,"children":749},{"style":289},[750],{"type":26,"value":292},{"type":21,"tag":255,"props":752,"children":754},{"class":257,"line":753},19,[755,760,765,769,773,777,782,787,792,797],{"type":21,"tag":255,"props":756,"children":757},{"style":272},[758],{"type":26,"value":759},"      const",{"type":21,"tag":255,"props":761,"children":762},{"style":486},[763],{"type":26,"value":764}," charge",{"type":21,"tag":255,"props":766,"children":767},{"style":272},[768],{"type":26,"value":547},{"type":21,"tag":255,"props":770,"children":771},{"style":272},[772],{"type":26,"value":552},{"type":21,"tag":255,"props":774,"children":775},{"style":486},[776],{"type":26,"value":557},{"type":21,"tag":255,"props":778,"children":779},{"style":289},[780],{"type":26,"value":781},".paymentProcessor.",{"type":21,"tag":255,"props":783,"children":784},{"style":283},[785],{"type":26,"value":786},"charge",{"type":21,"tag":255,"props":788,"children":789},{"style":289},[790],{"type":26,"value":791},"(cart.total ",{"type":21,"tag":255,"props":793,"children":794},{"style":272},[795],{"type":26,"value":796},"+",{"type":21,"tag":255,"props":798,"children":799},{"style":289},[800],{"type":26,"value":801}," tax, paymentToken);\n",{"type":21,"tag":255,"props":803,"children":805},{"class":257,"line":804},20,[806,811,815,819,823,828],{"type":21,"tag":255,"props":807,"children":808},{"style":272},[809],{"type":26,"value":810},"      return",{"type":21,"tag":255,"props":812,"children":813},{"style":272},[814],{"type":26,"value":552},{"type":21,"tag":255,"props":816,"children":817},{"style":486},[818],{"type":26,"value":557},{"type":21,"tag":255,"props":820,"children":821},{"style":289},[822],{"type":26,"value":562},{"type":21,"tag":255,"props":824,"children":825},{"style":283},[826],{"type":26,"value":827},"createOrder",{"type":21,"tag":255,"props":829,"children":830},{"style":289},[831],{"type":26,"value":832},"(cart, charge.id);\n",{"type":21,"tag":255,"props":834,"children":836},{"class":257,"line":835},21,[837,842,847],{"type":21,"tag":255,"props":838,"children":839},{"style":289},[840],{"type":26,"value":841},"    } ",{"type":21,"tag":255,"props":843,"children":844},{"style":272},[845],{"type":26,"value":846},"catch",{"type":21,"tag":255,"props":848,"children":849},{"style":289},[850],{"type":26,"value":851}," (err) {\n",{"type":21,"tag":255,"props":853,"children":855},{"class":257,"line":854},22,[856,861,865,869,874],{"type":21,"tag":255,"props":857,"children":858},{"style":272},[859],{"type":26,"value":860},"      await",{"type":21,"tag":255,"props":862,"children":863},{"style":486},[864],{"type":26,"value":557},{"type":21,"tag":255,"props":866,"children":867},{"style":289},[868],{"type":26,"value":719},{"type":21,"tag":255,"props":870,"children":871},{"style":283},[872],{"type":26,"value":873},"release",{"type":21,"tag":255,"props":875,"children":876},{"style":289},[877],{"type":26,"value":878},"(reservation.id);\n",{"type":21,"tag":255,"props":880,"children":882},{"class":257,"line":881},23,[883,888],{"type":21,"tag":255,"props":884,"children":885},{"style":272},[886],{"type":26,"value":887},"      throw",{"type":21,"tag":255,"props":889,"children":890},{"style":289},[891],{"type":26,"value":892}," err;\n",{"type":21,"tag":255,"props":894,"children":896},{"class":257,"line":895},24,[897],{"type":21,"tag":255,"props":898,"children":899},{"style":289},[900],{"type":26,"value":901},"    }\n",{"type":21,"tag":255,"props":903,"children":905},{"class":257,"line":904},25,[906],{"type":21,"tag":255,"props":907,"children":908},{"style":289},[909],{"type":26,"value":910},"  }\n",{"type":21,"tag":255,"props":912,"children":914},{"class":257,"line":913},26,[915],{"type":21,"tag":255,"props":916,"children":917},{"style":289},[918],{"type":26,"value":919},"}\n",{"type":21,"tag":22,"props":921,"children":922},{},[923],{"type":26,"value":924},"Notice the architectural defects:",{"type":21,"tag":122,"props":926,"children":927},{},[928,933,946],{"type":21,"tag":126,"props":929,"children":930},{},[931],{"type":26,"value":932},"The controller is acting as an ad-hoc workflow engine because the underlying domain modules are paper-thin.",{"type":21,"tag":126,"props":934,"children":935},{},[936,938,944],{"type":26,"value":937},"Testing ",{"type":21,"tag":81,"props":939,"children":941},{"className":940},[],[942],{"type":26,"value":943},"CheckoutController",{"type":26,"value":945}," requires mocking four separate collaborators.",{"type":21,"tag":126,"props":947,"children":948},{},[949,951,956,958,963],{"type":26,"value":950},"If you apply Michael Feathers’ ",{"type":21,"tag":38,"props":952,"children":953},{},[954],{"type":26,"value":955},"deletion test",{"type":26,"value":957}," (\"",{"type":21,"tag":108,"props":959,"children":960},{},[961],{"type":26,"value":962},"If I delete this module, does complexity vanish or reappear across callers?",{"type":26,"value":964},"\"), deleting any of these helpers simply moves the boilerplate straight back to the caller.",{"type":21,"tag":239,"props":966,"children":968},{"id":967},"the-deep-architecture-high-leverage-single-seam",[969],{"type":26,"value":970},"The Deep Architecture (High Leverage, Single Seam)",{"type":21,"tag":22,"props":972,"children":973},{},[974,976,981],{"type":26,"value":975},"Refactoring this into a ",{"type":21,"tag":38,"props":977,"children":978},{},[979],{"type":26,"value":980},"deep module",{"type":26,"value":982}," radically simplifies the system:",{"type":21,"tag":161,"props":984,"children":986},{"code":985,"language":248,"meta":7,"className":249,"style":7},"export interface OrderPlacement {\n  placeOrder(input: {\n    cartId: string;\n    customerId: string;\n    paymentToken: string;\n  }): Promise\u003COrderResult>;\n}\n\n\u002F\u002F All inventory holds, tax rules, payment handshakes, and rollbacks\n\u002F\u002F are hidden behind a single seam that callers—and tests—cross.\nexport class OrderService implements OrderPlacement {\n  constructor(\n    private db: DatabasePool,\n    private paymentGateway: PaymentGateway\n  ) {}\n\n  async placeOrder(input: { cartId: string; customerId: string; paymentToken: string }): Promise\u003COrderResult> {\n    \u002F\u002F Cohesive transactional implementation with automatic rollback & locality\n  }\n}\n",[987],{"type":21,"tag":81,"props":988,"children":989},{"__ignoreMap":7},[990,1011,1036,1057,1077,1097,1129,1136,1143,1151,1159,1188,1199,1224,1245,1252,1259,1359,1367,1374],{"type":21,"tag":255,"props":991,"children":992},{"class":257,"line":258},[993,997,1002,1007],{"type":21,"tag":255,"props":994,"children":995},{"style":272},[996],{"type":26,"value":275},{"type":21,"tag":255,"props":998,"children":999},{"style":272},[1000],{"type":26,"value":1001}," interface",{"type":21,"tag":255,"props":1003,"children":1004},{"style":283},[1005],{"type":26,"value":1006}," OrderPlacement",{"type":21,"tag":255,"props":1008,"children":1009},{"style":289},[1010],{"type":26,"value":292},{"type":21,"tag":255,"props":1012,"children":1013},{"class":257,"line":268},[1014,1019,1023,1028,1032],{"type":21,"tag":255,"props":1015,"children":1016},{"style":283},[1017],{"type":26,"value":1018},"  placeOrder",{"type":21,"tag":255,"props":1020,"children":1021},{"style":289},[1022],{"type":26,"value":474},{"type":21,"tag":255,"props":1024,"children":1025},{"style":318},[1026],{"type":26,"value":1027},"input",{"type":21,"tag":255,"props":1029,"children":1030},{"style":272},[1031],{"type":26,"value":326},{"type":21,"tag":255,"props":1033,"children":1034},{"style":289},[1035],{"type":26,"value":292},{"type":21,"tag":255,"props":1037,"children":1038},{"class":257,"line":295},[1039,1044,1048,1052],{"type":21,"tag":255,"props":1040,"children":1041},{"style":318},[1042],{"type":26,"value":1043},"    cartId",{"type":21,"tag":255,"props":1045,"children":1046},{"style":272},[1047],{"type":26,"value":326},{"type":21,"tag":255,"props":1049,"children":1050},{"style":486},[1051],{"type":26,"value":489},{"type":21,"tag":255,"props":1053,"children":1054},{"style":289},[1055],{"type":26,"value":1056},";\n",{"type":21,"tag":255,"props":1058,"children":1059},{"class":257,"line":309},[1060,1065,1069,1073],{"type":21,"tag":255,"props":1061,"children":1062},{"style":318},[1063],{"type":26,"value":1064},"    customerId",{"type":21,"tag":255,"props":1066,"children":1067},{"style":272},[1068],{"type":26,"value":326},{"type":21,"tag":255,"props":1070,"children":1071},{"style":486},[1072],{"type":26,"value":489},{"type":21,"tag":255,"props":1074,"children":1075},{"style":289},[1076],{"type":26,"value":1056},{"type":21,"tag":255,"props":1078,"children":1079},{"class":257,"line":339},[1080,1085,1089,1093],{"type":21,"tag":255,"props":1081,"children":1082},{"style":318},[1083],{"type":26,"value":1084},"    paymentToken",{"type":21,"tag":255,"props":1086,"children":1087},{"style":272},[1088],{"type":26,"value":326},{"type":21,"tag":255,"props":1090,"children":1091},{"style":486},[1092],{"type":26,"value":489},{"type":21,"tag":255,"props":1094,"children":1095},{"style":289},[1096],{"type":26,"value":1056},{"type":21,"tag":255,"props":1098,"children":1099},{"class":257,"line":365},[1100,1105,1109,1114,1119,1124],{"type":21,"tag":255,"props":1101,"children":1102},{"style":289},[1103],{"type":26,"value":1104},"  })",{"type":21,"tag":255,"props":1106,"children":1107},{"style":272},[1108],{"type":26,"value":326},{"type":21,"tag":255,"props":1110,"children":1111},{"style":283},[1112],{"type":26,"value":1113}," Promise",{"type":21,"tag":255,"props":1115,"children":1116},{"style":289},[1117],{"type":26,"value":1118},"\u003C",{"type":21,"tag":255,"props":1120,"children":1121},{"style":283},[1122],{"type":26,"value":1123},"OrderResult",{"type":21,"tag":255,"props":1125,"children":1126},{"style":289},[1127],{"type":26,"value":1128},">;\n",{"type":21,"tag":255,"props":1130,"children":1131},{"class":257,"line":391},[1132],{"type":21,"tag":255,"props":1133,"children":1134},{"style":289},[1135],{"type":26,"value":919},{"type":21,"tag":255,"props":1137,"children":1138},{"class":257,"line":417},[1139],{"type":21,"tag":255,"props":1140,"children":1141},{"emptyLinePlaceholder":452},[1142],{"type":26,"value":455},{"type":21,"tag":255,"props":1144,"children":1145},{"class":257,"line":439},[1146],{"type":21,"tag":255,"props":1147,"children":1148},{"style":262},[1149],{"type":26,"value":1150},"\u002F\u002F All inventory holds, tax rules, payment handshakes, and rollbacks\n",{"type":21,"tag":255,"props":1152,"children":1153},{"class":257,"line":448},[1154],{"type":21,"tag":255,"props":1155,"children":1156},{"style":262},[1157],{"type":26,"value":1158},"\u002F\u002F are hidden behind a single seam that callers—and tests—cross.\n",{"type":21,"tag":255,"props":1160,"children":1161},{"class":257,"line":458},[1162,1166,1170,1175,1180,1184],{"type":21,"tag":255,"props":1163,"children":1164},{"style":272},[1165],{"type":26,"value":275},{"type":21,"tag":255,"props":1167,"children":1168},{"style":272},[1169],{"type":26,"value":280},{"type":21,"tag":255,"props":1171,"children":1172},{"style":283},[1173],{"type":26,"value":1174}," OrderService",{"type":21,"tag":255,"props":1176,"children":1177},{"style":272},[1178],{"type":26,"value":1179}," implements",{"type":21,"tag":255,"props":1181,"children":1182},{"style":283},[1183],{"type":26,"value":1006},{"type":21,"tag":255,"props":1185,"children":1186},{"style":289},[1187],{"type":26,"value":292},{"type":21,"tag":255,"props":1189,"children":1190},{"class":257,"line":531},[1191,1195],{"type":21,"tag":255,"props":1192,"children":1193},{"style":272},[1194],{"type":26,"value":301},{"type":21,"tag":255,"props":1196,"children":1197},{"style":289},[1198],{"type":26,"value":306},{"type":21,"tag":255,"props":1200,"children":1201},{"class":257,"line":575},[1202,1206,1211,1215,1220],{"type":21,"tag":255,"props":1203,"children":1204},{"style":272},[1205],{"type":26,"value":315},{"type":21,"tag":255,"props":1207,"children":1208},{"style":318},[1209],{"type":26,"value":1210}," db",{"type":21,"tag":255,"props":1212,"children":1213},{"style":272},[1214],{"type":26,"value":326},{"type":21,"tag":255,"props":1216,"children":1217},{"style":283},[1218],{"type":26,"value":1219}," DatabasePool",{"type":21,"tag":255,"props":1221,"children":1222},{"style":289},[1223],{"type":26,"value":336},{"type":21,"tag":255,"props":1225,"children":1226},{"class":257,"line":644},[1227,1231,1236,1240],{"type":21,"tag":255,"props":1228,"children":1229},{"style":272},[1230],{"type":26,"value":315},{"type":21,"tag":255,"props":1232,"children":1233},{"style":318},[1234],{"type":26,"value":1235}," paymentGateway",{"type":21,"tag":255,"props":1237,"children":1238},{"style":272},[1239],{"type":26,"value":326},{"type":21,"tag":255,"props":1241,"children":1242},{"style":283},[1243],{"type":26,"value":1244}," PaymentGateway\n",{"type":21,"tag":255,"props":1246,"children":1247},{"class":257,"line":652},[1248],{"type":21,"tag":255,"props":1249,"children":1250},{"style":289},[1251],{"type":26,"value":445},{"type":21,"tag":255,"props":1253,"children":1254},{"class":257,"line":692},[1255],{"type":21,"tag":255,"props":1256,"children":1257},{"emptyLinePlaceholder":452},[1258],{"type":26,"value":455},{"type":21,"tag":255,"props":1260,"children":1261},{"class":257,"line":732},[1262,1266,1271,1275,1279,1283,1288,1292,1296,1300,1305,1309,1313,1317,1321,1325,1329,1333,1338,1342,1346,1350,1354],{"type":21,"tag":255,"props":1263,"children":1264},{"style":272},[1265],{"type":26,"value":464},{"type":21,"tag":255,"props":1267,"children":1268},{"style":283},[1269],{"type":26,"value":1270}," placeOrder",{"type":21,"tag":255,"props":1272,"children":1273},{"style":289},[1274],{"type":26,"value":474},{"type":21,"tag":255,"props":1276,"children":1277},{"style":318},[1278],{"type":26,"value":1027},{"type":21,"tag":255,"props":1280,"children":1281},{"style":272},[1282],{"type":26,"value":326},{"type":21,"tag":255,"props":1284,"children":1285},{"style":289},[1286],{"type":26,"value":1287}," { ",{"type":21,"tag":255,"props":1289,"children":1290},{"style":318},[1291],{"type":26,"value":479},{"type":21,"tag":255,"props":1293,"children":1294},{"style":272},[1295],{"type":26,"value":326},{"type":21,"tag":255,"props":1297,"children":1298},{"style":486},[1299],{"type":26,"value":489},{"type":21,"tag":255,"props":1301,"children":1302},{"style":289},[1303],{"type":26,"value":1304},"; ",{"type":21,"tag":255,"props":1306,"children":1307},{"style":318},[1308],{"type":26,"value":498},{"type":21,"tag":255,"props":1310,"children":1311},{"style":272},[1312],{"type":26,"value":326},{"type":21,"tag":255,"props":1314,"children":1315},{"style":486},[1316],{"type":26,"value":489},{"type":21,"tag":255,"props":1318,"children":1319},{"style":289},[1320],{"type":26,"value":1304},{"type":21,"tag":255,"props":1322,"children":1323},{"style":318},[1324],{"type":26,"value":515},{"type":21,"tag":255,"props":1326,"children":1327},{"style":272},[1328],{"type":26,"value":326},{"type":21,"tag":255,"props":1330,"children":1331},{"style":486},[1332],{"type":26,"value":489},{"type":21,"tag":255,"props":1334,"children":1335},{"style":289},[1336],{"type":26,"value":1337}," })",{"type":21,"tag":255,"props":1339,"children":1340},{"style":272},[1341],{"type":26,"value":326},{"type":21,"tag":255,"props":1343,"children":1344},{"style":283},[1345],{"type":26,"value":1113},{"type":21,"tag":255,"props":1347,"children":1348},{"style":289},[1349],{"type":26,"value":1118},{"type":21,"tag":255,"props":1351,"children":1352},{"style":283},[1353],{"type":26,"value":1123},{"type":21,"tag":255,"props":1355,"children":1356},{"style":289},[1357],{"type":26,"value":1358},"> {\n",{"type":21,"tag":255,"props":1360,"children":1361},{"class":257,"line":740},[1362],{"type":21,"tag":255,"props":1363,"children":1364},{"style":262},[1365],{"type":26,"value":1366},"    \u002F\u002F Cohesive transactional implementation with automatic rollback & locality\n",{"type":21,"tag":255,"props":1368,"children":1369},{"class":257,"line":753},[1370],{"type":21,"tag":255,"props":1371,"children":1372},{"style":289},[1373],{"type":26,"value":910},{"type":21,"tag":255,"props":1375,"children":1376},{"class":257,"line":804},[1377],{"type":21,"tag":255,"props":1378,"children":1379},{"style":289},[1380],{"type":26,"value":919},{"type":21,"tag":22,"props":1382,"children":1383},{},[1384],{"type":26,"value":1385},"In the deep version:",{"type":21,"tag":122,"props":1387,"children":1388},{},[1389,1394,1405],{"type":21,"tag":126,"props":1390,"children":1391},{},[1392],{"type":26,"value":1393},"The interface is the test surface: you test the behavior against an in-memory database and a payment gateway fake. No mock labyrinths.",{"type":21,"tag":126,"props":1395,"children":1396},{},[1397,1399,1403],{"type":26,"value":1398},"Callers have maximum ",{"type":21,"tag":38,"props":1400,"children":1401},{},[1402],{"type":26,"value":150},{"type":26,"value":1404},": they pass three parameters and get back a finished result.",{"type":21,"tag":126,"props":1406,"children":1407},{},[1408,1410,1414],{"type":26,"value":1409},"Maintainers have ",{"type":21,"tag":38,"props":1411,"children":1412},{},[1413],{"type":26,"value":157},{"type":26,"value":1415},": when tax calculations or inventory hold rules change, the changes are contained in one place.",{"type":21,"tag":92,"props":1417,"children":1418},{},[],{"type":21,"tag":96,"props":1420,"children":1422},{"id":1421},"the-3-phase-deepening-loop-of-improve-codebase-architecture",[1423,1425],{"type":26,"value":1424},"The 3-Phase Deepening Loop of ",{"type":21,"tag":81,"props":1426,"children":1428},{"className":1427},[],[1429],{"type":26,"value":1430},"\u002Fimprove-codebase-architecture",{"type":21,"tag":22,"props":1432,"children":1433},{},[1434,1436,1441],{"type":26,"value":1435},"The ",{"type":21,"tag":81,"props":1437,"children":1439},{"className":1438},[],[1440],{"type":26,"value":86},{"type":26,"value":1442}," skill operationalizes this design philosophy into an automated, interactive workflow:",{"type":21,"tag":161,"props":1444,"children":1446},{"code":1445},"  ┌────────────────────────────────────────────────────────┐\n  │ 1. EXPLORE & SCOPE                                     │\n  │    - Analyze Git hotspots (`git log --oneline`)        │\n  │    - Read domain context (`CONTEXT.md` & `docs\u002Fadr\u002F`)  │\n  │    - Apply the Deletion Test to spot shallow modules   │\n  └───────────────────────────┬────────────────────────────┘\n                              │\n                              ▼\n  ┌────────────────────────────────────────────────────────┐\n  │ 2. VISUAL HTML REPORT                                  │\n  │    - Render self-contained report to OS temp directory │\n  │    - Interactive Tailwind layout + Mermaid diagrams    │\n  │    - Before\u002FAfter cards with recommendation badges     │\n  └───────────────────────────┬────────────────────────────┘\n                              │\n                              ▼\n  ┌────────────────────────────────────────────────────────┐\n  │ 3. INTERACTIVE GRILLING & LIVING DOCS                  │\n  │    - Run `\u002Fgrilling` on user-selected candidate        │\n  │    - Update `CONTEXT.md` vocabulary inline             │\n  │    - Record architectural trade-offs in `docs\u002Fadr\u002F`    │\n  └────────────────────────────────────────────────────────┘\n",[1447],{"type":21,"tag":81,"props":1448,"children":1449},{"__ignoreMap":7},[1450],{"type":26,"value":1445},{"type":21,"tag":22,"props":1452,"children":1453},{},[1454],{"type":26,"value":1455},"Let's examine what makes each phase distinct.",{"type":21,"tag":92,"props":1457,"children":1458},{},[],{"type":21,"tag":239,"props":1460,"children":1462},{"id":1461},"phase-1-scoped-discovery-and-the-deletion-test",[1463],{"type":26,"value":1464},"Phase 1: Scoped Discovery and the Deletion Test",{"type":21,"tag":22,"props":1466,"children":1467},{},[1468],{"type":26,"value":1469},"A common pitfall with automated architectural scanners is that they produce hundreds of theoretical, low-value refactoring suggestions.",{"type":21,"tag":22,"props":1471,"children":1472},{},[1473,1475,1480],{"type":26,"value":1474},"Matt Pocock's skill avoids this by adhering strictly to ",{"type":21,"tag":38,"props":1476,"children":1477},{},[1478],{"type":26,"value":1479},"YAGNI",{"type":26,"value":1481}," (You Aren't Gonna Need It):",{"type":21,"tag":175,"props":1483,"children":1484},{},[1485,1503,1540],{"type":21,"tag":126,"props":1486,"children":1487},{},[1488,1493,1495,1501],{"type":21,"tag":38,"props":1489,"children":1490},{},[1491],{"type":26,"value":1492},"Hotspot Analysis",{"type":26,"value":1494},": It inspects recent Git commit history (",{"type":21,"tag":81,"props":1496,"children":1498},{"className":1497},[],[1499],{"type":26,"value":1500},"git log --oneline",{"type":26,"value":1502},") to identify files and directories that change frequently. Deepening a module only pays dividends if developers and agents will actively interact with it in the future.",{"type":21,"tag":126,"props":1504,"children":1505},{},[1506,1511,1513],{"type":21,"tag":38,"props":1507,"children":1508},{},[1509],{"type":26,"value":1510},"Friction-Based Exploration",{"type":26,"value":1512},": A sub-agent explores the codebase asking concrete structural questions:\n",{"type":21,"tag":122,"props":1514,"children":1515},{},[1516,1524,1532],{"type":21,"tag":126,"props":1517,"children":1518},{},[1519],{"type":21,"tag":108,"props":1520,"children":1521},{},[1522],{"type":26,"value":1523},"Where does understanding a single concept require bouncing between multiple tiny modules?",{"type":21,"tag":126,"props":1525,"children":1526},{},[1527],{"type":21,"tag":108,"props":1528,"children":1529},{},[1530],{"type":26,"value":1531},"Where are pure functions extracted solely for unit testability while real bugs hide in orchestrating them?",{"type":21,"tag":126,"props":1533,"children":1534},{},[1535],{"type":21,"tag":108,"props":1536,"children":1537},{},[1538],{"type":26,"value":1539},"Which modules leak their internal concerns across their seams?",{"type":21,"tag":126,"props":1541,"children":1542},{},[1543,1548,1550,1555],{"type":21,"tag":38,"props":1544,"children":1545},{},[1546],{"type":26,"value":1547},"The Deletion Test",{"type":26,"value":1549},": For every suspected shallow module, the agent asks: ",{"type":21,"tag":108,"props":1551,"children":1552},{},[1553],{"type":26,"value":1554},"If we delete this, does complexity concentrate or merely scatter?",{"type":26,"value":1556}," Only candidates that genuinely concentrate complexity make the cut.",{"type":21,"tag":92,"props":1558,"children":1559},{},[],{"type":21,"tag":239,"props":1561,"children":1563},{"id":1562},"phase-2-a-masterclass-in-agent-ux-ephemeral-html-reports",[1564],{"type":26,"value":1565},"Phase 2: A Masterclass in Agent UX (Ephemeral HTML Reports)",{"type":21,"tag":22,"props":1567,"children":1568},{},[1569],{"type":26,"value":1570},"Dumping massive architectural analyses into the CLI or the LLM's chat context creates two problems: it pollutes your terminal and exhausts context tokens.",{"type":21,"tag":22,"props":1572,"children":1573},{},[1574,1575,1580,1582],{"type":26,"value":1435},{"type":21,"tag":81,"props":1576,"children":1578},{"className":1577},[],[1579],{"type":26,"value":86},{"type":26,"value":1581}," skill solves this with an elegant UX pattern: ",{"type":21,"tag":38,"props":1583,"children":1584},{},[1585],{"type":26,"value":1586},"it writes a standalone, self-contained HTML report to your operating system's temp directory and launches it directly in your browser.",{"type":21,"tag":22,"props":1588,"children":1589},{},[1590,1592,1597,1599,1604],{"type":26,"value":1591},"Styled with ",{"type":21,"tag":38,"props":1593,"children":1594},{},[1595],{"type":26,"value":1596},"Tailwind CSS via CDN",{"type":26,"value":1598}," and animated with ",{"type":21,"tag":38,"props":1600,"children":1601},{},[1602],{"type":26,"value":1603},"Mermaid.js diagrams",{"type":26,"value":1605},", the report renders a visual dossier for every deepening opportunity:",{"type":21,"tag":122,"props":1607,"children":1608},{},[1609,1619,1629,1639,1649,1681],{"type":21,"tag":126,"props":1610,"children":1611},{},[1612,1617],{"type":21,"tag":38,"props":1613,"children":1614},{},[1615],{"type":26,"value":1616},"Files Involved",{"type":26,"value":1618},": Clear mapping of affected files and modules.",{"type":21,"tag":126,"props":1620,"children":1621},{},[1622,1627],{"type":21,"tag":38,"props":1623,"children":1624},{},[1625],{"type":26,"value":1626},"The Problem",{"type":26,"value":1628},": Concrete explanation of the architectural friction.",{"type":21,"tag":126,"props":1630,"children":1631},{},[1632,1637],{"type":21,"tag":38,"props":1633,"children":1634},{},[1635],{"type":26,"value":1636},"The Solution",{"type":26,"value":1638},": Plain-English description of the proposed deepening.",{"type":21,"tag":126,"props":1640,"children":1641},{},[1642,1647],{"type":21,"tag":38,"props":1643,"children":1644},{},[1645],{"type":26,"value":1646},"Before \u002F After Diagrams",{"type":26,"value":1648},": Side-by-side architectural comparisons contrasting shallow call graphs with deep encapsulations.",{"type":21,"tag":126,"props":1650,"children":1651},{},[1652,1657,1659,1665,1666,1672,1674,1680],{"type":21,"tag":38,"props":1653,"children":1654},{},[1655],{"type":26,"value":1656},"Confidence Badges",{"type":26,"value":1658},": Categorized as ",{"type":21,"tag":81,"props":1660,"children":1662},{"className":1661},[],[1663],{"type":26,"value":1664},"Strong",{"type":26,"value":195},{"type":21,"tag":81,"props":1667,"children":1669},{"className":1668},[],[1670],{"type":26,"value":1671},"Worth exploring",{"type":26,"value":1673},", or ",{"type":21,"tag":81,"props":1675,"children":1677},{"className":1676},[],[1678],{"type":26,"value":1679},"Speculative",{"type":26,"value":44},{"type":21,"tag":126,"props":1682,"children":1683},{},[1684,1689],{"type":21,"tag":38,"props":1685,"children":1686},{},[1687],{"type":26,"value":1688},"Top Recommendation",{"type":26,"value":1690},": An explicit verdict on which seam to tackle first and why.",{"type":21,"tag":22,"props":1692,"children":1693},{},[1694,1696,1702,1704,1710],{"type":26,"value":1695},"Because the file lives in your OS temp directory (",{"type":21,"tag":81,"props":1697,"children":1699},{"className":1698},[],[1700],{"type":26,"value":1701},"\u002Ftmp",{"type":26,"value":1703}," or ",{"type":21,"tag":81,"props":1705,"children":1707},{"className":1706},[],[1708],{"type":26,"value":1709},"%TEMP%",{"type":26,"value":1711},"), your repository remains clean while you review high-density visual architecture in your browser.",{"type":21,"tag":92,"props":1713,"children":1714},{},[],{"type":21,"tag":239,"props":1716,"children":1718},{"id":1717},"phase-3-interactive-grilling-and-living-documentation",[1719],{"type":26,"value":1720},"Phase 3: Interactive Grilling and Living Documentation",{"type":21,"tag":22,"props":1722,"children":1723},{},[1724,1726,1731,1733,1739],{"type":26,"value":1725},"Once you review the report and select a deepening candidate, the skill transitions to execution through an interactive ",{"type":21,"tag":38,"props":1727,"children":1728},{},[1729],{"type":26,"value":1730},"Grilling Loop",{"type":26,"value":1732}," (using the ",{"type":21,"tag":81,"props":1734,"children":1736},{"className":1735},[],[1737],{"type":26,"value":1738},"\u002Fgrilling",{"type":26,"value":1740}," skill).",{"type":21,"tag":22,"props":1742,"children":1743},{},[1744],{"type":26,"value":1745},"Instead of making speculative changes, the agent interviews you about the new interface:",{"type":21,"tag":122,"props":1747,"children":1748},{},[1749,1754,1759],{"type":21,"tag":126,"props":1750,"children":1751},{},[1752],{"type":26,"value":1753},"What invariants must live behind the seam?",{"type":21,"tag":126,"props":1755,"children":1756},{},[1757],{"type":26,"value":1758},"What configuration is necessary?",{"type":21,"tag":126,"props":1760,"children":1761},{},[1762],{"type":26,"value":1763},"Which legacy tests will be superseded by testing through the newly unified interface?",{"type":21,"tag":22,"props":1765,"children":1766},{},[1767],{"type":26,"value":1768},"Crucially, this phase updates your repository's living documentation in real time:",{"type":21,"tag":122,"props":1770,"children":1771},{},[1772,1790],{"type":21,"tag":126,"props":1773,"children":1774},{},[1775,1780,1782,1788],{"type":21,"tag":38,"props":1776,"children":1777},{},[1778],{"type":26,"value":1779},"Glossary Alignment",{"type":26,"value":1781},": If a deepened module introduces or refines a domain concept, it updates ",{"type":21,"tag":81,"props":1783,"children":1785},{"className":1784},[],[1786],{"type":26,"value":1787},"CONTEXT.md",{"type":26,"value":1789}," immediately.",{"type":21,"tag":126,"props":1791,"children":1792},{},[1793,1798,1800,1806],{"type":21,"tag":38,"props":1794,"children":1795},{},[1796],{"type":26,"value":1797},"Architecture Decision Records",{"type":26,"value":1799},": If you reject a candidate or choose an unconventional seam for load-bearing reasons, the agent offers to record an ADR in ",{"type":21,"tag":81,"props":1801,"children":1803},{"className":1802},[],[1804],{"type":26,"value":1805},"docs\u002Fadr\u002F",{"type":26,"value":1807},". Future agent sessions will read this record, preventing them from repeatedly proposing the same rejected refactor.",{"type":21,"tag":92,"props":1809,"children":1810},{},[],{"type":21,"tag":96,"props":1812,"children":1814},{"id":1813},"why-this-skill-is-essential-for-autonomous-agents",[1815],{"type":26,"value":1816},"Why This Skill Is Essential for Autonomous Agents",{"type":21,"tag":22,"props":1818,"children":1819},{},[1820],{"type":26,"value":1821},"Most conversations around AI-assisted coding focus on execution: writing code faster, fixing syntax errors, or running test suites.",{"type":21,"tag":22,"props":1823,"children":1824},{},[1825,1827,1832],{"type":26,"value":1826},"But when agents generate code faster than ever before, ",{"type":21,"tag":38,"props":1828,"children":1829},{},[1830],{"type":26,"value":1831},"architectural decay accelerates at the same rate",{"type":26,"value":44},{"type":21,"tag":22,"props":1834,"children":1835},{},[1836],{"type":26,"value":1837},"If your codebase consists of shallow modules with leaky seams:",{"type":21,"tag":122,"props":1839,"children":1840},{},[1841,1846,1851],{"type":21,"tag":126,"props":1842,"children":1843},{},[1844],{"type":26,"value":1845},"Every agent prompt requires broader file searches.",{"type":21,"tag":126,"props":1847,"children":1848},{},[1849],{"type":26,"value":1850},"Token consumption climbs with every task.",{"type":21,"tag":126,"props":1852,"children":1853},{},[1854],{"type":26,"value":1855},"Subtle integration bugs multiply in untested glue code.",{"type":21,"tag":22,"props":1857,"children":1858},{},[1859],{"type":26,"value":1860},"By periodically running:",{"type":21,"tag":161,"props":1862,"children":1866},{"code":1863,"language":1864,"meta":7,"className":1865,"style":7},"\u002Fimprove-codebase-architecture\n","bash","language-bash shiki shiki-themes github-light github-dark",[1867],{"type":21,"tag":81,"props":1868,"children":1869},{"__ignoreMap":7},[1870],{"type":21,"tag":255,"props":1871,"children":1872},{"class":257,"line":258},[1873],{"type":21,"tag":255,"props":1874,"children":1875},{"style":283},[1876],{"type":26,"value":1863},{"type":21,"tag":22,"props":1878,"children":1879},{},[1880],{"type":26,"value":1881},"you actively prune shallow abstractions, reinforce deep interfaces, and create an environment where both human developers and autonomous AI agents can operate with clarity, speed, and confidence.",{"type":21,"tag":1883,"props":1884,"children":1885},"style",{},[1886],{"type":26,"value":1887},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":7,"searchDepth":268,"depth":268,"links":1889},[1890,1891,1895,1901],{"id":98,"depth":268,"text":101},{"id":229,"depth":268,"text":232,"children":1892},[1893,1894],{"id":241,"depth":295,"text":244},{"id":967,"depth":295,"text":970},{"id":1421,"depth":268,"text":1896,"children":1897},"The 3-Phase Deepening Loop of \u002Fimprove-codebase-architecture",[1898,1899,1900],{"id":1461,"depth":295,"text":1464},{"id":1562,"depth":295,"text":1565},{"id":1717,"depth":295,"text":1720},{"id":1813,"depth":268,"text":1816},"markdown","content:blog:matt-pocock-improve-codebase-architecture.md","content","blog\u002Fmatt-pocock-improve-codebase-architecture.md","blog\u002Fmatt-pocock-improve-codebase-architecture","md",1789230399822]