/principles

name: principles
description: "Twenty-four engineering principles in five groups, mapped to the lane carrying each — premise testing, root causes, honest verification, domain modeling, convergence, context discipline. For design, debugging, or delegation briefs."
aliases: []
metadata:
  credits:
    principles-library: pstack
    author: Lauren Tan
    url: "https://github.com/cursor/plugins/tree/main/pstack"
    port: pstack-claude
    port-author: Michael Denyer
    port-url: "https://github.com/michael-denyer/pstack-claude"

Engineering Principles

Twenty-four principles distilled for OMC's lanes from the pstack principle library (credited above) and rewritten against OMC's own mechanisms. Each names when it applies and which lane carries it. This is a discipline skill: it shapes how work is done; it never gates delivery on its own.

When to use

• a fix has failed twice, or two fixes share one explanation
• debugging, verification, or benchmarking work is starting
• a design choice repeats a shape assumption across files
• delegation prompts are being written and a lane's standing principles

should travel with the brief

When not to use

• a one-line mechanical edit with an obvious check
• a hotfix under time pressure — state which principle you skipped and why

in one line, then proceed

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. Composes with `minimal-code-discipline`. Carried by `executor` and `code-simplifier`.

Foundational Thinking

Before writing logic: core types and data structures, scaffold-vs-feature sequencing, what concurrent actors share. Carried by `architect` and `planner`.

Redesign from First Principles

Integrating a new requirement into an existing design. Redesign as if the requirement had been foundational from day one, instead of patching the old shape around it. Carried by `architect`.

Attack the premise

When two or more attempted fixes share one assumption and all failed the same gate, stop writing fix three. Write the shared assumption down, test it directly, and let the result choose the next move. Carried by `critic` during plan gap analysis and by `debugger` before a third retry.

Subtract before you add

Before sequencing an addition, refactor, or rewrite, remove the dead weight first and build on the simpler base. Carried by `executor` and `code-simplifier`.

Minimize reader load

Reviewing or shaping code that is hard to trace. Count layers and hidden state, collapse one-caller wrappers, shrink mutable scope. Carried by `code-simplifier` and `writer`.

Outcome-oriented execution

Planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; do not preserve throwaway compatibility states. Carried by `planner`.

Experience first

Product, UX, or feature-scope tradeoffs. Choose user delight over implementation convenience, and say the tradeoff out loud when you take it. Carried by `designer`.

Exhaust the design space

A novel interaction or architectural decision with no precedent. Build 2-3 competing options and compare before committing — the `arena` and `architect` skills are this principle operationalized. Carried by `architect`.

Build the lever

Any non-trivial repeated work. Build the tool that does or proves it — codemod, script, generator — rather than doing it by hand a third time; the tool is the artifact a reviewer reruns. Carried by `executor`.

Architecture

Model the domain

When stateful logic branches a lot or repeats a shape assumption across files, encode the domain in a structure — a state machine, a typed model, a registry, a reducer — instead of scattering conditionals. OMC's graph runtime (`graph` skill) is this principle at full size. Carried by `architect`.

Boundary discipline

Wiring validation, error handling, or framework adapters. Guards at system boundaries, trust internal types, keep business logic pure. Carried by `architect` and `executor`.

Type system discipline

Designing types or signatures in any typed language. Make illegal states unrepresentable, brand primitives, parse external data at boundaries; in TypeScript, `typescript-best-practices` grounds this in syntax. Carried by `architect` and `executor`.

Make operations idempotent

Design commands, lifecycle steps, and loops that run amid crashes and retries to converge to the same end state. OMC's team recovery replays worker checkpoints idempotently; user code deserves the same property. Carried by `executor`.

Migrate callers, then delete legacy APIs

Introducing a new internal API while old callers exist. Migrate every caller and delete the old surface in one wave; a compatibility shim with no expiry is a second system. Carried by `executor`.

Separate before serializing shared state

Concurrent actors might write the same file, branch, key, or object. Eliminate the sharing first (a writer per worktree is OMC's house form); locking is the fallback, not the first move. Carried by `executor` and `team`.

Verification

Prove it works

Done means verified against the real artifact — the command's actual output, the passing test, the rendered page — never a proxy and never "it compiles". The `verify` skill owns the evidence format. Carried by `verifier`.

Fix root causes

Trace each symptom to the first place the system went wrong and fix it there. A guard for a state that should not exist is a workaround, not a fix; it is legitimate only when that state itself is legitimate. Carried by `debugger`; `verifier` treats symptom-level patches as incomplete work.

Sequence work into verifiable units

Multi-step work — sweeps, migrations, runs of similar edits — and how commits and PRs stack. Small units that each end in a check, verified before the next, ordered so the sequence proves itself. Ca