Pixel-CLI/pixel / .agents/skills/improve-codebase-architecture
improve-codebase-architecture
VerifiedFind deepening opportunities in pixel's crates (shallow modules to merge behind a smaller interface, leaking seams, logic only testable past its interface), scouted with pixel's own churn, size, caller and area data, presented as a local HTML report of before/after cards with their real cost (diff size, mutants, ARCHITECTURE.md sections, PR stack), then grilled through the candidate the user picks until it becomes a task on project 3. Adapted from Matt Pocock's improve-codebase-architecture skill. Manual only: "/improve-codebase-architecture [area]", "revue d'archi", "où approfondir les modules".
| File | Kind | Size |
|---|---|---|
| DESIGN.md | markdown | 6.7 KB |
| HTML-REPORT.md | markdown | 4.4 KB |
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 9.1 KB |
| UPSTREAM | other | 172 B |
| agents/openai.yaml | config | 166 B |
HTML-REPORT.md
View on GitHub# HTML report format
One self-contained HTML file in `${TMPDIR:-/tmp}`, never in the repo.
Tailwind and Mermaid come from CDNs; everything else is inline. Adapted from
`mattpocock/skills` (MIT, see [LICENSE](LICENSE)).
## Scaffold
```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Architecture review: pixel</title>
<script src="https://cdn.tailwindcss.com"></script>
<script type="module">
import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
mermaid.initialize({ startOnLoad: true, theme: "neutral" });
</script>
<style>
.seam { stroke-dasharray: 4 4; }
.leak { stroke: #dc2626; }
.deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
</style>
</head>
<body class="bg-stone-50 text-slate-900 font-sans">
<main class="max-w-5xl mx-auto px-4 sm:px-6 py-12 space-y-12">
<header>...</header>
<section id="candidates" class="space-y-10">...</section>
<section id="top-recommendation">...</section>
</main>
</body>
</html>
```
## Header
The commit (`git rev-parse --short HEAD`), the date, the scope (`$A` or the
hot spots and the churn window), and a compact legend: solid box = module,
dashed line = seam, red arrow = leakage, thick dark box = deep module. No
introduction paragraph.
## Candidate card
One `<article>` per candidate. The diagram carries the weight; prose is
sparse.
- **Title**: names the deepening ("Fold the doctor checks behind one
registry").
- **Badges**: strength (`Strong` emerald, `Worth exploring` amber,
`Speculative` slate) and the dependency category (`in-process`,
`local-substitutable`, `ports & adapters`, `mock`; DESIGN.md).
- **Files**: monospaced list (`font-mono text-sm`).
- **Before / after diagram**: two columns side by side on desktop, stacked
under 640 px.
- **Problem**: one sentence.
- **Solution**: one sentence, no interface yet.
- **Wins**: bullets of six words or fewer, in glossary terms ("locality:
one place to fix", "leverage: one interface, 14 callers").
- **Cost** (a small table, the numbers from SKILL.md Step 2): mutants listed
for the rewritten files, estimated diff and PR split, `ARCHITECTURE.md`
sections owed, `pixel impact` risk of the main symbol.
- **Settled-decision callout** when it applies: one amber line naming the
`ARCHITECTURE.md` section, the rule or the closed issue it reopens, and
why it is worth reopening.
If a diagram needs a paragraph to be understood, redraw the diagram.
## Diagram patterns
Pick per candidate and vary them; a report where every diagram looks the
same reads as generated.
- **Mermaid flowchart** for call flow and dependencies ("X calls Y calls Z,
and look at the mess"); `classDef` colours leaks red and the deep module
dark. A sequence diagram suits "before: six round trips; after: one".
- **Hand-built boxes and arrows** (divs plus an inline SVG overlay) when the
"after" must read as one thick-bordered module with its internals faded,
which Mermaid will not draw with the right weight.
- **Cross-section**: stacked bands for the layers a call crosses; before,
six thin bands doing nothing; after, one thick band.
- **Mass diagram**: two rectangles per module, interface and
implementation; before, nearly the same height; after, a short interface
over a tall implementation. Illustration only: depth is not a lines ratio.
- **Call-graph collapse**: a tree of calls as nested boxes, then the same
tree folded into one box with the now-internal calls faded inside.
Keep each diagram around 320 px tall so before and after fit side by side.
Module labels in `text-xs uppercase tracking-wider`, so they read as a
schematic, not as UI.
## Top recommendation
One larger card: the candidate's name, one sentence on why it comes first
(usually the best ratio of locality gained to cost), and an anchor link to
its card.
## Tone
Plain, concise, the architecture nouns from DESIGN.md without ceremony:
"The doctor module is shallow: its interface nearly matches its
implementation." "Install state leaks across the seam." "Two adapters
justify the seam: the socket in production, `Service::handle` in tests."
No "easier to maintain", no "cleaner code": those words are not in the
glossary and carry nothing. No hedging; if a sentence can be a bullet, make
it one, and if a bullet can go, cut it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |