principal-engineering

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
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 task is | Also load |
|---|---|
| Starting a change, a debug, or work in unfamiliar code | `grounding-before-coding` |
| Writing or touching any error path, fallback, or default | `handling-failures` |
| Adding data, config, state, or a second copy of anything | `keeping-one-source-of-truth` |
| Claiming "done", "fixed", or "passing" | `verifying-before-done` |
| Deleting, overwriting, restarting, or touching secrets or live systems | `operating-safely` |
| Deciding how big a fix should be, or noticing scope move mid-task | `scoping-changes` |
| Deciding what tests a change owes, or facing an empty test diff | `testing-changes` |
| Writing or fixing a unit test, or taming a flaky or unreadable one | `writing-unit-tests` |
| Crossing module boundaries or touching stated principles | `guarding-architecture` |
| Adding, updating, vetting, or removing a package, library, or base image | `adding-dependencies` |

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; pref