rohitg00/pro-workflow / skills/improve-architecture
improve-architecture
VerifiedAudit an area of the codebase and propose the smallest structural moves that improve it - untangle boundaries, kill duplication, fix seams, break cycles. Produces a prioritized plan and decision records, not a rewrite. Use when a codebase feels tangled, hard to change, or is becoming a ball of mud, or when asked to improve or refactor architecture.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.5 KB |
SKILL.md
View on GitHub---
name: improve-architecture
description: Audit an area of the codebase and propose the smallest structural moves that improve it - untangle boundaries, kill duplication, fix seams, break cycles. Produces a prioritized plan and decision records, not a rewrite. Use when a codebase feels tangled, hard to change, or is becoming a ball of mud, or when asked to improve or refactor architecture.
user-invocable: true
---
# improve-architecture
Invest in the shape of the system a little at a time rather than paying for a
rewrite later. This skill diagnoses and proposes; it does not rewrite on its own.
## Method
1. **Map first.** Get the current shape before judging it - entry points,
modules, data flow, who calls whom. Reuse `module-map` for the one-screen
view; do not skip to opinions.
2. **Find the strain.** Look for the load-bearing problems, not style nits:
- God modules that everything imports and nothing can change safely.
- Leaky boundaries - a module reaching into another's internals instead of
its surface.
- Duplicated logic that drifts (the same rule implemented three ways).
- Wrong seams - the code is split where it does not bend and fused where it
does.
- Cyclic dependencies.
- A shape that fights the domain (see `domain-modeling` - boundaries in code
should track boundaries in the language).
3. **Propose the smallest move.** For each problem, the least change that
relieves it: extract a boundary, collapse a duplicate, invert a dependency,
move a seam. Prefer a sequence of safe steps over one big cut.
4. **Rank by leverage.** Order the moves by pain relieved over effort. Say which
are safe now and which need a test net first (pair with `tdd`).
5. **Record the big calls.** For a structural change a future reader would
question, write a decision record in `docs/decisions/NNNN-slug.md`: context,
choice, alternatives rejected, why.
## Guardrails
- Diagnose, do not rewrite. The deliverable is a plan the user approves before
any code moves.
- No churn for taste. A move must relieve a named strain; "cleaner" is not a
reason.
- Three similar lines beat a premature abstraction - do not trade duplication
for indirection unless the duplication actually drifts.
- Keep behavior fixed. Structural moves are refactors; land them behind green
tests.
## Output
A prioritized list: each item is the problem, the smallest move, the risk, and
whether it needs a test net first. Plus decision records for the big moves. No
code changes until the user picks what to do.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |