Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

SituationWhat you type
The agent is about to add a fourth adapter beside 3 existing onesuse subtract before you add. delete the obsolete adapters first, then design what's left.
The agent claims success because the build passedapply prove it works. run the real import flow and show me the written records.
2 parallel attempts are about to write to the same branchseparate 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:

CategoryCountScope
Core10How much to build and when to rethink the design
Architecture6Where state, validation, and compatibility live
Verification5What counts as proof
Delegation2Keeping parallel work manageable
Meta1Turning 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

PrincipleSkillApplies when
Attack the Premiseprinciple-attack-the-premise2 or more fixes sharing one premise have failed the same gate
Foundational Thinkingprinciple-foundational-thinkingBefore writing logic: choosing core types, ordering scaffold and feature work, deciding what concurrent actors share
Redesign from First Principlesprinciple-redesign-from-first-principlesA new requirement must be integrated into an existing design
Exhaust the Design Spaceprinciple-exhaust-the-design-spaceA novel UI interaction or architectural decision has no precedent in the codebase
Model the Domainprinciple-model-the-domainWriting stateful logic, or code that branches heavily or repeats a shape assumption across files
Laziness Protocolprinciple-laziness-protocolRefactoring, judging diff size, or feeling tempted to add abstractions, layers, or signal threading

Quality and Verification

PrincipleSkillApplies when
Prove It Worksprinciple-prove-it-worksA task is finished but not yet declared done
Fix Root Causesprinciple-fix-root-causesDebugging
Test Behavior, Not Implementationprinciple-test-behavior-not-implementationWriting, changing, or keeping a test
Explain the Numberprinciple-explain-the-numberBefore measuring, and before trusting, reporting, or acting on a measured number

Design and Boundaries

PrincipleSkillApplies when
Boundary Disciplineprinciple-boundary-disciplineWiring validation, error handling, or framework adapters
Type System Disciplineprinciple-type-system-disciplineDesigning types or signatures, or writing code in any statically typed language
Minimize Reader Loadprinciple-minimize-reader-loadReviewing or shaping code that is hard to trace
Subtract Before You Addprinciple-subtract-before-you-addSequencing an addition, refactor, or rewrite
Build the Leverprinciple-build-the-leverAny non-trivial work: edits, migrations, analyses, checks
Encode Lessons in Structureprinciple-encode-lessons-in-structureYou write the same instruction a second time, or notice a recurring correction

Execution and Operations

PrincipleSkillApplies when
Sequence Work into Verifiable Unitsprinciple-sequence-verifiable-unitsWork done in several steps (sweeps, migrations, series of similar edits), and stacks of commits or PRs
Make Operations Idempotentprinciple-make-operations-idempotentDesigning commands, lifecycle steps, or loops that run amid crashes, restarts, and retries
Migrate Callers Then Delete Legacy APIsprinciple-migrate-callers-then-delete-legacy-apisIntroducing a new internal API while old callers still exist
Separate Before Serializing Shared Stateprinciple-separate-before-serializing-shared-stateConcurrent actors might write to the same file, branch, key, or state object
Guard the Context Windowprinciple-guard-the-context-windowContext is filling up: large outputs, long files, repeated reads, fan-out planning
Never Block on the Humanprinciple-never-block-on-the-humanYou are tempted to ask “should I do X?” about reversible work
Outcome-Oriented Executionprinciple-outcome-oriented-executionA planned rewrite or migration with explicit phase boundaries is under way
Experience Firstprinciple-experience-firstProduct, 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.