---
name: apt:improve
description: "Proactive refactor discovery — scan a named area through DEEPENING / INTERFACE-DESIGN / LANGUAGE lenses, present top candidates, deepen via grill loop."
apt-skill-version: {{APT_VERSION}}
stage: plan
intent: investigate
when_to_use: "The user feels code has rotted and wants a refactor surface (not a feature). Triggers: 'this part of the codebase needs work', 'I want to refactor X but don't know where to start', 'show me what's worth refactoring in Y'."
user_invocable: true
internal: false
spawns_agent: true
agent_name: "apt-improver"
task_context: create-new
default_track: DEEP
default_execution_mode: step
execution_modes:
  - auto
  - step
allowed-tools: "Read, Grep, Glob, Bash"
argument-hint: "apt:improve [area-name]"
gates: []
---

# Improve — Proactive Refactor Discovery

Open question #2 in adoption spec was answered concretely:
`apt:review` Pass 4 (architecture) is strictly **reactive** — it audits
the current diff for boundary violations. The work-intent "look at this
codebase and tell me what to refactor proactively" has no home today
(users retrofit it onto `apt:discuss --brainstorm` or `/apt:roundtable`,
both scope-mismatched). This skill is that home.

**Aperant adoption attribution.** 3-phase workflow + DEEPENING /
INTERFACE-DESIGN / LANGUAGE lenses ported from 
`improve-codebase-architecture` skill. Aperant-specific: spawns the
`apt-improver` agent and references `apt-discuss/appendices/grill-discipline.md`
as the canonical source for the autonomy-aware deepening loop rather than
re-stating the policy here.

## When to Use

- Feeling that an area of the codebase has rotted but unsure where to
  start (proactive discovery)
- Before a multi-task refactor cycle, to surface the highest-leverage
  candidates first
- After a feature has bedded in and the user wants to consolidate

## When NOT to Use

- Auditing a current diff for boundary violations — that's `/apt:review`
  Pass 4 (reactive)
- Locking a specific refactor decision — use `/apt:discuss` instead
- Renaming or restructuring without proactive discovery — use
  `/apt:plan` directly

## 3-Phase workflow

### Phase 1 — Explore (scan a named area for candidate refactors)

Sub-agent `apt-improver` reads:

- The named area (a noun phrase like "sparring engine", "feature
  registry", "auth flow")
- `CONTEXT.md` term-blocks matching the area (if present)
- Relevant files via Glob/Grep

It applies three lenses, each described in its own sub-file:

- **DEEPENING** (`DEEPENING.md`) — does this area model the domain at
  the right depth? Are abstractions earning their keep, or are they
  shallow wrappers hiding nothing?
- **INTERFACE-DESIGN** (`INTERFACE-DESIGN.md`) — are the boundaries
  between modules well-shaped? Are there feature-envy patterns? Hidden
  coupling? Async leakage?
- **LANGUAGE** (`LANGUAGE.md`) — does the codebase use the same word
  for the same thing? Do field names match domain language? Is
  CONTEXT.md's "aliases to avoid" list violated anywhere?

Output: a Phase-1 inventory of **candidate refactors** with one-line
diagnoses per candidate.

### Phase 2 — Present candidates (top 3-5 with deletion-test rationale)

The skill body filters the Phase-1 inventory down to 3-5 candidates
using the **deletion test**: for each candidate, ask "if I deleted this
abstraction, what would break?" If the answer is "nothing important",
the candidate is high-priority (the abstraction was paying no rent).

Output to the user:

```markdown
## Refactor candidates for {area}

1. **{Candidate title}** — {one-line diagnosis}.
   Deletion test: {what breaks if removed} → {priority: high/med/low}.

2. ...
```

### Phase 3 — Deepen via grill loop (autonomy-aware)

The user picks one or more candidates. For each picked candidate, the
skill enters a deepening loop. **This loop references
`apt-discuss/appendices/grill-discipline.md` as the canonical source**
for autonomy-aware degradation:

- Autonomy 1: ask the user about every load-bearing design question
- Autonomy 2: batch-recommend per decision, user reviews at end
- Autonomy 3: auto-lock with the 3 escalation triggers (conflict with
  prior locked decision; critical-path file touched; no defensible
  default)

The deepening loop produces a concrete refactor plan (which becomes
`/apt:plan`'s input on a subsequent invocation).

## Sub-files (MIT-attributed)

- `DEEPENING.md` — domain-modeling depth lens
- `INTERFACE-DESIGN.md` — boundary-shape lens
- `LANGUAGE.md` — naming-consistency lens

All three are ported from 's improve-codebase-architecture
skill with MIT attribution per AC15.

## Agent spawned

`apt-improver` (definition at `packages/framework/agents/apt-improver.md`)
runs Phase 1 — the codebase scan. Phases 2 and 3 run inline in the
parent agent (no separate sub-agent) because they require user
interaction for the candidate filter + the deepening loop.

## Output contract

- Phase 1 outputs a candidate inventory to stdout (not persisted).
- Phase 2 outputs the top 3-5 to stdout for user selection.
- Phase 3 (deepening loop) writes locked decisions to
  `.aperant/context/notes/{task-id}.md` via `apt-tools context write`
  and `apt-tools adr write` (the latter only when Nygard's 3-gate
  filter passes — most refactor decisions are reversible and stay in
  context-notes).
- The skill does NOT emit an implementation plan — that's `/apt:plan`'s
  job. apt:improve produces *what to refactor*; apt:plan produces *how*.
