improvement-cycle

name

improvement-cycle

description

Use when doing self-directed, iterative improvement of this codebase — "improve the UX", "find things to improve", "keep improving X", run improvement cycles, or generate/work a backlog. Encodes how to DISCOVER improvement points yourself (by investigating source code and the web), adversarially VERIFY them against the real code, and IMPLEMENT them one verified cycle at a time. Tuned for kd's UI/UX work but the loop is general.

Improvement cycle

A repeatable loop for finding and shipping improvements without a human spelling each one out. The single most important lesson: a generated idea is a hypothesis, not a fact — verify it against the actual code before building.

The loop

DISCOVER → VERIFY (adversarial) → RANK → IMPLEMENT one → VERIFY LIVE → TEST → COMMIT → GROOM

One improvement per commit; don't batch. Keep the backlog current so the loop survives compaction.

1. DISCOVER — generate candidates yourself

Two complementary sources:

• Source code investigation (primary, highest signal): read the focus area's files (file map in AGENTS.md). Look for UX gaps a user would feel, missing affordances, inconsistency with sibling features, fragile coupling, missing a11y, reactivity smells, dead controls, silent failures. Every candidate MUST cite file:line evidence.
• Web / docs research (secondary, "what good looks like"): Context7 MCP for library best practices; comparable tools (k9s / Lens / ArgoCD / Grafana) for UX patterns — then check whether kd already does it before proposing.

Fan out with a Workflow when the area is broad (one Explore agent per focus area returning structured candidates, each finding piped to an independent skeptic) — only when the user has opted into orchestration.

Decide directions yourself — don't ask the user. When a candidate needs a design call, make the best decision against the four design principles + the user's stated UX values, implement it, and note the reasoning in the commit. Do NOT pause with AskUserQuestion for feature direction — the user wants sustained autonomous progress; iteration after shipping is cheap. Reserve questions for destructive/irreversible actions or a hard external blocker.

2. VERIFY — adversarial, before building anything

For each candidate, try to refute it against the real code. Default to rejecting:

• already-handled — the code already does this (cite where).
• wrong — the premise misreads the code.
• risky — real, but the change would regress or fight an existing design choice.
• low-value — real, but a user wouldn't meaningfully feel it.
• real — genuine, correct, non-regressing, clearly felt. Only these get built.

Not optional: the refute rate was ~30% early and ~94% on a mature surface — most generated ideas do not survive contact with the code.

3. RANK

Value×effort, high-value / low-effort first, using the verifier's adjusted numbers (it saw the real code; the proposer guessed).

4. IMPLEMENT one cycle

The smallest change that delivers it. Match surrounding style; comments explain WHY. Any visual change follows the four design principles + explicit-over-implicit in docs/design.md.

5. VERIFY LIVE

Drive the actual UI per docs/live-debug.md (demo cluster, agent-browser, measurement pitfalls) — measure the thing you changed; a screenshot shows layout, an eval proves behaviour. kd-specific discovery recipes and recurring bug classes: dogfooding-kd-ui.md in this skill. Live driving has repeatedly caught bugs unit tests could not.

6. TEST

Add/extend a unit test for the durable contract. Mind jsdom limits (docs/client-gotchas.md): assert the DOM contract that enables a behaviour and rely on live verification for the behaviour itself.

7. COMMIT + GROOM

One Conventional Commit per cycle (git ops only per the session's standing permission); the commit message is the durable "what + why". Then groom durable state: shipped → delete the backlog row; refuted → check the owning site's comments and git log, add a missing durable constraint at the code site, or drop the candidate when no such constraint exists.

Backlog

docs/backlog.md (git-tracked) feeds and records the loop. Format + lifecycle: the backlog-management skill — don't restate its schema here. docs/plans/ is gitignored single-session scratch, never the backlog.

STOP condition

When a strict re-survey yields ≈0 high-value real items, the surface is mature: stop generating, record the maturity in the backlog's Status line, and switch to user-driven or new-feature work. Don't grind filler cycles. Scale effort to the request — a quick "find a bug" needs a small pass; "exhaustively improve" justifies a fan-out with multi-vote verification.