engineering-principles

name	engineering-principles
description	Execution and process principles for non-trivial engineering work, covering how to scope, sequence, delegate, and verify, independent of language or harness. Use when planning a change, sizing a diff, debugging, driving a long autonomous run, or deciding what "done" means. This is the process layer; code-design taste lives in the coding-standards skill.

Engineering Principles

These are execution principles: how to drive a piece of work from request to verified result. They are orthogonal to code-design taste. When a decision is about naming, types, modules, parsing, errors, or tests, that is the coding-standards skill, and these files defer to it rather than restating it.

Each principle is one file with one idea. Read the leaf in full when it applies; this index is only the router. They are referenced by name, not invoked as commands, and they apply the same whichever harness is driving (Claude, Pi, Codex, Cursor).

How this relates to coding-standards

coding-standards answers "is this code well-designed?" These principles answer "am I working on it the right way?" Where they touch the same ground, the principle points at the standard:

• Verification of a finished task lives here (PROVE_IT_WORKS.md); what a good test looks like lives in coding-standards/TESTING_AND_VERIFICATION.md.
• Diff size and deletion bias live here; module and interface design lives in coding-standards/DESIGNING_MODULES.md.
• Target-state-not-migration sequencing lives here; the no-backwards-compat design rule lives in coding-standards's non-negotiables.

If a leaf ever duplicates a standard, cut the leaf down to the part the standard does not own.

Principles

Read the matching leaf before applying it.

When you are...	Read...
Refactoring, sizing a diff, or tempted to add a layer or thread a new signal through types	LAZINESS_PROTOCOL.md
Sequencing an addition or rewrite and there is dead weight to remove first	SUBTRACT_BEFORE_YOU_ADD.md
Reviewing code that is hard to trace; counting layers, hidden state, one-caller wrappers	MINIMIZE_READER_LOAD.md
Doing any non-trivial or repeated work that a script, codemod, or generator could do and prove	BUILD_THE_LEVER.md
Finishing a task and about to declare it done	PROVE_IT_WORKS.md
Debugging a symptom and tempted to patch where it surfaced	FIX_ROOT_CAUSES.md
Diagnosing a hard bug or performance regression without a reliable reproduction	DIAGNOSE_HARD_BUGS.md
Stacking commits or PRs across a sweep or migration	SEQUENCE_VERIFIABLE_UNITS.md
Context is filling with large outputs, long files, or fan-out planning	GUARD_THE_CONTEXT_WINDOW.md
Tempted to ask "should I do X?" on reversible work	NEVER_BLOCK_ON_THE_HUMAN.md
Facing a novel decision with no precedent in the codebase	EXHAUST_THE_DESIGN_SPACE.md
About to write logic before settling the core data shapes	FOUNDATIONAL_THINKING.md
Catching yourself writing the same instruction a second time	ENCODE_LESSONS_IN_STRUCTURE.md

Every principle in the table has its leaf file.