principles

Principles

Each principle below names when it applies and the rule it sets. Read a principle's file in full before you apply it: the entry here is the pointer, the file is the principle.

Core

• Laziness Protocol. Refactoring, sizing a diff, or tempted to add abstractions, layers, or signal threading. Bias to deletion and the smallest change that solves the problem.
• Foundational Thinking. Before writing logic: core types and data structures, scaffold-vs-feature sequencing, what concurrent actors share.
• Redesign from First Principles. Integrating a new requirement into an existing design. Redesign as if it had been foundational from day one.
• Attack the Premise. Two or more fixes that share one premise have failed the same gate. Take a census of which actors hold the imbalance before the next fix, then question the premise instead of writing another fix that assumes it.
• Subtract Before You Add. Sequencing an addition, refactor, or rewrite. Remove dead weight first, then build on the simpler base.
• Minimize Reader Load. Reviewing or shaping code that's hard to trace. Count layers and hidden state, collapse one-caller wrappers, shrink mutable scope.
• Outcome-Oriented Execution. Planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture, don't preserve throwaway compatibility states.
• Experience First. Product, UX, or feature-scope tradeoffs. Choose user delight over implementation convenience.
• Exhaust the Design Space. A novel interaction or architectural decision with no precedent. Build 2-3 competing prototypes and compare before committing.
• Build the Lever. Any non-trivial work. Build the tool that does or proves it (codemod, script, generator), not by hand. The tool is the artifact a reviewer reruns.

Architecture

• Model the Domain. Writing stateful logic, or code that branches a lot or repeats a shape assumption across files. Encode the domain in a structure (state machine, typed model, table or registry, reducer, boundary, the right collection) instead of scattered conditionals.
• Boundary Discipline. Wiring validation, error handling, or framework adapters. Guards at system boundaries, trust internal types, keep business logic pure.
• Type System Discipline. Designing types or a signature, in TypeScript or in Lua with LuaLS annotations. Make illegal states unrepresentable, brand primitives, parse external data at boundaries.
• Make Operations Idempotent. Designing commands, lifecycle steps, or loops that run amid crashes, retries and resource restarts. Converge to the same end state.
• Migrate Callers Then Delete Legacy APIs. Introducing a new internal API while old callers exist. Migrate and delete in one wave.
• Separate Before Serializing Shared State. Concurrent actors might write the same file, branch, key, state bag, or row. Eliminate the sharing first.

Verification

• Prove It Works. After a task, before declaring done. Verify against the real artifact, not a proxy or "it compiles".
• Fix Root Causes. Debugging. Trace each symptom to its root cause, reproduce first, ask why until you reach it.
• Sequence Work into Verifiable Units. Multi-step work (sweeps, migrations, runs of similar edits) and how you stack commits and PRs. Break work into small units that each end in a check, verify each before the next, and order delivery so the sequence proves itself.
• Test Behavior, Not Implementation. Writing, changing, or keeping a test. Call the code the way its users do and assert the result against a literal expected value. If the test would still pass when every imported function returns undefined, rewrite the assertion or delete the test.

Delegation

• Guard the Context Window. Context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents, keep summaries in the main thread.
• Never Block on the Human. Tempted to ask "should I do X?" on reversible work. Proceed, present the result, let the human course-correct.

Meta

• Encode Lessons in Structure. You catch yourself writing the same instruction a second time. Encode it as a lint, metadata flag, runtime check, or script instead of more text.