[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CZNXR5VRKM5HR9WEZWCEHV":3,"skill-same:01M6CZNXR5VRKM5HR9WEZWCEHV":63},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":6,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":14,"categories":15,"keywords":16,"publishedAt":20,"linkOnly":21,"markdownContent":22,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M6CZNXR5VRKM5HR9WEZWCEHV","improve-codebase-architecture",null,"Testing-itay\u002FDevTools-Security-Lab","Testing-itay","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F230151326?v=4","01M6CZH4Q5Z571N5ZRZWMQ3YBS","01M6CZH4W55EHV4P1D3SNNRXSS",0,"MIT","https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fimprove-codebase-architecture\u002FSKILL.md",[],[17,18,19],"improve codebase architecture","architecture","improve","2026-11-10 10:12:30",false,"\n\n\n\n---\nname: improve-codebase-architecture\ndescription: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs\u002Fadr\u002F. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.\n---\n\n# Improve Codebase Architecture\n\nSurface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.\n\n## Glossary\n\nUse these terms exactly in every suggestion. Consistent language is the point — don't drift into \"component,\" \"service,\" \"API,\" or \"boundary.\" Full definitions in [LANGUAGE.md](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 (see [LANGUAGE.md](LANGUAGE.md) for the full list):\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\nThis skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.\n\n## Process\n\n### 1. Explore\n\nRead the project's domain glossary and any ADRs in the area you're touching first.\n\nThen use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:\n\n- Where does understanding one concept require bouncing between many small modules?\n- Where are modules **shallow** — interface nearly as complex as the implementation?\n- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?\n- Where do tightly-coupled modules leak across their seams?\n- Which parts of the codebase are untested, or hard to test through their current interface?\n\nApply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A \"yes, concentrates\" is the signal you want.\n\n### 2. Present candidates as an HTML report\n\nWrite a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `\u002Ftmp` (or `%TEMP%` on Windows), and write to `\u003Ctmpdir>\u002Farchitecture-review-\u003Ctimestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open \u003Cpath>` on Linux, `open \u003Cpath>` on macOS, `start \u003Cpath>` on Windows — and tell them the absolute path.\n\nThe report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph\u002Fflow\u002Fsequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS\u002FSVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs\u002FSVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before\u002Fafter visualisation**. Be visual.\n\nFor each candidate, the same template as before, but rendered as a card:\n\n- **Files** — which files\u002Fmodules are involved\n- **Problem** — why the current architecture is causing friction\n- **Solution** — plain English description of what would change\n- **Benefits** — explained in terms of locality and leverage, and how tests would improve\n- **Before \u002F After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening\n- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge\n\nEnd the report with a **Top recommendation** section: which candidate you'd tackle first and why.\n\n**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines \"Order,\" talk about \"the Order intake module\" — not \"the FooBarHandler,\" and not \"the Order service.\"\n\n**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _\"contradicts ADR-0007 — but worth reopening because…\"_). Don't list every theoretical refactor an ADR forbids.\n\nSee [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.\n\nDo NOT propose interfaces yet. After the file is written, ask the user: \"Which of these would you like to explore?\"\n\n### 3. Grilling loop\n\nOnce the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.\n\nSide effects happen inline as decisions crystallize:\n\n- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `\u002Fgrill-with-docs` (see [CONTEXT-FORMAT.md](..\u002Fgrill-with-docs\u002FCONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.\n- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.\n- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _\"Want me to record this as an ADR so future architecture reviews don't re-suggest it?\"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons (\"not worth it right now\") and self-evident ones. See [ADR-FORMAT.md](..\u002Fgrill-with-docs\u002FADR-FORMAT.md).\n- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).\n",{},"main","1188d0dcbd4e64256d35bfe14c955ba1c541b1de",".github\u002Fskills\u002Fimprove-codebase-architecture",13,"https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab","https:\u002F\u002Fgithub.com\u002FTesting-itay","2026-10-16 16:13:27",{"source":7,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add Testing-itay\u002FDevTools-Security-Lab --skill improve-codebase-architecture",{"tool":37,"command":38},"bunx","bunx skills add Testing-itay\u002FDevTools-Security-Lab --skill improve-codebase-architecture",{"tool":40,"command":41},"pnpm","pnpm dlx skills add Testing-itay\u002FDevTools-Security-Lab --skill improve-codebase-architecture","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fimprove-codebase-architecture\u002FSKILL.md",true,[45,51,55,59],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"DEEPENING.md","REFERENCE","参考文档",2569,"https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fimprove-codebase-architecture\u002FDEEPENING.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"HTML-REPORT.md",6675,"https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fimprove-codebase-architecture\u002FHTML-REPORT.md",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"INTERFACE-DESIGN.md",2729,"https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fimprove-codebase-architecture\u002FINTERFACE-DESIGN.md",{"path":60,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":61,"sourceHtmlUrl":62},"LANGUAGE.md",3808,"https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fimprove-codebase-architecture\u002FLANGUAGE.md",[64,73,82,91,100,105],{"skillNo":65,"name":66,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":6,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":20},"01M6CZR9VVRMS754ZKH7NPNMB1","sds-plugin-a11y-check","https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002Fsrc\u002FnewDIR\u002Fbundles\u002Fplugins\u002Fsds-frontend-plugin\u002Fskills\u002Fsds-plugin-a11y-check\u002FSKILL.md",[],[70,71,72],"sds plugin a11y check","check","plugin",{"skillNo":74,"name":75,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":6,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":20},"01M6CZR8FQ30QGEV5D3SB6DDKP","endpoint-review","https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002Fsrc\u002FnewDIR\u002Fbundles\u002Fplugins\u002Fpython-api-plugin\u002Fskills\u002Fendpoint-review\u002FSKILL.md",[],[79,80,81],"endpoint review","endpoint","review",{"skillNo":83,"name":84,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":6,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":20},"01M6CZR6TYBN5EMBM70E096E66","schema-draft","https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002Fsrc\u002FnewDIR\u002Fbundles\u002Fplugins\u002Fpython-api-plugin\u002Fagents\u002Fpy-plugin-endpoint-designer\u002Fskills\u002Fschema-draft\u002FSKILL.md",[],[88,89,90],"schema","schema draft","draft",{"skillNo":92,"name":93,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":6,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":20},"01M6CZR5SDWF91FHDK54XHXS67","doc-outline","https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002Fsrc\u002FnewDIR\u002Fbundles\u002Fplugins\u002Fai-documentation-workflow\u002Fskills\u002Fdoc-outline\u002FSKILL.md",[],[97,98,99],"doc outline","outline","doc",{"skillNo":101,"name":66,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":6,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":20},"01M6CZR3Z4WZCBA5FVJZB65B1Y","https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002Fsrc\u002FnewD\u002FnewDIR\u002Fbundles\u002Fplugins\u002Fsds-frontend-plugin\u002Fskills\u002Fsds-plugin-a11y-check\u002FSKILL.md",[],[70,71,72],{"skillNo":106,"name":75,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":6,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":20},"01M6CZR2PR7T4XYSJJWQYYPXVW","https:\u002F\u002Fgithub.com\u002FTesting-itay\u002FDevTools-Security-Lab\u002Fblob\u002Fmain\u002Fsrc\u002FnewD\u002FnewDIR\u002Fbundles\u002Fplugins\u002Fpython-api-plugin\u002Fskills\u002Fendpoint-review\u002FSKILL.md",[],[81,79,80]]