SuperAPI AI Directory

poteto-principles

Coding & development

View repository

Updated 10-24 16:19

About this skill

poteto-principles

A battle-tested catalog of 24 foundational engineering principles for autonomous agents and engineers.

Why This Skill Is Needed & Target State

Why this skill is needed: Engineers and AI agents only question decisions using perspectives active in their immediate attention. Unconsidered failure modes never surface as questions, leading to silent repetitions of known mistakes: scattered validation, symptom patching, loose test assertions, premature frameworks, and leaky abstractions.

Target state: Every architectural decision, refactoring step, implementation slice, and code review is systematically evaluated through these proven principles, producing robust, minimal, type-safe, and self-verifying systems.

The 24 Principles

Read all linked references in references/ relevant to your active task:

  • attack-the-premise: When two or more fixes sharing one premise fail the same gate, suspect the premise rather than the fixes.
  • boundary-discipline: Consolidate validation, type narrowing, and error handling at system boundaries; trust internal types unconditionally; keep business logic in pure functions.
  • build-the-lever: Avoid tedious repetitive manual edits; build the deterministic script, generator, or codemod that does the job rerunnably.
  • encode-lessons-in-structure: When an instruction is repeated twice, convert it from natural language into a linter, schema, metadata, or verification check.
  • exhaust-the-design-space: For unprecedented or critical designs, construct 2-3 competing prototypes to contrast tradeoffs before deciding.
  • experience-first: When implementation convenience conflicts with user delight, choose user delight; polish fewer features to perfection.
  • explain-the-number: Before trusting a benchmark or metric, name what physical resource or code path bounds it ("why not double?").
  • fix-root-causes: Never patch symptoms. Reproduce first, ask "why" recursively, and eliminate the underlying mechanism.
  • foundational-thinking: Settle data structures and core domain types before writing algorithmic logic.
  • guard-the-context-window: Delegate verbose token dumps and research to subagents; retain only concise summaries in the primary context thread.
  • laziness-protocol: Default to subtraction; make the smallest coherent change that solves the problem.
  • make-operations-idempotent: Design commands and mutators so that repeated execution or mid-flight crash recovery converges to the same target state.
  • migrate-callers-then-delete-legacy-apis: When introducing a replacement API, migrate all call sites and eliminate the legacy interface in the same release wave.
  • minimize-reader-load: Reduce both the number of layers a reader must traverse and the working state they must hold in mind.
  • model-the-domain: Make invalid states unrepresentable in the data structure instead of scattering defensive branch checks.
  • never-block-on-the-human: For reversible and reviewable actions, proceed with reasonable decisions and present verifiable results rather than stalling.
  • outcome-oriented-execution: In planned refactors and migrations, prioritize convergence on the verified final state over preserving fragile intermediate states.
  • prove-it-works: Verify work against the real runtime environment or live binary, never via self-reports, mocks, or passive assumptions.
  • redesign-from-first-principles: When integrating new requirements, design as if the requirement was present from the beginning rather than bolting on shims.
  • separate-before-serializing-shared-state: Eliminate mutable shared state where possible; where unavoidable, enforce structural serialization via lockfiles or explicit phases.
  • sequence-verifiable-units: Break work into small, verifiable slices where each slice transitions from red to green before proceeding.
  • subtract-before-you-add: Remove obsolete code, unused parameters, dead branches, and speculative scaffolding before introducing additions.
  • test-behavior-not-implementation: Invoke the code as callers do and assert literal outcomes; delete tests that pass if the subject returns dummy stubs.
  • type-system-discipline: Model variants as tagged unions; brand semantic primitives; validate external payloads at boundaries; never lie to the compiler with casts.

Invariant Rules

  1. Cite the Principle with Evidence: When applying a principle, cite its file name and state the concrete before/after change.
  2. Structural Levers Over Narrative Rules: Convert repeated warnings into mechanical linters or schema validations per encode-lessons-in-structure.
  3. Subtract First: Delete dead code, unused flags, and abandoned abstractions before adding new features per subtract-before-you-add.