demi

a demi-glace starts concentrated. nothing extra goes in just because the kitchen has it nearby. you do the same with code: build the smallest useful version that satisfies the ticket, fits the repo, and can be verified. complexity has to earn its way into the pan.

core principle: start simple enough that reduce should not be needed immediately afterward. small means understandable and verifiable, not cramped. the shortest version that hides intent is not demi; it is just dense.

intent

use demi before implementing, scaffolding, prototyping, or adding a feature when the work should start with the smallest useful code path, avoid speculative architecture, or prevent overbuilding before reduction would be needed. demi is a discipline for climbing from existing behavior to custom code in seven explicit steps, then shipping the minimum that works. apply it by default unless the task is architectural, touches public interfaces, is security-sensitive, or under-specified in a way that changes the outcome.

inputs

• task description or ticket: the actual ask in plain language; vague tickets require you to choose the smallest useful interpretation.
• repo context: access to existing code, helpers, components, configuration, conventions, naming patterns, and test harnesses already in place.
• language and framework standard library docs: built-in features (stdlib, native browser APIs, database features, shell commands, OS features, framework primitives).
• installed dependencies: list of third-party packages already in the project's package manager (npm, pip, go.mod, etc.), with version constraints.
• related skills: mise for missing context, recipe for sequencing multi-step work, taste for focused testing before confidence, check for verification before shipping, reduce only after code exists.

procedure

1. restate the actual ask

write one sentence that captures what the ticket really needs. if the request is vague (add a feature, improve performance, refactor), pick the smallest useful interpretation that still satisfies it. if the statement feels too broad, narrow it. if it feels incomplete, use mise to fill gaps before proceeding.

output: one-sentence restatement, written down or stated aloud.

2. find the local pattern

read the nearest existing code, helpers, tests, and naming conventions in the repo. do not start a research project; scan a few related files to see what the kitchen already does. if the repo has a similar feature or data shape, prefer the local pattern over what you know from other codebases.

output: identified pattern or helper (filename, function name, component name, or config convention).

3. climb the demi ladder

check each rung in order. stop at the first one that holds and satisfies the ask:

1. does this need to exist? if the current behavior already satisfies the ask, skip the change and document why.
2. can the repo already do it? use existing commands, helpers, components, config, conventions, and tests before inventing new ones.
3. does the standard library cover it? prefer built-in language or framework features over custom code.
4. does the platform cover it? native browser, database, shell, operating system, framework, or deployment features beat owned code when they fit.
5. does an already-installed dependency cover it? use what is already in the project. do not add a dependency for a few clear lines.
6. can one explicit local change do it? one function, one component, one endpoint, one flag, one small data path, with no new abstractions.
7. only then: write the minimum custom implementation that works and can be checked.

do not turn the ladder into a research project. if two rungs work, take the higher one unless the lower rung is more correct on edge cases.

output: the rung you land on (name it explicitly) and why.

4. name the smallest useful slice

define the first complete behavior the user can run, click, test, or review. this is not a line of code; it is a whole feature end-to-end that satisfies the ask and nothing more. ignore options, variants, edge cases that are not in the current ticket, and future growth paths.

output: clear description of what will work when done (e.g., "fetch a single user by ID and return their name and email address").

5. cut speculative scope

remove features, settings, abstractions, options, data models, and UI states that are not required for that slice. ask:

• is this required by the current request?
• does the repo already have a pattern for this?
• is there a standard library, platform, or existing dependency path?
• will at least two real callers use this now? (three is better for shared abstractions.)
• would a future maintainer understand this faster than the direct version?
• can i verify the behavior after this change?

if any answer is no, keep it local or do not build it.

output: list of what is intentionally not being built (and why).

6. pick the boring implementation

use direct code, existing helpers, and local composition. new abstractions need evidence (a second consumer, a third repeated pattern, a measured performance limit, a public API boundary, or an explicit user requirement).

prefer these moves:

• one vertical slice over a broad scaffold.
• one explicit function over a generic utility.
• existing components, commands, config, and test harnesses over new infrastructure.
• clear local logic over premature indirection.
• a small typed data shape over a general schema system.
• a direct ui state path over a reusable state machine.
• a narrow cli flag over an interactive prompt or new config file.
• a plain file or local module over a package, service, queue, plugin, or database.
• a small runnable check over a full testing framework when the repo does not already have one.

do not build these unless the current task proves they are needed:

• framework swaps.
• plugin systems.
• generic registries.
• new persistence layers.
• background workers.
• multi-provider abstractions.
• config formats for a single value.
• theme systems for one screen.
• large component libraries for one view.
• repository-wide rewrites.
• public api reshapes.
• "future-proof" abstractions without a future requirement.

output: implementation sketch or decision (e.g., "add one function to index.ts using the repo's existing request helper").

7. set a growth trigger and verify

write down what future fact would justify expanding the design: a second consumer, a third repeated pattern, a measured performance limit, a public api boundary, or an explicit user requirement. do not design for growth; design for today.

run the narrowest meaningful check through check. if behavior is hard to pin down, use taste for a focused test before expanding.

output: growth trigger (written) and verification command or user-visible proof (passed).

decision points

if the task is vague or under-specified (and it changes the outcome): use mise to gather context first. do not proceed with demi until the actual ask is clear.

if the task is architectural, touches public interfaces, or is security-sensitive: report the demi plan (one-screen plan, below) and wait for explicit approval before implementing. do not assume you can narrow the scope alone.

if a rung higher than "custom code" holds (e.g., an existing feature already does it): skip the change and document why. this saves work and keeps the repo lean.

if the smallest useful slice is unclear or depends on user feedback: use taste to prototype a minimal version first, then build the real slice based on what users say.

if the work is multi-step and sequencing matters: use recipe to plan the sequence. use demi on each recipe task to keep individual steps small and verifiable.

if the implementation has known ceilings (e.g., single-user lock, linear scan below X files, native date input without custom picker): name the ceiling inline or in a shortcut note (below). document what fact would trigger a redesign.

if the code is complete but behavior is hard to verify: use check before claiming done. if a full test harness is not in place and is not being added, use taste for focused validation.

output contract

a demi pass produces one or more of these deliverables, depending on the task:

• one-screen plan (if work is non-trivial):

  ## demi: <task>
  
  actual ask: <one sentence>
  smallest useful slice: <what will work when done>
  highest rung that holds: <existing behavior | repo primitive | stdlib | platform | installed dependency | local change | custom code>
  existing pattern to follow: <file/helper/test/component or none>
  cut from scope: <what is intentionally not being built>
  growth trigger: <what would justify expanding later>
  verification: <command/check/user-visible proof>
  

• implementation: code, config, or schema that satisfies the slice and passes verification.
• growth ceiling note (if applicable): inline comment or shortcut note naming the ceiling and the trigger for expansion (e.g., "global lock is fine for single-user cli; move to per-account locks if concurrent accounts matter").
• verification proof: passing check command, test output, or user-visible behavior.

outcome signal

you know demi worked when:

• the plan is written (one-screen plan or conversation note) before coding.
• the rung you landed on is named and justified.
• the implemented slice is narrow enough to review in one sitting and complete enough that a user can test it end-to-end.
• the code uses existing repo patterns and helpers instead of inventing new ones.
• verification is narrower than a full test suite but proves the behavior works.
• future scope is explicitly named (growth trigger), not left ambiguous.
• the work feels done, not halfway to a bigger design.

if you find yourself designing a framework, debating abstractions, or adding options before two real use cases exist, you have missed demi. pause and reread step 5 and step 6.

one-screen plan template

for non-trivial work, write this before editing:

## demi: <task>

actual ask: <one sentence>
smallest useful slice: <what will work when done>
highest rung that holds: <existing behavior | repo primitive | stdlib | platform | installed dependency | local change | custom code>
existing pattern to follow: <file/helper/test/component>
cut from scope: <what is intentionally not being built>
growth trigger: <what would justify expanding later>
verification: <command/check/user-visible proof>

keep it short. this is a guardrail, not a design doc. once you land on a rung and name the slice, start coding.

mode

demi is apply-by-default. after the quick pass (steps 1-4), implement the smallest slice unless the task is architectural, public-interface-heavy, security-sensitive, under-specified in a way that changes the outcome, or the user explicitly asks for options first. in those cases, report the demi plan and wait.

for large work, combine with recipe: use demi to keep each recipe task small, vertical, and verifiable.

boundaries

• use mise when context is missing.
• use recipe when the work needs sequencing across multiple steps.
• use taste when the slice needs focused tests before confidence.
• use check before claiming done.
• use reduce only after code exists and needs behavior-preserving cleanup.

not skimping

demi is not permission to be careless. never simplify away:

• trust-boundary validation.
• error handling that prevents data loss.
• security controls (auth, authorization, input sanitization, rate limiting).
• accessibility basics (keyboard navigation, semantic html, alt text, contrast).
• compatibility shims that protect real users.
• calibration or tuning points for real hardware or external systems (timeouts, retries, connection pooling).
• tests or checks for non-trivial branches, loops, parsers, money paths, auth paths, or security-sensitive logic.
• anything the user explicitly asked for after you challenged the scope once.

a simple implementation without a check is not finished. use the smallest meaningful check, not necessarily the biggest test harness.

common mistakes

mistake	reality
building a full framework because the feature might grow	growth is a trigger, not a prediction. ship the slice.
adding config before there are real variants	one value can be code. two may still be code. three starts a conversation.
creating a generic utility from one use	that is not reuse, it is disguise. keep it local.
scaffolding every future state	build the path the user asked for and leave clean edges.
calling fewer files "less complex"	a thousand-line god file is not demi. small means understandable, not cramped.
picking the shortest algorithm when it drops edge cases	lazy means less owned code, not flimsier behavior. correctness wins ties.
skipping local pattern discovery	simple in isolation can be weird in the repo. match the kitchen.
treating yagni as technical debt	yagni keeps quality high and scope small. skimping leaves a mess for later.