| name | improvement-driver |
| description | Drive a full improvement cycle for a codebase: analyze the repo with Greptile (AI codebase search that returns cited file:line evidence) to surface concrete improvement opportunities, score and rank them with an auditable weighted formula (IQS — impact, reach, alignment, effort, risk, confidence), scaffold the chosen improvement into a new numbered spec that matches the project's spec format, then hand the spec to the spec-ensemble-driver skill to design and implement each section. Use this whenever the user wants to "find improvements and implement them", "analyze the code and turn the best idea into a spec", run an improvement/refactor/tech-debt pass that ends in shipped code, generate a new spec from a codebase audit, use Greptile to understand or audit a codebase, or chain codebase analysis → spec generation → implementation. Trigger on requests to audit/analyze a codebase for improvements, prioritize tech debt or enhancements by score, spin up a new spec from findings, run a Greptile-powered codebase analysis, or run an end-to-end "improve the code" loop — even if the user doesn't name this skill. This is the orchestrator that wraps Greptile analysis and spec-ensemble-driver with an auditable scoring front-end and spec scaffolding. |
Improvement Driver
Turn "make this codebase better" into shipped, spec-backed change. The cycle has
three phases, each ending at a checkpoint so the user steers before you spend
real work: Analyze → Spec → Implement. The value is that improvements are
chosen by an auditable score (not a vibe), captured as a real spec (not an
ad-hoc patch), and built through the ensemble (multiple models design each
section, best one wins).
This skill is an orchestrator. It owns Phase 1 (analysis + ranking — powered by
Greptile for codebase understanding) and Phase 2 (spec scaffolding), then
delegates Phase 3 to the spec-ensemble-driver skill, which already designs
and implements a spec one § at a time.
When this applies
The user wants improvements found and acted on — a tech-debt pass, a refactor
sweep, "what should we fix next and then fix it", or "audit the code and turn the
best idea into a spec". If they only want a one-off bug fix with a clear repro,
or they already have a spec to work through, this is overkill — for the latter,
go straight to spec-ensemble-driver.
Prerequisites
- Phase 1 uses Greptile: set
GREPTILE_API_KEY in the skill's .env (copy
.env.example, chmod 600). Greptile indexes the GitHub remote, not your
working tree — so the repo must be pushed, and recent local-only changes won't
be analyzed until committed and pushed. GitHub access uses GITHUB_TOKEN or
falls back to gh auth token. Full setup + API details: references/greptile.md.
- Phase 3 uses spec-ensemble-driver, which needs
OPENAI_API_KEY,
GEMINI_API_KEY, and OPENROUTER_API_KEY in its .env.
Confirm the keys for a phase before promising to reach it, so you don't strand the
user mid-cycle. The scripts fail loudly on a missing key (naming it) rather than
fabricating output — relay which key to set; never work around it.
Phase 1 — Analyze and rank (Greptile-powered)
Understand the whole repo through Greptile, then produce a ranked list of
concrete improvement candidates, each backed by cited file:line evidence and a
score. Greptile does the understanding; you steer the questions and own the
ranking. Breadth matters here; depth comes later (only the winner gets a spec).
1.1 Index and run the analysis battery
Greptile indexes the GitHub remote and answers natural-language questions about
the code with cited sources. Make sure the repo is pushed first (Greptile sees
the remote, not your working tree), then run the analysis driver, which indexes
(or reuses an existing index) and runs a battery of improvement-finding queries:
python3 ~/.claude/skills/improvement-driver/scripts/greptile_analyze.py \
--out /tmp/improvement-driver/findings.json
The default battery asks one question per analysis axis — spec/constitution
drift, invariants stated in prose but unenforced, ripe deferred work (TODO /
"future spec" / stubs), duplication, test gaps, fragile error paths — each
demanding file:line citations. Tune the battery to the repo (--queries PATH);
it's the lens Phase 1 looks through. Details and the override format:
references/greptile.md.
If Greptile is unavailable or the key is missing, the script says so and stops.
You may fall back to a manual survey (read the constitution/specs and grep the
axes above) — but say plainly that you're working without Greptile's evidence, and
candidates will carry weaker citations.
1.2 Distill findings into scored candidates
Read findings.json and distill discrete improvement candidates — one row per
actionable change, not one per query (a single query often surfaces several). Keep
each candidate's Greptile citations as its evidence trail. Then estimate the six
IQS dimensions per candidate and run the scorer so the ranking is reproducible.
Full formula and rubric: references/scoring.md.
python3 ~/.claude/skills/improvement-driver/scripts/score_improvements.py \
--in /tmp/improvement-driver/candidates.json \
--out /tmp/improvement-driver/ranked.json
Each candidate needs: impact, reach, alignment, effort, risk (each
0–10) and confidence (0.0–1.0). The script computes IQS (0–100), sorts
descending, and emits a markdown table. Effort and risk are costs — high
values lower the score. Confidence scales the whole thing, so a high-impact idea
you're unsure about is honestly ranked below a sure thing.
You assign the dimension estimates, anchored on Greptile's cited evidence — that's
the judgment. The script makes the arithmetic deterministic and the ranking
auditable, the same discipline spec-ensemble-driver applies with WEQS.
1.3 Checkpoint — present the ranking
Show the ranked table and stop. Don't scaffold a spec until the user picks.
## Improvement candidates (ranked by IQS)
| IQS | Title | Why it matters | Effort/Risk |
|------|--------------------------------|-----------------------------------|-------------|
| 78.4 | Enforce determinism AST check | Spec 0003 invariant unguarded | low / low |
| 64.1 | Dedup runtime audit writers | 3 copies drift; one bug fixed 1x | med / low |
| 51.9 | Doc the resume CLI | onboarding friction | low / low |
Top pick by score: **<title>**. Want me to scaffold this into a spec, pick a
different one, or combine a few? (Score ranks them; you decide what we build.)
A high score doesn't override judgment — if the user knows a lower-ranked item is
strategically urgent, that wins. The score informs; it doesn't dictate.
Phase 2 — Scaffold the new spec
Once the user picks an improvement, turn it into a new numbered spec that
matches this project's existing spec format, so spec-ensemble-driver has real
sections (§) to work through.
2.1 Match the house format
Read the most recent spec in specs/ (e.g. the highest-numbered directory) and
mirror its structure exactly — numbering scheme, front-matter line, section
headings, constitutional-alignment section. Don't invent a format. The repo's
convention is the contract. Details and a worked template: references/spec-scaffold.md.
2.2 Create the spec skeleton
Allocate the next spec number (highest existing NNNN + 1), make
specs/NNNN-<slug>/spec.md, and write the section skeleton: real headings and a
one-to-three-line intent under each, but leave the design content thin — the
ensemble fills it in Phase 3. At minimum mirror the house sections (typically:
Problem, Goals/Non-goals, Constitutional alignment, Architecture broken into
numbered subsections, Testing/verification). The Architecture subsections are the
§ units spec-ensemble-driver will iterate over, so make them concrete and
single-purpose.
2.3 Checkpoint — confirm the spec shape
Show the user the spec skeleton (the heading outline + intents) and stop.
This is the cheapest moment to fix scope. Confirm:
- the section breakdown is right (these become the ensemble's work units),
- the problem framing matches what they picked,
- the ensemble keys are configured if they want to proceed to implementation now.
Ask: "Approve this spec outline to start the ensemble loop on §, or adjust
the sections first?"
Phase 3 — Design and implement via the ensemble
Hand off to spec-ensemble-driver. Invoke that skill and let it run its loop on
the new spec, one § at a time: fan each section out to the model ensemble,
score with WEQS, re-rank, implement the winner, and checkpoint. Do not
reimplement that loop here — it owns the design-and-build mechanics.
Your orchestration job during Phase 3:
- Point spec-ensemble-driver at
specs/NNNN-<slug>/spec.md and the first §.
- Between sections, keep the thread coherent: the spec is being filled in as it's
implemented, so after each section is approved, make sure the spec doc reflects
what was actually built before the next § starts.
- When all sections are done, do a final pass: confirm the spec's Goals are met,
tests pass, and summarize what shipped against the original IQS rationale —
closing the loop back to why this improvement was chosen.
Notes on judgment
- One winner per cycle. Resist scaffolding five specs at once. The cycle is
cheap to repeat; a focused spec is worth more than a sprawling one. Run the loop
again for the next improvement.
- The score serves the decision, it doesn't make it. IQS sequences options and
makes the trade-offs explicit. The user (and your reading of the codebase) still
owns the call — especially when strategic urgency outranks raw score.
- Keep artifacts inspectable. Candidates and rankings live under
/tmp/improvement-driver/; the spec lives in specs/. Each phase leaves a
durable trace so the chain analyze → spec → code is auditable end to end.
- Don't skip checkpoints. The three stops (ranking, spec outline, then each §
via the ensemble) are what keep an autonomous-feeling loop from running off in
the wrong direction. They're cheap; a wrong spec is not.
