# Aif Improve

> Find architectural deepening opportunities in existing code — shallow modules to make deep, tightly-coupled modules to consolidate, seams worth adding for testability and AI-navigability. Judges depth with the deletion test and reports evidence-backed candidates ranked by recommendation strength, never touching code until you pick one. Optionally reads a domain glossary (CONTEXT.md) and decision…

- **Type:** Skill
- **Install:** `agentstack add skill-ainative-build-skills-aif-improve`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ainative-build](https://agentstack.voostack.com/s/ainative-build)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ainative-build](https://github.com/ainative-build)
- **Source:** https://github.com/ainative-build/skills/tree/main/skills/engineering/aif-improve

## Install

```sh
agentstack add skill-ainative-build-skills-aif-improve
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# aif-improve

Find where the structure of working code makes it harder to test and change than it needs to be, and
propose **deepenings** — changes that trade a pile of shallow modules for a smaller number of deep
ones. Every candidate carries evidence; no code changes until you pick one.

**Principles:** depth over extraction · evidence over taste · propose, don't touch.

This is not a diff review (that's `aif-code-review`) and not a task map (that's `aif-recon`). It
reads existing code and asks a different question: *where is the structure making this harder to
understand, test, and change than it needs to be — and what deeper shape would fix it?* `aif-code-review`
may hand off paths to this skill via its non-blocking **Deepening pointers** footer — a review that
kept bumping into pre-existing shallowness points here rather than restructuring inside a merge gate.

The lens is module **depth** (Ousterhout, *A Philosophy of Software Design*): a deep module hides a
lot of behavior behind a small interface. See `references/module-depth.md` for the working
vocabulary — use it exactly, so suggestions stay consistent.

Self-contained — built-ins only: `git`, `Glob`, `Grep`, `Read`, `Bash`, and (where available) the
`Task` tool for parallel exploration. Read-only in steps 1–2; step 3 edits code only after you pick
a candidate and agree the design.

## Workflow

```
1. Explore        → read optional domain docs, then walk the code for friction   (orchestrator)
2. Present        → evidence-backed candidates, ranked; ask which to pursue        (orchestrator)
3. Deepen         → design the interface with the user, then implement one         (orchestrator)
```

### 1. Explore

**Optional context first (only if present — never required):**
- `CONTEXT.md` / a domain glossary → use its nouns to name modules (the "Order intake module", not
  "the FooBarHandler"). If absent, name modules after what they do.
- `docs/adr/` (or `docs/decisions/`) → decisions already made. Do not re-litigate a settled ADR;
  only reopen one when the friction is real enough to warrant it, and say so explicitly.

**Explorer:** if the `aif-recon` skill is installed, use it to map the target area (pass the path or
area, no `--spec` needed). Otherwise scout inline: `Glob`/`Grep` to size the space, then read the
owners. On runtimes with the `Task` tool, fan out read-only `Explore` subagents over disjoint
directories; otherwise sweep sequentially.

Read through the target area the way you would to make a change, and note friction as you hit it —
don't grind a checklist:
- understanding one concept requires bouncing between many small modules (no **locality**);
- a module is **shallow** — its interface is nearly as wide as its implementation;
- pure functions were extracted only for testability, but the real bugs live in how they're *called*;
- tightly-coupled modules leak state or assumptions across their **seam**;
- a part of the codebase is untested, or can't be tested through its current interface.

Apply the **deletion test** (`references/module-depth.md`) to anything that smells shallow: paste it
into its callers in your head. If nothing gets harder, it was decoration — the deepening candidate you
want. If each caller inherits a copy of the hard part, it was already doing its job — leave it.

### 2. Present candidates

Do NOT design interfaces yet. Report per `references/opportunity-report.md`: each candidate as a card
with the modules involved, the friction (concrete `file:line` evidence), the deletion-test result,
the proposed deepening in plain English, the payoff in **leverage** + **locality** + test surface, a
before→after sketch, and a **recommendation-strength** badge (`Backed` / `Worth a look` /
`Speculative`). Carry over the evidence discipline from the review skill: every claim gets a
`[Verified]` (a grep/count/test you ran, with output) or `[Reasoned]` tag, and any candidate whose
value hinges on a fact you couldn't confirm gets a `> Conditional:` line.

End with a **Top recommendation** — which one to tackle first and why. Then ask the user: *"Which of
these would you like to pursue?"*

With `--html`, also write the self-contained visual report (`references/opportunity-report.md` →
HTML) to the temp dir and open it; markdown in chat stays the default.

### 3. Deepen a candidate

Once the user picks one, design the deeper module *with* them before writing code — see
`references/deepening-patterns.md`. Walk the interface: the constraints, what sits behind the seam,
which tests survive, what the caller no longer needs to know. Only cut a seam once a second
implementation is present or clearly imminent — a seam with one thing plugged into it is a bet, not a
need.

Side effects happen inline as the design settles, and only when the relevant doc already exists or
the user opts in:
- **Naming a module after a concept not in `CONTEXT.md`** (and `CONTEXT.md` exists) → offer to add
  the term, so the domain language and the code stay in sync.
- **User rejects the candidate for a load-bearing reason** (and `docs/adr/` exists) → offer to record
  an ADR, framed as *"so future architecture reviews don't re-suggest this"*. Skip ephemeral reasons
  ("not now") and self-evident ones.

Then implement the agreed change. Verify through the new interface — run the tests that should still
pass, and any new one the deepening makes possible. Never claim the refactor is done without running
the proving command and reading its output (same verification gate as the review skill).

## Input

| Invocation | Scans |
|-----------|-------|
| `aif-improve` | the whole repo (sampled — discloses coverage) |
| `aif-improve src/payments/` | a scoped path or area |
| `aif-improve "the auth flow"` | an area named in prose (resolved to files first) |
| `… --html` | also emit the visual before/after report to the temp dir |

For a whole-repo scan, disclose coverage honestly — "walked N of M modules, sampled by …" — and never
imply exhaustiveness you didn't reach.

## Tools used

Built-ins only: `git`, `Glob`, `Grep`, `Read`, `Bash`, plus the `Task`/`Agent` tool for parallel
exploration where available, and `Edit`/`Write` in step 3 only. On Codex/Cursor, map these to that
runtime's search / file-read / shell / edit equivalents — the capability is what matters, not the
name. Prefers the `aif-recon` skill for exploration when installed; falls back to inline scouting.

## References

- `references/module-depth.md` — the depth vocabulary (module, interface, depth, seam, leverage,
  locality) + the deletion test and the principles that rank candidates.
- `references/opportunity-report.md` — the markdown candidate-card format, recommendation strength,
  evidence rules, and the optional `--html` visual scaffold.
- `references/deepening-patterns.md` — common shallow→deep patterns and the interface-design walk for
  step 3, plus the optional CONTEXT.md / ADR side-effects.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ainative-build](https://github.com/ainative-build)
- **Source:** [ainative-build/skills](https://github.com/ainative-build/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ainative-build-skills-aif-improve
- Seller: https://agentstack.voostack.com/s/ainative-build
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.