Skip to content
Skills Library
Programming · Review & audit

improve-codebase-architecture

/improve-codebase-architecture

Explicitly scan existing product code for evidence-backed deep-module opportunities, render a safe offline report, and explore one user-selected refactor without implementing it. Use for broad maintenance discovery of shallow modules, scattered policy, leaky seams, repeated orchestration, and hard-to-test behavior; not for new-system architecture, workflow-harness audits, or direct refactoring.

Repository
ezpowers ↗
Licence
MIT
Last repository change
18.10.2026

Assessment and security

95/ 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.
Content30 / 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
5
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/render-report.py

What it does and when to use it

Explicitly scan existing product code for evidence-backed deep-module opportunities, render a safe offline report, and explore one user-selected refactor without implementing it. Use for broad maintenance discovery of shallow modules, scattered policy, leaky seams, repeated orchestration, and hard-to-test behavior; not for new-system architecture, workflow-harness audits, or direct refactoring.

Original author description

Explicitly scan existing product code for evidence-backed deep-module opportunities, render a safe offline report, and explore one user-selected refactor without implementing it. Use for broad maintenance discovery of shallow modules, scattered policy, leaky seams, repeated orchestration, and hard-to-test behavior; not for new-system architecture, workflow-harness audits, or direct refactoring.

How it works

  1. Ground and freeze the scan
  2. Find and rank candidates
  3. Render and present
  4. Explore the selected candidate
Original SKILL.md headings · 88 lines, 546 words
SKILL.md preview
---
name: improve-codebase-architecture
description: Explicitly scan existing product code for evidence-backed deep-module opportunities, render a safe offline report, and explore one user-selected refactor without implementing it. Use for broad maintenance discovery of shallow modules, scattered policy, leaky seams, repeated orchestration, and hard-to-test behavior; not for new-system architecture, workflow-harness audits, or direct refactoring.
disable-model-invocation: true
---

# Improve Codebase Architecture

Find high-value product-code deepening opportunities without changing the
repository.

## Ground and freeze the scan

Resolve `<skill-root>` as the directory containing this `SKILL.md`. Read
`<skill-root>/references/report-contract.md` and use
`<skill-root>/scripts/render-report.py`. Verify both exist before scanning;
never fetch an upstream file at runtime.

Read repository instructions, the exact initial Git status, relevant history,
`CONTEXT.md` when present, applicable ADRs, architecture documents, product
code, callers, and tests. Treat documentation as context, not automatically as
an affected product file. Do not run tests, builds, formatters, or generators
during this advisory scan unless the user explicitly requests them; inspection
must not create caches or other workspace artifacts.

Use a user-named module, subsystem, or pain point as the boundary. Do not widen
a user-named scope. With no named scope, use recurring recent product-code
changes to choose a hotspot, state why, and widen only when history has no
coherent hotspot. Do not audit EZPowers workflow or harness authority with
this skill.

## Find and rank candidates

Apply the deletion test and the Module, Interface, Implementation, Depth, Seam,
Adapter, Leverage, and Locality vocabulary. Look organically for scattered
domain behavior, repeated ordering policy, interfaces nearly as complex as
implementations, pass-through modules, one-adapter false seams, caller leakage,
and behavior that cannot be tested through an honest interface.

Keep only 1–8 candidates supported by exact existing file-and-line evidence.
Every affected product or test file needs evidence. Mark glossary, architecture,
and ADR findings separately as context or decision evidence. Record the current
problem, responsibility-level deepening, locality and leverage, surviving test
surface, compatibility, migration, ADR status, recommendation strength, and
semantically styled before/after graphs.

Do not propose interfaces during the scan; selection must precede interface
design. Do not invent a candidate to satisfy the report schema. If the bounded
scope has no evidence-backed candidate, report that result and stop without a
report.

## Render and present

Write schema-version-2 JSON to an OS temporary path and run:

```text
python <skill-root>/scripts/render-report.py
  --project-root <project-root>
  --input <temporary-json>
  --open
  --json
```

Correct invalid structured input and rerun; never hand-author HTML, use a CDN,
write the report inside the repository, overwrite a report, or claim success
without a valid receipt. Delete the temporary input JSON after a successful
render and also on terminal failure. Preserve the generated HTML for the user.

Confirm the final Git status exactly matches the initial status. If this scan
changed the workspace, stop and report the drift without deleting unknown
files. Report scope and its basis, revision and dirty state, top recommendation
and rationale, candidate count, report path, report/input/source SHA-256 values,
source file count, and warnings.

Ask exactly one question at a time. At this stage ask only which candidate the
user wants to explore, then wait.

## Explore the selected candidate

After selection, inspect missing facts and ask one consequential constraint
question at a time rather than inventing a decision. When the user has answered
or delegated the choices, compare at least two materially different Interface
and Seam options. Do not vary only names.

Return **Refactor brief** with the selected candidate and evidence, settled
constraints, interface options and tradeoffs, recommendation, compatibility
and migration boundary, surviving tests, and unresolved risks.

Do not implement the refactor or automatically edit product code, `CONTEXT.md`,
ADRs, architecture documents, specs, or plans. Durable project-boundary changes
remain separate architecture work; implementation requires independent user
authority.
Files in this package (5)
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB
  • agents/project-openai.yaml 1 KB
  • references/report-contract.md 4 KB
  • scripts/render-report.py 1 KB

Versions

RepositoryScoreLicence
This page · dlwlgus9125/ezpowers95MIT
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 407a415e6800 (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

  • 100code-architecture
    Scan a codebase for deepening opportunities, such as shallow modules, hypothetical seams and scattered state, against the h2xd:code-quality bar and its smells, report them ranked, then grill through the one the user picks with h2xd:plan-grill. A chosen reshape that is hard to…
  • 100architecture-rescue
    Find deepening opportunities in a codebase — shallow modules, missing seams, leaky abstractions — and present them as numbered candidates ready for a grilling session before any interface is proposed. Use when the codebase feels tangled, tests are hard to write, modules feel…
  • 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…
  • 100deep-module-design
    Design deep modules with small interfaces and rank shallow, pass-through or leaky code for deepening. Use when designing a module interface, improving codebase architecture, or making code easier to test.
  • 86improve-architecture
    Audit a codebase for evidence-backed architecture improvements, leverage, seams, locality, and reversibility. Use when the user explicitly requests an assessment of the existing architecture, including when the request defers new module-boundary design; do not implement changes,…
  • 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…

Feedback and reports

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