Skip to content
Skills Library
Programming · Review & audit

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.

Licence
Apache-2.0
Last repository change
08.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.07.2026, without references to retired models or APIs.

Licence

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

  1. Vocabulary [LOAD-BEARING]
  2. Principles
  3. Process
  4. Deepening categories (testing strategy per dependency class)
  5. Language-neutral examples
  6. Reference docs
Original SKILL.md headings · 78 lines, 696 words
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

RepositoryScoreLicence
This page · OutlineDriven/odin-codex-plugin100Apache-2.0
TerminalSkills/skills100Apache-2.0
callmeteus/gti-skills100MIT
akillness/jeo-skills100MIT
sammcj/agentic-coding100Apache-2.0
drvoss/everything-copilot-cli100MIT
hachemsoft/ia-toolkit100MIT
niekcandaele/claude-helpers100MIT
runwield/runwield100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.