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

Design and Boundaries

The 6 principles in this chapter concern the shape of the code: where its defenses sit, how much the types are made to enforce, and how much a reader must hold in mind. The chapter closes with 2 principles that turn design effort into lasting artifacts, namely tools and structural checks. A principle is a named pstack rule kept in its own skill file (its leaf); /poteto-mode reads the index of all principles and applies those a task triggers, as the Principles Overview explains.

Boundary Discipline (principle-boundary-discipline)

Source: skills/principle-boundary-discipline/SKILL.md

  • Rule: concentrate validation, type narrowing, and error handling at the points where data crosses a system boundary, such as CLI arguments, config files, external APIs, and the network. Inside the system, trust the types; re-validation and redundant nil checks have no place there.
  • Parsing and surfaces: parse raw data into domain types at the boundary, and keep transport and framework types off the public surface.
  • Pure core, thin shell: business logic belongs in pure functions that depend on no framework. The shell that calls them stays thin.
  • The 2 tests from the leaf:
    1. Does this data cross a boundary at this point? When it does not, the check duplicates protection that already exists.
    2. Could this logic become a pure function for the shell to call? When it could, move it out.
  • Steering: name this principle when defensive checks start multiplying in internal code.

Type System Discipline (principle-type-system-discipline)

Source: skills/principle-type-system-discipline/SKILL.md

  • Rule: let the compiler reject impossible states, mismatched primitives, and unhandled variants. It applies when designing types, reviewing a function signature, or writing code in any statically typed language.
  • Brand semantic primitives: if 2 arguments share a primitive type but carry different meanings, give each its own type and validate the value once, when it is created.
  • Parsing external data: the leaf treats anything from outside (JSON, RPC payloads, CLI arguments, config, environment variables, database rows) as untyped until a parse function at the boundary has converted it into the typed model.
  • Derive from authoritative schemas: if a schema file is the owner of a shape, generate the type from that file rather than keeping a separate hand-written copy in parallel.
  • Exhaustive variants: the description adds that every variant should be handled, so the compiler can flag any case left uncovered.
  • Related skill: for TypeScript syntax, the leaf refers to typescript-best-practices (see Building and Code Quality).

Minimize Reader Load (principle-minimize-reader-load)

Source: skills/principle-minimize-reader-load/SKILL.md

  • Definition: reader load is the effort a reader must spend to understand code. The leaf measures it along 2 independent axes: the number of layers to trace between a question and its answer, and the amount of hidden or mutable state the reader must keep in mind. Both need guarding.
  • Collapse forwarding layers: wrappers with a single caller, adapters with no second implementation, and pass-through methods should be inlined.
  • Shrink state scope: prefer return values to mutation, locals to fields, fields to module state, and module state to globals. Derive values where you would otherwise keep copies in sync.
  • Invariants: state an invariant once, at the boundary, and avoid repeating it in every consumer.
  • The test: the leaf asks whether a newcomer to the code can answer “where does X come from?” and “what can change X?” within 30 seconds. When they cannot, reduce the layers or the state.
  • Steering: this principle is a good response when code the agent wrote itself turns out to be hard to follow.

Subtract Before You Add (principle-subtract-before-you-add)

Source: skills/principle-subtract-before-you-add/SKILL.md

  • Rule: when evolving a system, remove complexity first and build afterwards. Subtraction is the default.
  • Continual investment: the leaf treats simplification as an ongoing habit. Each change should leave the design slightly simpler and more capable, behind a surface the same size as before or smaller.
  • Practices:
    • Schedule removal before construction.
    • Cut before polishing; reach the minimum before investing in quality.
    • Design for observed usage instead of speculative edge cases.
    • Write no validators, parsers, or guards beyond what the spec requires.
    • Simplify prompts by removing redundant instructions and excessive templates.
    • Delete a reference that adds no new content instead of leaving it as a stub.
  • Steering: the guide’s example applies when the agent is about to add another adapter beside existing ones: use subtract before you add. delete the obsolete adapters first, then design what's left.

Build the Lever (principle-build-the-lever)

Source: skills/principle-build-the-lever/SKILL.md

  • Rule: for any non-trivial work (edits, migrations, analyses, checks), build the tool that performs it or proves it correct, such as a codemod, a script, a generator, or a rerunnable check, instead of doing the work by hand. The threshold is triviality; repetition is irrelevant. Only a couple of obvious edits justify skipping the tool.
  • Method: complete the first unit manually, then write the tool and confirm it works by running it again on the unit you just did. Running the tool more than once must be safe.
  • Fan-out: a deterministic tool is preferable to fanning work out to subagents. When fan-out is necessary, write the recipe, the verification contract, and the fences as one skill that the delegates read and cannot modify.
  • Evidence: applying this principle produces a file. If the diff contains no script, codemod, generator, or delegate skill, the principle was not applied. Commit the tool when the work will outlive the session.
  • Size: build the smallest script that does or proves the job. A framework is never the goal.
  • The guide’s additions: the tool is what a reviewer can rerun. When an agent keeps repeating a manual task, have it write the tool or skill it wishes it had. If a script can perform a step identically every time, use the script and reserve agents for judgment calls.

Encode Lessons in Structure (principle-encode-lessons-in-structure)

Source: skills/principle-encode-lessons-in-structure/SKILL.md

  • Rule: when you notice yourself writing the same instruction for the second time, or see a correction that keeps recurring, encode the rule as structure: a lint, a metadata flag, a runtime check, or a script. More text is the wrong remedy.
  • Exception: some lessons depend on judgment and resist encoding. For such a lesson, give the instruction a more prominent place and add an example of the failure it is meant to prevent.
  • Corollary: if a structural fix exists, use only the structural fix. The leaf calls the written instruction “the symptom”.
  • Category: poteto-mode’s index places this principle alone in its “Meta” category.
  • Related skill: the guide points to /correct, which applies this principle across an entire repository (see Building and Code Quality).
  • Steering: once you have given the agent the same correction twice, ask it to encode the lesson in structure.