Next Best Improvement

Nextreme Next-Best-Improvement — The Extreme Fragment Engine

This skill produces one insane, taste-driven, proof-backed improvement to a single feature-flow-level fragment that survives review: every change is on a new branch, every before/after is shown, every win is benchmarked. The output is not a vague suggestion — it is a merged-ready branch + proof pack with disciplined diff, measured gains, and zero AI slop. You get three deliverables: the branch, the before/after + diff, and the proof/benchmarks.

You are extreme and unbound inside the picked part — you can do anything that leads to improvement — but you are disciplined about how you pick. You scan the whole project with commonsense (never a 20-line README or a trivial util), surface feature-flow-level candidates that noticeably need it, then you must create a new branch before you touch a file, and must pick exactly one fragment via the 3-mode menu. Inside that part, you have full creative freedom to brainstorm extreme, out-of-the-box solutions.

Why This Is Not Generic

Most “improve” skills are bounded: they polish the file you pointed at, or they pick the easiest line to lint. They never ask what deserves to be improved, they never create a branch, and they never prove the win — so the diff is noise and the improvement is invisible.

This fuses the core of next-best-thing (smallest high-leverage move) and nextreme-decision (commit to one insane pick) but refuses their bounds.

If the picked part wants a better improvement that no pattern names, invent it — but keep it branch-isolated, validated, and proven.

Golden Code Quality Rules — ENFORCED

These are non-negotiable. Every branch and every script this skill ships must pass them. Violation = task fails.

Keep code human-readable, small, and obvious. No AI slop.

• Names tell the truth — variables/functions reveal intent. No data, info, result, handler, manager, helper, utils, foo.
• One job per unit — if you need "and" to describe what a function does, split it. Files own one domain.
• Guard clauses over nesting — early returns, fail fast. No pyramids, no else after return. Nesting past 2–3 levels is a signal to restructure.
• No duplication — never copy-paste. Third occurrence of the same logic = must abstract. Two is coincidence, not a pattern.
• No dead weight — zero dead code, commented-out code, console.log, unused imports. Delete, don't comment out.
• Types are contracts — no any, no silent as casts, narrow unknown explicitly. At an untyped boundary (JSON.parse, third-party API), a cast is allowed only alongside visible runtime validation.
• Errors never silent — every failure path is handled, returned, or logged with context. Never an empty catch, never a swallowed promise.
• No magic — no unexplained numbers or strings. Name every constant. No cryptic one-liners.
• Explicit dependencies — no hidden globals, no surprise side effects. Inputs in, outputs out. Pure where possible.
• Readability > cleverness — code reads like prose: linear flow, consistent style, self-documenting. Comments explain why, not what.
• No premature abstraction — no wrappers, layers, or helpers you don't need today. YAGNI. Abstract on the real second pattern.
• Leave it cleaner, not bigger — boy-scout only on touched code.
• State assumptions, don't guess silently — if the spec is ambiguous, say what you assumed and why, in a comment or PR note.

Auto-rejected AI slop: placeholder TODO without a ticket, generic scaffolding, empty try/catch, lorem-ish names, duplicated boilerplate, over-engineered factories/managers, unvalidated as casts at boundaries, silent assumptions about ambiguous specs, inconsistent style within one file, and fragment-level slop: improving a trivia file, working on main, no before/after, no proof, Click to add residue, overlapping UX.

Improvement Axes — You Can Do Anything Inside the Picked Part

All ship: scripts/branch_guard.py (branch gate) + scripts/proof_builder.py (before/after + benchmarks). You choose the axis per fragment — state the one-line justification.

Core Workflow — Extreme but Gated

Each step ends on a completion criterion. Do not proceed until it passes.

1. Scan — Understand the Whole Project with Commonsense

Map the repo as nextreme-plans would: glob + grep + read key files, but filter with taste. Surface feature-flow-level candidates that noticeably need extreme improvement — a whole feature, a major section, a subsystem, a critical flow — never a 20-line README, never a single trivial helper. Use commonsense: if you need “and” to describe what the part does for a user, it’s probably too small.

Reference: references/scan-guide.md — what counts as a part, how to surface 5–8 candidates.

Completion criterion: 5–8 candidates listed, each is a feature-flow (file group or flow) with one-line why it noticeably needs it; no trivia.

2. Branch — Hard Gate (Cannot Proceed Without It)

Create a new branch before you read the picked part for edit. This is not optional.

git checkout -b next-best-improvement/<slug>
# slug = kebab of the fragment (e.g. event-graph-ingest)

If branch creation fails, stop and fix git — do not touch a file on main.

Reference: scripts/branch_guard.py — idempotent branch creation, dirty-tree check.

Completion criterion: git branch --show-current is next-best-improvement/<slug> and git status is clean (or stashed) — proven by command output.

3. Ask — Present the 3 Choices (You Must Ask)

Present exactly this menu and wait — the pick is the unique bit:

Pick one fragment to extremely improve:

1. Specific — you tell me the part (e.g. “the ingestion pipeline”)
2. Yolo — I pick the single fragment that most needs extreme improvement
3. Random — I surface candidates then randomly pick one

Reply with 1, 2, or 3 (or the part name for 1).

Do not auto-pick, do not collapse choices. If the user pre-answered in their prompt (yolo, random, improve X), honor it and skip the wait — but still log which mode was used.

Completion criterion: one mode is chosen and one fragment is locked (name + path + why it was picked); logged as mode: user|yolo|random.

4. Extreme Brainstorm — Out-of-the-Box Before You Code

For the locked fragment, propose 3 insane alternatives before you commit to one. Each is a different axis (e.g., architecture vs perf vs product rethink). Make them out-of-the-box, not safe tweaks. Then commit to one extreme pick and state why it wins — like nextreme-decision but inside the fragment.

Reference: references/improvement-axes.md — how to make alternatives actually distinct.

Completion criterion: 3 distinct extreme alternatives listed + one committed pick with one-line “why this is the most insane win”.

5. Improve — Do Anything Inside the Picked Part

Implement the committed pick. You can do anything that leads to improvement — refactor, redesign, add deps, delete code, add tests, change API (with migration note if breaking), speed up, repolish UX. Keep blast radius to the picked part, but do not be tame inside it.

• Keep main’s tests green on the picked part’s scope; fix root causes, not symptoms.
• Follow Golden Rules — no AI slop leaves this step.

Completion criterion: the picked part is modified on the new branch, validate (tests / validate_<artifact>.py / tsc / lint whatever the fragment owns) is green, and no file outside the fragment was touched without an explicit note.

6. Proof — Before/After + Benchmarks (You Must Prove)

Build the proof pack the user asked for — what changed and what/how it was before, with numbers:

• Diff: git diff --stat + key git diff hunks (or screenshots for UX).
• Before/after: 2–3 concrete snippets or screenshots (e.g., “before: 6h batch, after: 4m streaming”).
• Benchmarks: whatever proves the win — time, hey, pytest, tsc --noEmit, validate output, Lighthouse, or a before/after table with before | after | Δ.

Reference: scripts/proof_builder.py — collects diff, snapshots, and benchmark stubs.

Completion criterion: proof pack exists as proof/<slug>.md (or PR description) with diff stat, 1–2 before/after pairs, and at least one measured proof (numbers, not adjectives).

7. Validate — No Silent Failure

Run the lightest validation that fully fits the fragment: tests, tsc, lint, build, validate script. If the baseline was red, your change must not make it worse — report the baseline.

Completion criterion: validation command output is pasted in proof, exit 0 (or baseline-red acknowledged).

8. Deliver — Branch + Proof, Not Vague Advice

Report: the branch name, the picked mode + fragment + why, the extreme pick + why it won, the proof pack path, and the one open risk.

Do not merge. Do not push unless the user says so — git-guardrails applies.

Completion criterion: report lists branch, mode, fragment, extreme pick, proof path, and open risk; no merge/push without explicit go-ahead.

Quick Picks — What a “Part” Looks Like (Do Not Start From Trivia)

Never: README 20 lines, utils/foo.ts, a single helper. If you can’t name the user flow it serves, it’s not a part.

Troubleshooting — No Glitch Is “Weird — Ignore It”

Reference Files

• references/scan-guide.md — what counts as a part, how to surface 5–8 candidates with commonsense, how to avoid trivia.
• references/improvement-axes.md — 6 axes (architecture, perf, UX, correctness, DX, product) with insane examples + how to make 3 alternatives distinct.
• scripts/branch_guard.py — hard gate: creates next-best-improvement/<slug> from clean tree, refuses to proceed on main without branch.
• scripts/proof_builder.py — proof pack: git diff --stat, before/after snippets/screenshots, benchmark stub (time/tests/validate), writes proof/<slug>.md.
• references/workflow.md — the 8-step workflow in one page (for quick lookup).

Principles — The Nextreme Signature (Extreme Inside, Disciplined at Edges)

• You decide the pick — but you justify. Every yolo/random pick ties to one line about why this fragment noticeably needs it. “Why this part?” is answered, not shrugged.
• One fragment, one insane win. Never improve two parts in one run; the extreme is diluted. Route cleanly.
• Branch is law. No improvement exists outside a new branch. The gate is not a suggestion.
• Anything inside, discipline outside. Full creative freedom inside the picked part; Golden Rules and validation outside.
• Proof over adjectives. An extreme claim without numbers is slop. Benchmarks are the taste.
• Ghost the trivial. If the scan surfaces a 20-line util, ghost it — it was never a candidate.