Kiss

KISS

Measure twice, cut once. Every cut — every line written, edited, or deleted — is preceded by a measurement. Measure, cut once, confirm the cut landed clean. Most bloat and breakage is cheapest to prevent at the wellspring, before the cut exists; guards catch errors downstream, KISS prevents them at the source.

This is the front door. It does three things: holds the measure-twice discipline, runs a one-time kickoff that makes a project start clean, and routes to the focused KISS skills.

The pre-cut gate — before any write, edit, or delete

The two measurements already live in the focused skills. This gate just makes sure they happened before you cut:

If you can't answer a measurement, you have not measured twice. Stop and measure.

The two measurements people skip, and what they cost:

• Skipping the concept check is how one system ended up with eight implementations of "which agents are installed?" — each named differently, each locally clean, every twin-check passing. They drifted until the app told its own AI that agents which plainly existed did not exist. A symbol map cannot catch this; only grepping the store can.
• Skipping the incidental-prevention check is how a correct, cleaner refactor silently deleted a licence gate and, separately, un-hid an object that was never meant to be listed. Both passed 700+ tests, because the rule they destroyed was never tested — it was never even intended.

Kickoff — when starting a project or sizable feature

1. Plan into the frame → kiss-plan produces a design.md (modules, interfaces, verify-stepped build sequence) before code.
2. Build the map → kiss-map generates .kiss/inert.md, the cheap source-of-truth index the agent consults first.
3. Set the budget → kiss-modularity records the size/responsibility tiers.
4. Arm the guards → kiss-debt-guard installs the size audit + config; kiss-coherence installs the concept guard (fails the build when a second site starts deriving a concept that already has an owner) and seeds a concept index — question · canonical accessor · store · consumers.
5. Establish the design system → one source for the visual constants the UI reasons about — a type scale, a spacing scale, a color palette, radii — defined in a token file (the machine-readable source: tokens.css, Tokens.xaml, tokens.ts) and explained in a ## Design values section of design.md (the scale, the rungs, the rationale). This is a coherence store like any other: register the token file with kiss-coherence so a hardcoded literal that duplicates a token's value is caught as divergent duplication. Adopt it from the first line — no component hardcodes a value a token owns. A token layer with near-zero adoption is worse than none: it reads as a design system but every value is answered in N hardcoded places, so the app cannot be retuned from one file and every screen is hand- fixed forever. That section is a living deliverable — when the scale gains a rung, it is recorded there.

One design doc, and it is always design.md

Never split the design system into a second DESIGN.md. Windows (NTFS) and macOS (APFS default) are case-insensitive: design.md and DESIGN.md are the same file, so a system that asks for both is literally unbuildable on the two platforms most people use. On Linux it is worse than unbuildable — it succeeds, and you now have two rival answers to "where is the design recorded?", which is the precise duplication this skill exists to prevent. KISS must not violate KISS.

The plan (goal · modules · interfaces · build sequence) and the design values (tokens · scale · rationale) are sections of one file. If that file is getting long, that is a signal to shorten the prose — not to spawn a case-variant sibling. Applies to every doc this system emits: one concept, one file, one canonical spelling, lowercase.

Kickoff writes into the repo: design.md (plan and design values) + its token file, .kiss/inert.md (gitignored), a budget/guard config, and a short KISS contract merged into CLAUDE.md/AGENTS.md. That makes KISS a base, not advice.

Routing — during ongoing work

Retrofit — applying KISS to a codebase that was NOT built with it

Kickoff assumes greenfield: prevent at the wellspring. Most real work is the opposite — an existing codebase, written without KISS, that you are now cleaning. The hazards invert.

In greenfield you are stopping bad code from being written. In a retrofit the bad code is already load- bearing, and your clean-up is the most dangerous thing in the repo.

Retrofit order (do not reorder — later steps are riskier):

1. Measure, don't touch. File sizes, concept duplication (grep by store), dead code, doc drift. Produce the numbers before producing a diff. A guard that only inspects changed files says nothing about the codebase — run it over the whole tree.
2. Guards before cleanup. Install the ratchets first (kiss-debt-guard, kiss-coherence), with the existing violations recorded as tracked debt. This stops the bleeding while you work, and every subsequent step is verified as it lands.
3. Consolidate concepts (kiss-coherence) — this finds live product bugs, not just ugly code. It is the highest-value pass in a retrofit and the one no size audit can do for you.
4. Sweep dead DATA, not just dead code (kiss-coherence → the reverse pass). Run each store backwards: does every record still have an owner in code? Dead-code sweeps prove the code is gone and say nothing about the avatars, config rows, vaults and build artifacts it left behind — which a wildcard packaging glob will cheerfully ship. Check the deployed tree, not just the repo.
5. Split by byte-motion — pure moves, no logic changes. Cheap and safe.
6. Refactor logic last. Highest risk, lowest urgency. Often correctly deferred forever.

The retrofit-specific traps — all three cost real regressions:

• Deliberate behaviour that looks like a bug. Old code is full of odd-looking constructs that are load-bearing. A permissive default (unknown ⇒ enabled) may be the only reason new records appear at all. Investigate before "correcting", and when you conclude it's intentional, WRITE THAT AT THE SITE (kiss-coherence → Record the negative finding) — or you, or the next agent, will re-litigate it and eventually "fix" it into a real bug.
• Conditions that enforce a rule by accident. See kiss-blast-radius → the silent-deletion trap. Consolidation deletes conditions; some were doing a second, unwritten job. A green test suite does not protect you — the rule was never tested because it was never intended.
• Tests prove structure, not behaviour. In a retrofit the suite was written against the old shape. It will happily stay green while you change what the product does. Verify at runtime, on the actual surface.

And the finding worth carrying into every retrofit: code can be locally immaculate — small files, clean names, one responsibility each — and globally incoherent, with one concept answered eight different ways. Size audits score that codebase as excellent. Only a coherence pass sees it.

The model underneath

Every unit of code is a block: bounded, labeled, self-documenting, reusable, slotted into a known frame — the way a modular installer or a reusable UI panel is built. The plugin is the frame; each skill is a block. KISS keeps everything bite-size, human-legible, and easy to transplant — enforced by discipline, not by template files.