improve-codebase-architecture
/improve-codebase-architecture
Surface deepening refactors that turn shallow modules into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Use when the user asks to improve architecture, find refactor candidates, raise testability, or make a codebase more agent-navigable. Skip for single localized fixes.
- Author
- OutlineDriven ↗
- Repository
- odin-codex-plugin ↗
- Licence
- Apache-2.0
- Last repository change
- 08.07.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 08.07.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Surface deepening refactors that turn shallow modules into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Use when the user asks to improve architecture, find refactor candidates, raise testability, or make a codebase more agent-navigable. Skip for single localized fixes.
Original author description
Surface deepening refactors that turn shallow modules into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Use when the user asks to improve architecture, find refactor candidates, raise testability, or make a codebase more agent-navigable. Skip for single localized fixes.
How it works
- Vocabulary [LOAD-BEARING]
- Principles
- Process
- Deepening categories (testing strategy per dependency class)
- Language-neutral examples
- Reference docs
SKILL.md preview
--- name: improve-codebase-architecture description: Surface deepening refactors that turn shallow modules into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Use when the user asks to improve architecture, find refactor candidates, raise testability, or make a codebase more agent-navigable. Skip for single localized fixes. disable-model-invocation: true --- Iteration loop: explore for friction, present deepening candidates, grill the chosen one, update domain artifacts inline. Vocabulary is load-bearing — see `references/LANGUAGE.md`. ## Vocabulary [LOAD-BEARING] Use these terms exactly. Do not substitute "component," "service," "API," or "boundary." Full definitions in `references/LANGUAGE.md`. - **Module** — anything with an interface and an implementation (function, class, package, slice). Scale-agnostic. - **Interface** — every fact a caller must know: types, invariants, ordering, error modes, config, performance shape. Not just signature. - **Depth** — leverage at the interface. Deep = much behaviour behind a small interface. Shallow = interface as complex as implementation. - **Seam** (Feathers) — where an interface lives; a place behaviour can be altered without editing in place. Use this, not "boundary." - **Adapter** — a concrete thing satisfying an interface at a seam. Role, not substance. - **Leverage** — capability callers gain per unit of interface learned. - **Locality** — concentration of change, bug, and knowledge at one site for maintainers. ## Principles - **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. - **Interface = test surface.** Tests cross the same seam callers cross. Wanting to test past the interface = wrong shape. - **One adapter = hypothetical seam. Two adapters = real seam.** No port without two real implementations (production + test). ## Process ### 1. Explore First tool call MUST be Explore-agent dispatch — not direct reads. The agent's brief: - Read `CONTEXT.md` (or `CONTEXT-MAP.md` + per-context `CONTEXT.md`) and any `docs/adr/`. If absent, proceed silently. - Walk the codebase organically; classify friction: - Concept understanding requires bouncing across many small modules → shallow cluster. - Interface complexity matches implementation complexity → shallow module. - Pure functions extracted only for testability while real bugs hide in callers → no locality. - Tightly coupled modules leaking across their seams. - For each suspect, run the deletion test before reporting. ### 2. Present candidates Numbered list. Each candidate: **Files**, **Problem** (concrete friction; cite deletion test), **Solution** (plain-English description; no interface yet), **Benefits** (locality, leverage, testability deltas). ADR conflicts: surface only when friction warrants reopening; mark explicitly: _"contradicts ADR-0007 — worth reopening because…"_. Ask: "Which candidate to explore?" Do not propose interfaces yet. ### 3. Grilling loop Once user picks, drop into adversarial interview — walk the design tree, resolve dependencies one decision at a time, recommend an answer per question. Side effects happen inline: - New domain term emerging? Update `CONTEXT.md` immediately (lazy create). - User rejects with a load-bearing reason that future explorers would need? Offer ADR. - User wants alternative interfaces for the chosen candidate? Pivot to `references/INTERFACE-DESIGN.md` — parallel sub-agent design twice (Ousterhout). ## Deepening categories (testing strategy per dependency class) Full treatment in `references/DEEPENING.md`. Summary: | Class | Deepenable? | Test strategy | |---|---|---| | In-process (pure / in-memory) | Always | Merge modules; test through new interface directly. No adapter. | | Local-substitutable (PGLite, in-memory FS) | Yes if stand-in exists | Stand-in runs in tests; seam stays internal. | | Remote but owned (microservices) | Yes via Ports & Adapters | Port at seam; HTTP/gRPC adapter prod, in-memory adapter test. | | True external (Stripe, Twilio) | Yes | Injected port; mock adapter for tests. | Replace, don't layer: delete shallow-module tests once interface tests exist. ## Language-neutral examples **Rust** — shallow `validate_address` + `format_address` + `geocode_address` separately called by a `Shipment` aggregator. Deletion test: removing `format_address` concentrates string-handling at one call site → was a pass-through. Deepen into `address::Resolver` with `resolve(raw) -> Result<Resolved, AddressError>`; tests cross the new interface; in-memory `Geocoder` adapter for tests, HTTP adapter for production. **Python** — module exposes `parse_invoice`, `apply_tax`, `round_total` as separate top-level functions; every caller chains all three. Deepen into `billing.Invoice.finalize(raw) -> Invoice`. Internal seams (tax tables, rounding rules) stay private; the test surface is `Invoice.finalize`. ## Reference docs - `references/LANGUAGE.md` — full vocabulary, principles, rejected framings. - `references/DEEPENING.md` — dependency taxonomy, seam discipline, replace-don't-layer testing. - `references/INTERFACE-DESIGN.md` — parallel sub-agent "Design It Twice" workflow when the chosen candidate's interface needs alternatives. Forbidden: proposing interfaces in step 2 (premature commitment), bundling unrelated refactors, re-litigating ADRs without a load-bearing reason.
Files in this package (4)
- SKILL.md 5 KB
- references/DEEPENING.md 4 KB
- references/INTERFACE-DESIGN.md 3 KB
- references/LANGUAGE.md 5 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · OutlineDriven/odin-codex-plugin | 100 | Apache-2.0 |
| TerminalSkills/skills | 100 | Apache-2.0 |
| callmeteus/gti-skills | 100 | MIT |
| akillness/jeo-skills | 100 | MIT |
| sammcj/agentic-coding | 100 | Apache-2.0 |
| drvoss/everything-copilot-cli | 100 | MIT |
| hachemsoft/ia-toolkit | 100 | MIT |
| niekcandaele/claude-helpers | 100 | MIT |
| runwield/runwield | 100 | MIT |
Database snapshot: 13.11.2026 · package version 7108c1096123 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100deep-codebase-audit
Find deepening opportunities in a codebase, surfacing architectural friction and proposing refactors that turn shallow modules into deep ones. Use when the user wants to improve architecture, make a codebase more testable, consolidate tightly-coupled modules, or make it safer… - 100improve
Find deepening opportunities in a codebase — refactors that turn shallow modules into deep ones for better testability and AI-navigability. Use when the user wants to improve architecture, surface architectural friction, consolidate tightly-coupled modules, find shallow… - 90codebase-deepening
Deepening shallow modules, by how their dependencies are tested. Use when the task or your plan merges, refactors or deepens shallow modules, or puts a seam, port or adapter in place. - 100architecture
Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary… - 90architecture-review
Surfaces architectural friction in real code — shallow modules, tight coupling, untested seams — and proposes deepening refactors using Ousterhout's deep-module principle (small interface hiding a large implementation). Use when the founder says 'architecture review', 'find… - 81architecture
Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary…