engineering-principles

name	engineering-principles
description	Methods inside a caller-owned lifecycle: diff sizing, work sequencing, refactoring, debugging, commit stacks, verification, context pressure, recurring corrections, and tool choice.

Engineering Principles

Sixteen principles, one index. Match the situation to a row, then read that reference in full before applying it. Each reference is short.

Principle	Apply when
laziness-protocol	Refactoring, sizing a diff, or tempted to add abstractions, layers, or signal threading.
model-the-domain	Stateful logic, repeated shape assumptions, or branching spread across files.
separate-before-serializing-shared-state	Multiple writers contend for one slot, cache, or merged config value.
boundary-discipline	Validation, error handling, parsing, framework adapters, or external data.
make-operations-idempotent	Activation, migration, install, retry, or hook paths that can run twice.
type-system-discipline	Types or signatures in a statically typed language.
subtract-before-you-add	Sequencing an addition, refactor, or rewrite. Remove dead weight first.
migrate-callers-then-delete-legacy-apis	Replacing an API or call path. Migrate callers and delete the old path together.
minimize-reader-load	Code that requires too many layers or too much hidden state to understand.
fix-root-causes	Debugging. Trace each symptom to its root cause; reproduce first.
sequence-verifiable-units	Multi-step work and commit or PR stacking. Verify each unit before the next.
verified-slice	Implementing one reviewable, reversible unit with evidence and commit authority.
prove-it-works	After completing a task, before declaring done. Check the real artifact.
guard-the-context-window	Context fills up: large outputs, long files, repeated reads, fan-out planning.
encode-lessons-in-structure	The same instruction gets written a second time, or a correction recurs.
build-the-lever	Non-trivial edits, migrations, analyses, or checks. Build the rerunnable tool.

Cite a principle only when it changed a concrete choice. A citation with no decision behind it means the reference was skipped.

Workflow skills reference principles by short name, for example "the prove-it-works principle". Resolve those names against this index.

Seven principles adapt pstack guidance. Upstream terms are in LICENSE.