---
name: pstack-principles
description: "Apply pstack's engineering principles to a coding decision. Use for /pstack-principles, or when you want the rigorous principle set that grounds architecture, verification, delegation, and code-quality choices. Referenced by the poteto-mode router."
license: MIT
metadata:
  adapted-from: "cursor/plugins/pstack/skills/principle-*"
  version: "1.0.0"
---

# pstack Engineering Principles

When a principle shapes a decision, name it in your reply and state the specific choice it changed. Each entry names when it applies.

## Core
- **Laziness Protocol** — refactoring, sizing a diff, or tempted to add abstractions/layers. Bias to deletion and the smallest change that solves the problem.
- **Foundational Thinking** — before writing logic. Design core types and data structures first; sequence scaffold before feature; name what concurrent actors share.
- **Redesign from First Principles** — integrating a new requirement into an existing design. Redesign as if it had been foundational from day one, not bolted on.
- **Attack the Premise** — when two or more fixes share one premise, they failed the same gate. Question the premise instead of writing another fix that assumes it.
- **Subtract Before You Add** — sequencing an addition/refactor/rewrite. Remove dead weight first, then build on the simpler base.
- **Minimize Reader Load** — reviewing or shaping hard-to-trace code. Count layers and hidden state, collapse one-caller wrappers, shrink mutable scope.
- **Outcome-Oriented Execution** — planned rewrites and migrations with phase boundaries. Converge on the target architecture; do not preserve throwaway compatibility states.
- **Experience First** — product/UX/scope tradeoffs. Choose user delight over implementation convenience.
- **Exhaust the Design Space** — a novel decision with no precedent. Build 2-3 competing prototypes and compare before committing.
- **Build the Lever** — non-trivial work. Build the tool that does or proves it (codemod, script, generator) rather than doing it by hand. The tool is the artifact a reviewer reruns.

## Architecture
- **Model the Domain** — stateful logic, or code that branches a lot or repeats a shape across files. Encode the domain in a structure (state machine, typed model, table/registry, reducer, boundary, the right collection) instead of scattered conditionals.
- **Boundary Discipline** — wiring validation, error handling, or framework adapters. Guards at system boundaries, trust internal types, keep business logic pure.
- **Type System Discipline** — designing types or a signature in a typed language. Make illegal states unrepresentable, brand primitives, parse external data at boundaries.
- **Make Operations Idempotent** — commands, lifecycle steps, or loops that run amid crashes and retries. Converge to the same end state.
- **Migrate Callers Then Delete Legacy APIs** — introducing a new internal API while old callers exist. Migrate and delete in one wave.
- **Separate Before Serializing Shared State** — concurrent actors might write the same file/branch/key/object. Eliminate the sharing first.

## Verification
- **Prove It Works** — after a task, before declaring done. Verify against the real artifact, not a proxy or "it compiles".
- **Fix Root Causes** — debugging. Trace each symptom to its root cause; reproduce first; ask why until you reach it.
- **Sequence Work into Verifiable Units** — multi-step work and how you stack commits/PRs. Small units that each end in a check; verify each before the next; order delivery so the sequence proves itself.
- **Test Behavior, Not Implementation** — writing/changing/keeping a test. Call the code as its users do and assert against a literal expected value. If the test would still pass when every imported function returns undefined, rewrite or delete it.

## Delegation
- **Guard the Context Window** — context fills up (large outputs, long files, repeated reads, fan-out). Route bulk to subagents; keep summaries in the main thread.
- **Never Block on the Human** — tempted to ask "should I do X?" on reversible work. Proceed, present the result, let the human course-correct.

## Meta
- **Encode Lessons in Structure** — you catch yourself writing the same instruction twice. Encode it as a lint, metadata flag, runtime check, or script instead of more prose.