principal-engineering

name: principal-engineering description: Use when doing any non-trivial engineering work - implementing, debugging, refactoring, configuring, operating, or investigating why a system misbehaves - or any change where being wrong has a cost. Encodes the evidence-over-theory discipline, the hard safety rules, and the pre-change checkpoint. Use whenever code, data, or infrastructure is about to change or must be understood before it can, even if the task looks routine or is only "find out why". Foundation for the sibling skills.

Principal engineering

Overview

Check what the system actually does rather than recalling a pattern for it. Ground every decision in the real code and data, fail loud, keep one home per fact, and never claim done without the verification that proves it.

Sibling skills carry the depth: grounding-before-coding, handling-failures, keeping-one-source-of-truth, verifying-before-done, operating-safely, scoping-changes, testing-changes, writing-unit-tests, guarding-architecture, adding-dependencies. Load the matching one on top of this.

When to invoke

The documents around the work (specs, decisions, changelogs, runbooks, postmortems, issues) are the technical-writer plugin's job where installed; these skills govern the engineering itself and defer to it for the prose.

Scope limits

• Not a style guide: formatting, naming taste, and framework choice belong to the repository's own conventions, which win.
• Not a replacement for project instructions: CLAUDE.md and repository rules outrank everything here.
• Not a source of product decisions: what to build comes from the owner; this governs how built things stay true and safe.

Mandatory checkpoint before a non-trivial change

Before writing the first line, state in working notes:

Grounded: <what you read or ran to know the current behavior> | Blast radius: <what this change touches> | Invariants: <what must not break> | Verify: <the command that will prove it worked>

Fill it from the code and data, not from memory or plausibility. A field you cannot fill is the work you do first.

Hard rules

Non-negotiable, in every repository:

• No silent error swallows. Every catch and failure path logs and rethrows, returns a typed failure the caller must handle, or enters an explicitly documented degraded mode. A new silent swallow is an automatic review BLOCKER. See handling-failures.
• An applied migration is immutable history. Schema corrections are new additive migrations, never edits to an applied one.
• Never claim verified without naming what was checked. A "done" claim names the command and its result, quotes the output of every failing test, and names every skipped step. See verifying-before-done.
• Secret values are never read, printed, or decrypted to disk. Names and structural checks only; an auth failure means pause, never bypass.
• Destructive operations need eyes first. Look at the target before deleting or overwriting; ask before restarting or killing live services; prefer targeted operations over bulk ones.
• Evidence beats theory. Profile, query, and read before concluding; a signal that pattern-matches a known failure may have a different cause, so check that the evidence supports the specific action, not the familiar one.

Risk tiers set the rigor

The rules hold at every tier; the tier sets how much proof they demand. What sits in the top tier is the project's to declare: money paths in one system, the sales pipeline in another, stored user data, a medical record, a safety gate, an irreversible migration. The project's rules or CLAUDE.md name its top-tier paths; when they do not, ask what the system must never get wrong and treat the answer as the declaration.

Top-tier work gets maximum rigor: invariant tests, independent verification, and the full checkpoint taken literally. Ordinary paths get standard rigor. Tooling and throwaway work still obey the hard rules (a silent swallow in a script still hides failures) but earn no gold-plating. State the tier when it is not obvious; running top-tier work at tooling rigor is the expensive mistake, the reverse is the wasteful one.

The rule lifecycle

Something that bites twice becomes a written rule with its provenance (what happened, when, how to avoid it); once is learning. A rule that keeps triggering gets sharpened; a rule whose underlying cause is fixed gets retired. The recorded incident behind each rule is what stops it from being cargo-culted or wrongly deleted later.

Common mistakes

• Acting on a document's claim about the system instead of the system; doc status goes stale fast, the code and the history are the record.
• Fixing the symptom that pattern-matched instead of the cause the evidence shows.
• Treating "the tests are green" as "the change works"; a green suite over code that cannot work means the suite does not run or does not test.
• Leaving a duplicate untouched in code you are changing: a duplicate in code you touch gets absorbed as part of the work; one merely noticed elsewhere gets surfaced and tracked, not silently fixed and not silently left. See keeping-one-source-of-truth.
• Growing a fix past its trigger because improvements were adjacent. See scoping-changes.