/principles

name: principles
description: 'Use when a request names a working principle (subtract before you add, idempotent operations, never block on the human) or asks which principle applies. Not for running a repair: use strike-the-root.'
disable-model-invocation: true

Principles

Indexed anchor register: 21 named principles, each a law plus the moment it bites. Read the index, jump to the anchor, apply the law. Principles governs judgment only and never executes or mutates. When an anchor requires mutation or execution, route the user to the owning skill (`strike-the-root`, `architect`, `deslop`, `commit`, `ci-cd`) instead of instructing execution. Come here to decide, not to run a repair.

Five anchors carry procedure-dense references (linked inline); the rest are complete at anchor length.

Contract

| Field | Bound contract | |---|---| | Trigger | A request names a working principle by name or example, or asks which principle governs a decision. | | Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. Names the owning skill for execution. | | Side effect | Guidance in chat output only. No file, VCS, credential, paid, published, deployed, or remote mutation. | | Done | The governing principle is named with its law and bite point, and the owning skill is named when the anchor requires execution. |

Index

| Anchor | Governs | |---|---| | Subtract before you add | land deletions first, as their own commit | | Sequence verifiable units | per-unit checks, halt at first failure | | Outcome-oriented execution | plan → rollback-anchor migration | | Migrate callers, then delete | one-wave API replacement | | Redesign from first principles | requirement integration without bolt-ons | | Build the lever | hand-do one, codify, rerun | | Idempotent operations | retries converge to one state | | Encode lessons in structure | repeated instruction → enforcement artifact | | Fix root causes | why-chain over symptom patching | | Prove it works | captured evidence from the real artifact | | Model the domain | typed state machines, illegal states fail compile | | Type system discipline | compiler as the proof of constraints | | Foundational thinking | types before logic | | Boundary discipline | validate once, at the seam | | Separate before serializing | per-actor state before locks | | Laziness protocol | deletion-first smallest change | | Minimize reader load | one-pass state trace | | Experience first | fewer polished over many partial | | Exhaust the design space | 3+ distinct alternatives, criteria first | | Never block on the human | reversible proceeds, irreversible parks | | Guard the context window | decisions in context, payload out |

Sequencing and structure

Subtract before you add

Land obsolete-code deletions as their own green commit before the addition or rewrite starts, so the new work rests on a simpler base.

**Bites when** an addition or rewrite lands on code the new design obsoletes.

The deletion commit is the recovery anchor: if the gate fails after deletion, revert it and abort the addition; if it fails after the addition, fix forward, never revert the subtraction to mask an addition bug. Announce the deletion set and get confirmation before staging; a narrowed-to-empty set skips straight to the addition. When this anchor requires landing commits, route to `commit`.

Sequence verifiable units

Decompose multi-step work into units, each with a named check; halt the sequence at the first failing check and report that unit only.

**Bites when** work decomposes into two or more units, each verifiable in isolation.

Map the dependency graph first; units at the same depth may run in parallel. A failed unit means no partial commit and no success summary.

Outcome-oriented execution

Execute a planned migration stepwise against a rollback anchor, verifying each step's predicted intermediate state; roll back to the anchor on any mismatch.

**Bites when** a plan names a target architecture and the intermediate breakage is reversible.

Establish the anchor before the first mutation; release it only after the end state verifies. Procedure and failure codes: `references/outcome-oriented-execution.md`. When this anchor requires executing the migration, route to `strike-the-root`.

Migrate callers, then delete

Replace an internal API by migrating every caller in one wave, proving zero references remain, then deleting the legacy path under VCS.

**Bites when** an API replacement is scoped and every caller is enumerable.

A missed caller after deletion → restore from VCS, migrate it, redo the verify-and-delete. An ambiguous caller halts the wave before any mutation. When this anchor requires executing the migration, route to `architect`.

Redesign from first principles

Integrate a new requirement by resolving it against named invariants and propagating structural edits everywhere the answer changes, never bolting it on at one site.

**Bites when** a requirement lands that the current structure only half-fits.

Name the invariants first; a conflict is resolved by revising the principle or reshaping the requirement, never suppressed. Partial propagation is a stop, not a done. When this anchor requires propagating structural edits, route to `architect`.

Levers and enforcement

Build the lever

For non-trivial repetitive work: do the first unit by hand, codify the recipe into a deterministic rerunnable script, prove it reproduces the hand-done unit, then run it for the rest.

**Bites when** work repeats and is more than a couple of obvious edits.

Pick the artifact by intent: edits → codemod; repeated files → generator; analysis → structured query; verification → rerunnable check with an explicit pass/fail contract. Commit the lever when the work outlives the session; a reviewer must be able to rerun it without session context. When this anchor requires building and committing the lever, route to `commit`.

Ide