improvement-driver

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
# auto-detects repo+branch from the git remote; add --reload to re-index after a push

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.