Pragmatic Engineering

---
name: pragmatic-engineering
description: Keep engineering boring and complete. TRIGGER when the Architect says KISS, pragmatic, don't overengineer, ship it, keep it simple, or asks for a pragmatic read on a Proposal, Plan, code review, or Architectural Decision. DO NOT TRIGGER when the Architect asks for maximum rigor over shipping pressure.
---

# Pragmatic Engineering

- One Process: ship the smallest complete change that preserves the User's Capability and the Architecture.
- Most time savings come from deletion, not acceleration.

## 1. Question the requested work

Prove the requested work serves the User before preserving it. Question Agent-generated work especially hard.

### Read before correcting the Architect

Correct the Architect only after reading the code. Never say "You're absolutely right!" before Verification.

IF you see assumed intent:
### Stop and research before proceeding

Do not continue from a guess.

## 2. Delete

Remove dead paths, duplicated choices, unused indirection, and code that does not serve the Goal. If deletion breaks a Capability, restore only the Capability.

### Delete more than you create

A pragmatic change removes work before it adds work.

## 3. Simplify

Do not optimize code that should not exist. Keep files small, dependencies one-way, and each module cheap to rewrite.

### Avoid speculative abstraction

Abstract after three concrete uses, never before.

IF you see abstractions "for later" or two-way dependencies:
### Stop and simplify before proceeding

The simplest complete path is the one with the fewest moving parts that still preserves the User Capability.

### Measure before you set a limit
Do not pick a cap or timeout by feel. Measure the real case, set the limit well past it, and write the measurement next to the number. Then only something broken hits the limit.

### Make the limit speak when hit
The error names the limit, its value, and what was asked for. A silent limit is worse than no limit.

## 4. Use existing code and libraries

Reuse repo Precedent and well-maintained third-party code before writing local machinery. Read the library behavior before building on it.

IF you see duplicated third-party functionality or building before understanding library behavior:
### Stop and research the library first

Never rebuild behavior a library already owns.

## 5. Speed up

Improve performance only after deletion, simplification, and reuse. Developer experience beats runtime performance until measured User harm proves otherwise.

IF you see optimization before deletion:
### Delete first

Do not accelerate a path that should not exist.

## 6. Automate last

Automating unnecessary work preserves the wrong path. Automate only the Process that survived the first five steps.

IF you see automation before simplification:
### Simplify before automating

Automate the surviving Process, not the first Process you found.

## 7. Report failures immediately

State the blocker, the paths attempted, and the ranked options.

IF you see hidden errors or claimed completion without Verification:
### Stop and report the failure

Never work around a failure silently.