improve-codebase-architecture

Files (2)

• HTML-REPORT.md
• SKILL.md

SKILL.md (first lines)

# Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deeper ones with better locality, leverage, and testability.

## Design Vocabulary

Use these terms consistently:
- module
- interface
- depth
- seam
- adapter
- leverage
- locality
- deletion test

If `CONTEXT.md` exists, use its domain language. If ADRs exist in `docs/adr/`, treat them as current constraints unless there is concrete evidence they should be revisited.

## Process

### 1. Explore

Read the domain glossary (`CONTEXT.md`) and relevant ADRs first, if present.

Then explore the codebase and note friction:
- Understanding one concept requires jumping across many files.
- A module interface is nearly as complex as its implementation.
- Testability exists only through extracted helpers, while call-site behavior remains hard to reason about.
- Tight coupling leaks across seams.
- Important behavior is untested or difficult to test through the current interface.

Apply the deletion test to suspicious abstractions: if deleting it only moves complexity elsewhere, it is likely shallow.

### 2. Generate HTML Architecture Report

Write a self-contained HTML report to the OS temp directory, not the repository.

Path rules:
- Resolve temp dir from `$TMPDIR`, else `/tmp` on Unix-like systems, else `%TEMP%` on Windows.
- Write to `<tmpdir>/architecture-review-<timestamp>.html`.
- Open it with `open` (macOS), `xdg-open` (Linux), or `start` (Windows).
- Return the absolute report path.

Report requirements:
- Use Tailwind CDN for layout and styling.
- Use Mermaid when graph or flow diagrams add clarity.
- Use custom HTML/CSS/SVG where editorial visuals communicate better.
- Include before/after visuals for each candidate.

For each candidate, include:
- Files involved
- Problem
- Solution
- Benefits (in terms of locality and leverage)
- Before/after diagram
- Recommendation strength: `Strong`, `Worth exploring`, or `Speculative`

End with a Top recommendation section: what to do first and why.

After writing the report, ask: `Which of these would you like to explore?`

### 3. Drill Into the Selected Candidate

Once the user picks a candidate, run a structured drill:
1. Clarify constraints and non-goals.
2. Map dependencies and seam boundaries.
3. Define the proposed interface.
4. Decide what remains behind the seam.
5. Specify tests that validate behavior through the interface.
6. Outline migration steps and rollback strategy.

If multiple interface shapes are plausible, design at least two alternatives and compare tradeoffs in complexity, locality, leverage, and testability.

## Context Maintenance

As decisions crystallize:
- If a new durable domain term appears, add or update `CONTEXT.md`.
- If a candidate is rejected for a durable reason, offer to record an ADR so future reviews avoid the same dead end.
- Do not create process noise for temporary or obvious reasons.

## Guardrails

- Keep recommendations concrete and repo-specific.
- Prefer minimal responsible changes over broad rewrites.
- Do not modify production code unless the user explicitly asks for implementation.
- Do not claim impact without citing where the friction was observed.

From veverkap/skills, MIT.

More from veverkap/skills