principles
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.
Install
npx skills add https://github.com/OutlineDriven/odin-claude-plugin/tree/main/plugins/odin-code/skills/principles
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install outlinedriven-odin-claude-plugin@llmmart
git clone https://github.com/OutlineDriven/odin-claude-plugin.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole outlinedriven/odin-claude-plugin collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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.
Idempotent operations
Design every retryable operation so running it N times converges to the same state as running it once.
Bites when commands, loops, or migrations can be interrupted and re-entered.
Classify each side effect (naturally / conditionally / not idempotent) and replace or guard it; guards read state at execution time, never from cache; the rollback must itself be idempotent. Procedure and replacement table: references/idempotent-operations.md.
Encode lessons in structure
Turn a repeated instruction into an enforcement artifact (lint rule, check, CI gate, schema constraint) that fires on the violation, instead of re-telling it.
Bites when the same correction has been given more than once and a mechanism can catch it.
One violation per artifact; prove it fails before the fix and passes after; name the rollback. No preemptive rules without a named violation. When this anchor requires creating CI gates or lint rules, route to ci-cd.
Truth and proof
Fix root causes
Reproduce first, trace the why-chain to a decision in this project's source, fix the pattern at every instance, and reject any change that only silences the failure.
Bites when a defect is reported with wrong behavior (not a feature request).
Instrument rather than guess; a guard is legal only where the why-chain proves the state invalid. Procedure, symptom-fix rejection list, and failure classes: references/fix-root-causes.md. For the guarded repair loop with retry budgets, use strike-the-root; this anchor governs the diagnosis.
Prove it works
Completion claims require captured output from a real artifact, not a mock: state the claim, run the minimal verification command, record what it printed.
Bites when about to claim done.
Verification contradicting the claim stops the run: no re-running hoping for a different result, no substituting a test double, no claiming done while the reproduction fails.
Types and boundaries
Model the domain
Encode stateful, branch-heavy logic as a typed state machine so illegal states and transitions fail to compile.
Bites when flags and booleans track domain progress.
Enumerate states and transitions before writing types; one constructor per live state; validate reachability and migrate every caller, unmigrated call sites mean not done. When this anchor requires encoding the state machine in code, route to architect.
Type system discipline
Choose types so the compiler, not review, detects invalid and unhandled states: sum types for exclusivity, branded types for look-alike domains, literal unions for closed sets, exhaustive matches without wildcards.
Bites when designing types or signatures for a domain.
Compiler rejects valid code → widen; accepts invalid → narrow; re-run until both hold. The five moves and the tighten/loosen loop: references/type-system-discipline.md.
Foundational thinking
Settle the core types and data structures before writing any logic; data shapes that compose make downstream code obvious.
Bites when starting a feature or module.
Strongest available type (enums over strings, branded over bare, records over loose maps); validate at trust boundaries; if an operation needs a cast or escape hatch, extend the type set instead.
Boundary discipline
Validate once, at the trust boundary; the interior trusts validated types and carries only business logic.
Bites when placing validation and error handling.
Classify each guard boundary / interior / absent and move it outward to the seam; a thin shell means no nil-guards on data that entered validated. A guard that cannot move cleanly is a stop, not a partial move.
Separate before serializing
Fix shared-write races by splitting per-actor state out of shared scope before choosing a lock, then define the explicit read-boundary merge.
Bites when two or more actors write one mutable location.
Shared residue gets the narrowest primitive that covers the write path; a merge that cannot be expressed without a papering-over lock is a stop, not a lock. Procedure and failure classes: references/separate-before-serializing.md. When this anchor requires executing the split, route to strike-the-root.
Economy
Laziness protocol
Deletion first: anything the requirement sentence does not demand is a candidate for removal; every retained element carries a stated reason.
Bites when minimizing an implementation or refactor.
Reuse before new code; of two sufficient approaches pick fewer moving parts; note adjacent improvements in one line without doing them.
Minimize reader load
Collapse pass-through layers and narrow scopes until a fresh reader traces each state's origin and mutation in one pass, with behavior unchanged.
Bites when reading cost, not behavior, is the problem.
A forwarder survives only if it adds behavior, guards a boundary, or carries a needed name. An edit that changes behavior is restored immediately. When this anchor requires executing the collapse, route to deslop.
Experience first
Scope products to fewer fully polished experiences over many partial ones; every retained feature carries a one-sentence quality guarantee.
Bites when scope exceeds resources.
Cut stubs outright; cut partials that do not harm the core experience; never lower the quality bar to fit more features.
Decisions and attention
Exhaust the design space
For a novel interaction or architecture: three or more structurally distinct alternatives, criteria fixed before comparison, winner chosen on recorded evidence.
Bites when the choice is genuinely novel, not a parameter tweak.
Prototypes need only reveal the shape; a tie is documented, not broken arbitrarily.
Never block on the human
Proceed asynchronously on reversible work; park each irreversible item behind exactly one concrete question (target, consequence, recommended option).
Bites when deciding what needs a question before the human answers.
Reversible = undoable locally with no credential, publication, data-at-rest change, or destructive delete; uncertain means irreversible. Silence and timeouts are non-consent.
Guard the context window
Keep raw payload (full files, bulk search results) out of main context; delegate bulk reading or read selectively, carrying forward decisions and facts only.
Bites when context fills and reasoning room shrinks.
If the payload cannot be distilled into a decision, say so; do not pretend the context is clean.
Files (odin-claude-plugin)
-
agents
-
openai.yaml 216 B
interface: display_name: "Principles" short_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."
-
-
references
-
fix-root-causes.md 2.9 KB
# Fix root causes: procedure The diagnosis procedure behind the anchor. For the guarded repair loop with retry budgets, use `strike-the-root`; this file governs finding and removing the cause. 1. Restate the defect as expected vs actual in one sentence. A request for new behavior is a feature change, not a defect: stop. 2. Reproduce before any edit: build the smallest failing command, test, or scripted step. A fix for a failure you never observed cannot be verified. Done when: the reproduction fails now. 3. Bound scope: state the suspected root cause and the files it touches, before mutating. 4. Trace the why-chain: ask why the failure happens, then verify each answer against the source. Continue until the chain reaches a decision in this project's source that can be changed, not another symptom. Stuck → instrument (logging or assertions at the divergence point), rerun the reproduction, read the actual error. Done when: the chain terminates at a changeable decision. 5. Reject symptom fixes: a nil/null check to stop a crash, a swallowed or broadened catch, a disabled assertion or test. A guard is legal only where the why-chain proves the guarded state invalid, at the boundary where that state enters. Paragraph test: if the change needs a long justification comment explaining why it does not address the real cause, the code is wrong: return to step 4. 6. Fix the pattern, not the instance: search the project for the shape the why-chain identified (call sites, copies, near-identical guards) and fix every instance. Done when: a re-search for the shape returns none. 7. Intermittent or post-restart failures → suspect state before code: code does not change between runs, state does. Check stale persistent state first (config, caches, lock files, serialized state). If clearing a state file restores normal behavior, the fix is source-side validation or handling of that state, not a manual clearing step. 8. Verify: the reproduction now passes, the targeted checks covering the touched code pass, the shape search is clean, and every diagnostic added in step 4 is removed. ## Failure classes - Unreproducible: make no source change. Record the exact reproduction attempts and the evidence that would decide the why-chain; classify blocked. Never claim done without a passing reproduction. - Why-chain exits the project (dependency, platform, environment, data): report the chain and the external cause; do not patch around it. Blocked unless the project owns the decision. - Attempted fix fails verification: revert that attempt entirely, including its instrumentation; return to the why-chain. Never stack a new fix on a failed one. - Repeated-shape instance unfixable (generated, vendored, owned elsewhere): done does not hold. Report the instances left, the reason, and the state: root cause fixed, shape removal incomplete. - Never swallow an error to end the run; never report done while the reproduction fails or any instance of the shape remains. -
idempotent-operations.md 1.8 KB
# Idempotent operations: procedure The side-effect classification and convergence proof behind the anchor. 1. Bound scope: list every side effect the operation performs (file writes, database mutations, network calls, state transitions, external process invocations). Do not widen beyond the declared operation. 2. Classify each side effect: - Naturally idempotent (set a key to a value) → leave unchanged. - Conditionally idempotent (insert-if-absent) → add a precondition check: read current state, compare to target, skip if already applied. - Not idempotent (append, increment, send-and-forget) → replace with an idempotent equivalent: upsert not insert, set-union not append, compare-and-swap not increment. No equivalent → wrap in a completion guard that records done and short-circuits on re-entry. 3. Guards read state at execution time, never from cache, so concurrent or interleaved retries see the true current state. Done when: a re-entry after interruption detects the partial state and completes or skips. 4. Define a rollback path for every write; the rollback must itself be idempotent. 5. Convergence proof: executing the operation zero, one, two, or N times from any reachable intermediate state produces the same terminal state. Done when: convergence holds from an interrupted mid-state. ## Failure classes - Side effect with no idempotent form and no exclusion rationale: stop before convergence verification. Report the side effect and its classification. - External dependency diverges state: report the dependency and the divergence; do not suppress the check or widen scope to accommodate it. - Rollback not idempotent: redesign the rollback before declaring the operation idempotent. - Partial idempotency: report the non-idempotent subset; the operation is not declared idempotent until all side effects converge. -
outcome-oriented-execution.md 1.7 KB
# Outcome-oriented execution: procedure The rollback-anchor lifecycle and per-step verification behind the anchor. 1. Parse the plan: extract the target architecture and enumerate each step. Absent or incoherent plan → stop (plan-not-parseable). 2. Establish the rollback anchor before the first mutation: capture the pre-mutation state of every affected artifact. Cannot capture → stop, no mutation attempted (rollback-anchor-failed). 3. Validate reachability: confirm the target architecture is reachable from the current state via the plan steps. Not reachable → stop (target-unreachable). 4. Execute steps sequentially. For each step: apply it, then verify the step produced the intermediate state the plan predicts. Mismatch → roll back all mutations to the anchor and stop (step-N-verification-failed). Done when: each step's observed state matches its prediction. 5. Verify the end state: assert the resulting state matches the target architecture with no compatibility residue. Fail → roll back to the anchor (target-state-not-achieved). 6. Release the rollback anchor only after step 5 passes. ## Failure classes and outcomes - plan-not-parseable: blocked; no mutation. - rollback-anchor-failed: blocked; no mutation attempted. - target-unreachable: terminated with reason. - step-N-verification-failed: partial; rollback to pre-mutation anchor, completed steps listed, failed step named. - target-state-not-achieved: partial; rollback to pre-mutation anchor. - termination (human or plan signals the target is no longer achievable): stopped; roll back if changes exist. When stopped after step 4 or 5, rollback restores the pre-mutation state. Report each completed step, the failed step, and the rollback outcome. -
separate-before-serializing.md 1.9 KB
# Separate before serializing: procedure The classification, primitive choice, and merge-point design behind the anchor. 1. Inventory every shared mutable location (variable, struct field, object property, memory cell) that two or more actors (threads, coroutines, processes, tasks, agents) can write. 2. Classify each: - Per-actor: state private to one actor → migrate it into that actor's ownership. No actor writes another's per-actor state. - Shared: state genuinely required by multiple actors → synchronization. 3. For shared state, choose the narrowest primitive that covers the write path: mutex, lock-free structure, channel, or atomic. Low contention → lock-free or channel; complex critical-section logic → mutex. 4. Design every merge point where an actor reads or receives state from another. Name the merge operation explicitly; never let it occur implicitly inside a critical section. If the merge combines per-actor deltas (a reducer), define the merge function before introducing synchronization and verify it is associative and free of write-write conflicts. Done when: every cross-actor read passes through a named merge. 5. Revert all changes via VCS if any step cannot be completed safely. ## Failure classes - Undecouplable state: two actors cannot separate without breaking the required merge semantics. Stop; return the coupling points and the required merge. Do not introduce a lock that papers over the coupling. - Missing primitive: the environment lacks the selected synchronization. Stop; report the missing primitive and the state it would protect. - Deadlock risk: the merge point occurs inside a held lock and creates a cyclic wait. Revert; return the cycle with actor names and the merge point. - Partial separation: some shared state separates, some does not. Return the separable set with per-actor layout and merge points; flag the remainder unresolved. -
type-system-discipline.md 2 KB
# Type system discipline: procedure The five modeling moves and the compiler loop behind the anchor. 1. Enumerate every domain value, state, and operation as a named entity with its valid companions and exclusions. 2. Mutually exclusive entities → **sum type** (tagged union, discriminated union, sealed trait): holding one variant excludes the others at the type level. 3. Structurally identical but semantically distinct entities → **branded type** (newtype, opaque alias, nominal wrapper): the compiler rejects cross-domain interchange. 4. Fixed known values → **literal union** or **enum**: the compiler rejects any value outside the set. 5. Data structures: product types (structs, records) for coexisting properties; sum types from step 2 for mutually exclusive properties. Signatures: each parameter type accepts exactly the values the function handles; return types encode outcomes as a sum. 6. Exhaustiveness: every consumer of a sum type handles all variants: pattern match without wildcard, compiler flag, or exhaustive switch, so unhandled variants fail to compile. 7. Invalid-state probe: construct a literal example of an invalid domain state and confirm the type system makes it unrepresentable. If the compiler accepts it, return to step 2 or 5 and tighten. 8. Compiler loop: rejects valid code → widen the affected type; accepts invalid code → narrow it; rerun in both directions. Done when: valid code compiles and every probed invalid state is unrepresentable. ## Residue and failure - States that cannot be made static (cross-field constraints requiring runtime validation): document the remaining runtime guard explicitly in the code; the report names it. The type model is complete to the degree the language allows. - Ambiguous domain semantics: stop; report the ambiguous entities and ask for clarification. Do not guess. - Non-convergence after one tighten/loosen round: report which state cannot be made unrepresentable and why; leave existing types unchanged. - Rollback: revert the changed type-definition file to its prior content or restore from VCS.
-
-
SKILL.md 12.3 KB
--- 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`. ### Idempotent operations Design every retryable operation so running it N times converges to the same state as running it once. **Bites when** commands, loops, or migrations can be interrupted and re-entered. Classify each side effect (naturally / conditionally / not idempotent) and replace or guard it; guards read state at execution time, never from cache; the rollback must itself be idempotent. Procedure and replacement table: `references/idempotent-operations.md`. ### Encode lessons in structure Turn a repeated instruction into an enforcement artifact (lint rule, check, CI gate, schema constraint) that fires on the violation, instead of re-telling it. **Bites when** the same correction has been given more than once and a mechanism can catch it. One violation per artifact; prove it fails before the fix and passes after; name the rollback. No preemptive rules without a named violation. When this anchor requires creating CI gates or lint rules, route to `ci-cd`. ## Truth and proof ### Fix root causes Reproduce first, trace the why-chain to a decision in this project's source, fix the pattern at every instance, and reject any change that only silences the failure. **Bites when** a defect is reported with wrong behavior (not a feature request). Instrument rather than guess; a guard is legal only where the why-chain proves the state invalid. Procedure, symptom-fix rejection list, and failure classes: `references/fix-root-causes.md`. For the guarded repair loop with retry budgets, use `strike-the-root`; this anchor governs the diagnosis. ### Prove it works Completion claims require captured output from a real artifact, not a mock: state the claim, run the minimal verification command, record what it printed. **Bites when** about to claim done. Verification contradicting the claim stops the run: no re-running hoping for a different result, no substituting a test double, no claiming done while the reproduction fails. ## Types and boundaries ### Model the domain Encode stateful, branch-heavy logic as a typed state machine so illegal states and transitions fail to compile. **Bites when** flags and booleans track domain progress. Enumerate states and transitions before writing types; one constructor per live state; validate reachability and migrate every caller, unmigrated call sites mean not done. When this anchor requires encoding the state machine in code, route to `architect`. ### Type system discipline Choose types so the compiler, not review, detects invalid and unhandled states: sum types for exclusivity, branded types for look-alike domains, literal unions for closed sets, exhaustive matches without wildcards. **Bites when** designing types or signatures for a domain. Compiler rejects valid code → widen; accepts invalid → narrow; re-run until both hold. The five moves and the tighten/loosen loop: `references/type-system-discipline.md`. ### Foundational thinking Settle the core types and data structures before writing any logic; data shapes that compose make downstream code obvious. **Bites when** starting a feature or module. Strongest available type (enums over strings, branded over bare, records over loose maps); validate at trust boundaries; if an operation needs a cast or escape hatch, extend the type set instead. ### Boundary discipline Validate once, at the trust boundary; the interior trusts validated types and carries only business logic. **Bites when** placing validation and error handling. Classify each guard boundary / interior / absent and move it outward to the seam; a thin shell means no nil-guards on data that entered validated. A guard that cannot move cleanly is a stop, not a partial move. ### Separate before serializing Fix shared-write races by splitting per-actor state out of shared scope before choosing a lock, then define the explicit read-boundary merge. **Bites when** two or more actors write one mutable location. Shared residue gets the narrowest primitive that covers the write path; a merge that cannot be expressed without a papering-over lock is a stop, not a lock. Procedure and failure classes: `references/separate-before-serializing.md`. When this anchor requires executing the split, route to `strike-the-root`. ## Economy ### Laziness protocol Deletion first: anything the requirement sentence does not demand is a candidate for removal; every retained element carries a stated reason. **Bites when** minimizing an implementation or refactor. Reuse before new code; of two sufficient approaches pick fewer moving parts; note adjacent improvements in one line without doing them. ### Minimize reader load Collapse pass-through layers and narrow scopes until a fresh reader traces each state's origin and mutation in one pass, with behavior unchanged. **Bites when** reading cost, not behavior, is the problem. A forwarder survives only if it adds behavior, guards a boundary, or carries a needed name. An edit that changes behavior is restored immediately. When this anchor requires executing the collapse, route to `deslop`. ### Experience first Scope products to fewer fully polished experiences over many partial ones; every retained feature carries a one-sentence quality guarantee. **Bites when** scope exceeds resources. Cut stubs outright; cut partials that do not harm the core experience; never lower the quality bar to fit more features. ## Decisions and attention ### Exhaust the design space For a novel interaction or architecture: three or more structurally distinct alternatives, criteria fixed before comparison, winner chosen on recorded evidence. **Bites when** the choice is genuinely novel, not a parameter tweak. Prototypes need only reveal the shape; a tie is documented, not broken arbitrarily. ### Never block on the human Proceed asynchronously on reversible work; park each irreversible item behind exactly one concrete question (target, consequence, recommended option). **Bites when** deciding what needs a question before the human answers. Reversible = undoable locally with no credential, publication, data-at-rest change, or destructive delete; uncertain means irreversible. Silence and timeouts are non-consent. ### Guard the context window Keep raw payload (full files, bulk search results) out of main context; delegate bulk reading or read selectively, carrying forward decisions and facts only. **Bites when** context fills and reasoning room shrinks. If the payload cannot be distilled into a decision, say so; do not pretend the context is clean.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.