Principles Overview
A principle in pstack is a short, named rule about how an agent should make one kind of decision. pstack ships 24 of them. Each lives in its own skill file, skills/principle-<name>/SKILL.md, which poteto-mode calls the principle’s leaf. A leaf states when the rule applies and what the agent should do, and little else.
Principles are never invoked on their own: every leaf carries disable-model-invocation: true in its front matter. They take effect through /poteto-mode, the operating-style skill that keeps an index of all 24 and decides which ones a task triggers (see Using /poteto-mode).
How principles work
The “Principles” section of poteto-mode’s SKILL.md is the index. Each entry gives a principle’s title and a one-line trigger, the situation in which it applies. According to the principles guide, poteto-mode reads this index at the start of every multi-step task.
The index is only a pointer. For any principle it actually applies, the agent must first read the full leaf. The leaf’s skill name follows a fixed rule: principle- plus the title in kebab case, keeping hyphens and removing any other punctuation. The only entry that overrides this rule is Sequence Work into Verifiable Units, whose leaf is principle-sequence-verifiable-units.
Naming applied principles
Among poteto-mode’s non-negotiables is a reporting duty. In its reply, the agent must name each principle that shaped a decision and state the specific choice that principle changed. It may cite only principles whose leaf it read during the current session.
The guide adds a test for these citations. A principle named with no decision attached means the agent cited the rule without applying it. When you review a reply, look for the pair (principle, changed decision) and treat a bare name as a warning sign.
Steering with principle names
You never invoke a principle yourself. Instead, you use its name to redirect the agent. Because each name points at a complete rule the agent has already read, one phrase carries more precise instructions than a paragraph of explanation. The guide gives 3 examples, quoted here:
| Situation | What you type |
|---|---|
| The agent is about to add a fourth adapter beside 3 existing ones | use subtract before you add. delete the obsolete adapters first, then design what's left. |
| The agent claims success because the build passed | apply prove it works. run the real import flow and show me the written records. |
| 2 parallel attempts are about to write to the same branch | separate before serializing shared state. give each attempt its own worktree, no locks. |
The guide’s advice on learning the list is to skim it once and return to it whenever you see the agent do something one of these names would have prevented.
Upstream categories and this book’s chapters
The poteto-mode index sorts the 24 principles into 5 categories:
| Category | Count | Scope |
|---|---|---|
| Core | 10 | How much to build and when to rethink the design |
| Architecture | 6 | Where state, validation, and compatibility live |
| Verification | 5 | What counts as proof |
| Delegation | 2 | Keeping parallel work manageable |
| Meta | 1 | Turning repeated advice into structure |
This book uses its own grouping of 4 chapters, arranged by the stage of work in which a principle tends to matter. Every principle appears in exactly one chapter. The tables below give each trigger in brief; the chapters explain each rule and link its leaf.
Premises and Thinking
| Principle | Skill | Applies when |
|---|---|---|
| Attack the Premise | principle-attack-the-premise | 2 or more fixes sharing one premise have failed the same gate |
| Foundational Thinking | principle-foundational-thinking | Before writing logic: choosing core types, ordering scaffold and feature work, deciding what concurrent actors share |
| Redesign from First Principles | principle-redesign-from-first-principles | A new requirement must be integrated into an existing design |
| Exhaust the Design Space | principle-exhaust-the-design-space | A novel UI interaction or architectural decision has no precedent in the codebase |
| Model the Domain | principle-model-the-domain | Writing stateful logic, or code that branches heavily or repeats a shape assumption across files |
| Laziness Protocol | principle-laziness-protocol | Refactoring, judging diff size, or feeling tempted to add abstractions, layers, or signal threading |
Quality and Verification
| Principle | Skill | Applies when |
|---|---|---|
| Prove It Works | principle-prove-it-works | A task is finished but not yet declared done |
| Fix Root Causes | principle-fix-root-causes | Debugging |
| Test Behavior, Not Implementation | principle-test-behavior-not-implementation | Writing, changing, or keeping a test |
| Explain the Number | principle-explain-the-number | Before measuring, and before trusting, reporting, or acting on a measured number |
Design and Boundaries
| Principle | Skill | Applies when |
|---|---|---|
| Boundary Discipline | principle-boundary-discipline | Wiring validation, error handling, or framework adapters |
| Type System Discipline | principle-type-system-discipline | Designing types or signatures, or writing code in any statically typed language |
| Minimize Reader Load | principle-minimize-reader-load | Reviewing or shaping code that is hard to trace |
| Subtract Before You Add | principle-subtract-before-you-add | Sequencing an addition, refactor, or rewrite |
| Build the Lever | principle-build-the-lever | Any non-trivial work: edits, migrations, analyses, checks |
| Encode Lessons in Structure | principle-encode-lessons-in-structure | You write the same instruction a second time, or notice a recurring correction |
Execution and Operations
| Principle | Skill | Applies when |
|---|---|---|
| Sequence Work into Verifiable Units | principle-sequence-verifiable-units | Work done in several steps (sweeps, migrations, series of similar edits), and stacks of commits or PRs |
| Make Operations Idempotent | principle-make-operations-idempotent | Designing commands, lifecycle steps, or loops that run amid crashes, restarts, and retries |
| Migrate Callers Then Delete Legacy APIs | principle-migrate-callers-then-delete-legacy-apis | Introducing a new internal API while old callers still exist |
| Separate Before Serializing Shared State | principle-separate-before-serializing-shared-state | Concurrent actors might write to the same file, branch, key, or state object |
| Guard the Context Window | principle-guard-the-context-window | Context is filling up: large outputs, long files, repeated reads, fan-out planning |
| Never Block on the Human | principle-never-block-on-the-human | You are tempted to ask “should I do X?” about reversible work |
| Outcome-Oriented Execution | principle-outcome-oriented-execution | A planned rewrite or migration with explicit phase boundaries is under way |
| Experience First | principle-experience-first | Product, UX, or feature-scope trade-offs come up |
How to read the next chapters
Each leaf is brief. None runs much past 15 lines, and the body of Exhaust the Design Space is a single sentence. In the shortest leaves, the description field carries most of the rule, so the chapters draw on both the description and the body. For every principle, the chapters cover the rule itself, the situations that trigger it, and how you can use its name when steering.