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,
"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/<lens>.md playbook plus a research/<lens>/ 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/<lens>.md. The lens playbook (phases, gates, output shape)research/<lens>/. 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 |
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 |
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 |
Classifying a candidate's dependencies, where the category chooses the testing strategy |
| 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 |
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): memory tier, default .work/<topic-slug>/. 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.
1---2name: improve3description: 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, enfo4---56## Repository context. Gather first78Collect these with **individual** Bash calls, one command per call, never combined into a single9invocation:1011- Current branch, `git branch --show-current`12- Recent commits, `git log --oneline -20`13- Working tree status (empty = clean), `git status --porcelain | head -10`1415The pipe is the bound and belongs in the command. A read-time cap ("read only the first 10 entries")16bounds nothing: the Bash tool returns the command's complete output into context before there is17anything to decide about.1819Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as20separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute21block as one shell invocation, and a worktree-isolated session refuses a compound command that22contains git. The dated record for that composition claim is the `source-control` plugin's23[worktree/reference/gather-block.md](https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/plugins/source-control/skills/worktree/reference/gather-block.md),24"The pre-compute block runs as one shell invocation".2526## Variables2728Arguments: `$ARGUMENTS`2930## Purpose3132Improvement 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).3334The scan-present-pick process generalizes across improvement **lenses**. Each lens (action) brings its own analysis method and vocabulary via an `actions/<lens>.md` playbook plus a `research/<lens>/` 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.3536This 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").3738## Actions3940| Argument | Action | What it does |41|----------|--------|-------------|42| *(empty)* | Defaults to `deepening` | Runs the deepening lens |43| `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` |4445One lens per invocation. Lenses don't chain implicitly. Read the action's playbook for its full process.4647### Adding a lens4849A 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):5051- `actions/<lens>.md`. The lens playbook (phases, gates, output shape)52- `research/<lens>/`. Reference for that lens, loaded only when its action runs (per-action progressive disclosure)53- one row in the Actions table above, plus one row per new reference file in the reference index below5455## Reference index. Load on demand5657| File | Load when |58|------|-----------|59| [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 |60| [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 |61| [research/deepening/dependencies.md](research/deepening/dependencies.md) | Classifying a candidate's dependencies, where the category chooses the testing strategy |62| [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) |63| [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 |6465## What this skill does NOT do6667- **Does not plan implementation.** Produces candidates + agreed shape; a planning step plans the work68- **Does not enforce rules.** A rule-enforcement reviewer does that reactively on a diff69- **Does not apply mechanical tidyings.** Code-level tidyings (rename, extract, inline) are a separate, smaller-grained concern70- **Does not review a diff.** Pre-merge review tools do that71- **Does not write code.** Discovery and design skill only72- **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 concern73- **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)7475## Composition7677Graceful 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.7879| When | Then | How |80|------|------|-----|81| A debugging pass finds an architectural root cause | Run this skill's deepening lens | Structured deepening review of the affected module |82| 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`) |83| 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 |84| Post-improvement | Review the implemented changes with the project's review tool | Standard diff review |8586## Gotchas8788Failure modes this lens runs into, each stated as the rule it implies.8990- **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/<topic-slug>/`. 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.91- **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.
melodic-software