# Improve > Scan an existing codebase for module-level friction and architecture improvement opportunities (shallow modules, seam leaks, locality gaps), present candidates as an HTML report, interview on the selected candidate with a Design-It-Twice branch that designs the interface several radically different ways in parallel, and hand off the agreed shape for planning. Use when: 'improve architecture', 'find deepening opportunities', 'shallow modules', 'Ousterhout deepening', 'design it twice', 'compare alternative interfaces', 'make code more testable', 'make code more AI-navigable', 'find refactoring opportunities', 'codebase friction', 'module seams', 'locality'. Skip when: a cross-dimension or evidence-driven improvement ask (a general 'what should we improve', 'highest-impact improvement', or 'find improvements' across code, product, process, or ops) routes to /improvement:find (this skill is the single-lens architecture-depth pass); also skip for mechanical code-level tidyings, reviewing a diff before merge, enfo - Skill: `melodic-software/improve` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add melodic-software/improve` - Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/improve/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: melodic-software (https://skillmd.com/u/melodic-software) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/melodic-software/improve --- ## Repository context. Gather first Collect these with **individual** Bash calls, one command per call, never combined into a single invocation: - Current branch, `git branch --show-current` - Recent commits, `git log --oneline -20` - Working tree status (empty = clean), `git status --porcelain | head -10` The pipe is the bound and belongs in the command. A read-time cap ("read only the first 10 entries") bounds nothing: the Bash tool returns the command's complete output into context before there is anything to decide about. Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute block as one shell invocation, and a worktree-isolated session refuses a compound command that contains git. The dated record for that composition claim is the `source-control` plugin's [worktree/reference/gather-block.md](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/source-control/skills/worktree/reference/gather-block.md), "The pre-compute block runs as one shell invocation". ## Variables Arguments: `$ARGUMENTS` ## Purpose Improvement is distinct from review and planning. Review evaluates a DIFF against criteria (reactive). Planning designs NEW work (forward-looking). This skill scans EXISTING code for friction and proposes candidates for improvement (proactive). The scan-present-pick process generalizes across improvement **lenses**. Each lens (action) brings its own analysis method and vocabulary via an `actions/.md` playbook plus a `research//` reference set, loaded only when that lens runs. The first lens, `deepening`, implements Ousterhout's deep-module concept: finding shallow modules (interface nearly as complex as implementation) and proposing how to deepen them. The aim is **testability and AI/agent-navigability (AX)**: a deep module's small interface lets a reader, human or agent, grasp its purpose without traversing the whole import graph. This finds existing friction. It does not plan new work, apply mechanical code-level tidyings, enforce rules on a diff, or review changes before a PR. Those are separate concerns handled by planning, tidying, rule-enforcement, and review tools respectively (see "Composition"). ## Actions | Argument | Action | What it does | |----------|--------|-------------| | *(empty)* | Defaults to `deepening` | Runs the deepening lens | | `deepening` | **Deepening (Ousterhout)** | Shallow→deep module scan → HTML report → interview loop (with a Design-It-Twice branch for parallel interface exploration) → hand off an agreed candidate for planning. Full process: `actions/deepening.md` | One lens per invocation. Lenses don't chain implicitly. Read the action's playbook for its full process. ### Adding a lens A new improvement lens (e.g. `coupling`, `testability`, dependency-direction review) is a pure ADD. Never edit an existing lens's contract to add one (open for extension, closed for modification): - `actions/.md`. The lens playbook (phases, gates, output shape) - `research//`. Reference for that lens, loaded only when its action runs (per-action progressive disclosure) - one row in the Actions table above, plus one row per new reference file in the reference index below ## Reference index. Load on demand | File | Load when | |------|-----------| | [research/deepening/scan-briefing.md](research/deepening/scan-briefing.md) | Before briefing the Phase 1 scan subagents. It is the canonical prompt (vocabulary primer, friction checklist, dependency categories, the two badge-acceptance heuristics, per-candidate return schema), so scan quality does not vary run-to-run | | [research/deepening/vocabulary.md](research/deepening/vocabulary.md) | Applying the deletion test, or naming anything in a candidate, report, or interview turn. The terms are used exactly, not paraphrased | | [research/deepening/dependencies.md](research/deepening/dependencies.md) | Classifying a candidate's dependencies, where the category chooses the testing strategy | | [research/deepening/html-report.md](research/deepening/html-report.md) | Writing the HTML report: scaffold, diagram patterns, and the report's two additions to the rendered-views security baseline (which strings are repository-derived, no script inside SVG) | | [research/deepening/interface-design.md](research/deepening/interface-design.md) | Entering the Design-It-Twice branch, or a single proposed shape is not converging in the interview loop | ## What this skill does NOT do - **Does not plan implementation.** Produces candidates + agreed shape; a planning step plans the work - **Does not enforce rules.** A rule-enforcement reviewer does that reactively on a diff - **Does not apply mechanical tidyings.** Code-level tidyings (rename, extract, inline) are a separate, smaller-grained concern - **Does not review a diff.** Pre-merge review tools do that - **Does not write code.** Discovery and design skill only - **Does not brainstorm a rough problem.** This skill hunts architecture friction on its own lenses; open-ended "how could we approach X" divergence is a brainstorming concern - **Does not render another repository's files to HTML** until the rendered-views escape helper ships. A scan of a repository that is not the user's own delivers the durable candidate artifact and says in one line why no page was produced (`actions/deepening.md`, Phase 2) ## Composition Graceful degradation: where a named step below is not available in the consuming project, inline the equivalent work in this session instead of blocking on it. | When | Then | How | |------|------|-----| | A debugging pass finds an architectural root cause | Run this skill's deepening lens | Structured deepening review of the affected module | | A candidate shape is agreed | Hand off to a planning skill if the project has one; else summarize the agreed shape for planning | Consumes the `agreed-shape` entry from the candidate artifact (see `actions/deepening.md`) | | During the interview loop | Maintain resolved project vocabulary | Invoke `/domain-driven-design:curate-language` via the Skill tool when available in the current session; otherwise update an existing consumer-declared glossary in its own shape | | Post-improvement | Review the implemented changes with the project's review tool | Standard diff review | ## Gotchas Failure modes this lens runs into, each stated as the rule it implies. - **The durable candidate artifact is a per-project memory-tier file, never `${CLAUDE_PLUGIN_DATA}`.** Even resolved it points at a plugin-global dir with no project dimension that collides candidates across projects, and uninstalling from the last remaining scope deletes the directory. The documented use is deps/caches/generated code, not per-project artifacts. The artifact resolves through the marketplace topic-docs convention (the plugin's topic-docs [binding](../../reference/topic-docs.md)): memory tier, default `.work//`. A `${CLAUDE_PROJECT_DIR}/.claude/...` path is also wrong: `.claude/` generated output is reserved for observability, and an unignored artifact there leaks scan output into git. - **Scan-agent claims are shipped only after Phase 1.5 reproduction.** Exploration subagents infer from partial reads, so a claim that a service is unused or a call path is dead can be wrong in a way a single grep settles. Any candidate headed for a `Strong` badge and any runtime-bug / dead-code claim is reproduced against the actual code before it reaches the user-facing report. The report lends every claim its authority, so an unreproduced overstatement is cheap to make and expensive to reputation.