{"id":68483,"plugin_id":"plugins_6adf87c4f2648191a3db16e324db4c36","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-28T13:17:38.000Z","digest":"66850b225492af6b48a40ac60ab7fa663ac2e186d99bf35fa81ac6d693ac0b55","against":null,"payload":{"description":"Apply the 24 battle-tested engineering principles for architecture design, refactoring, implementation, bug diagnosis, migration, and verification. Use when deciding technical tradeoffs, structuring systems, writing tests, or reviewing code changes.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":286},{"relative_path":"references/attack-the-premise.md","size_in_bytes":1552},{"relative_path":"references/boundary-discipline.md","size_in_bytes":1580},{"relative_path":"references/build-the-lever.md","size_in_bytes":1976},{"relative_path":"references/encode-lessons-in-structure.md","size_in_bytes":262},{"relative_path":"references/exhaust-the-design-space.md","size_in_bytes":122},{"relative_path":"references/experience-first.md","size_in_bytes":932},{"relative_path":"references/explain-the-number.md","size_in_bytes":1419},{"relative_path":"references/fix-root-causes.md","size_in_bytes":1114},{"relative_path":"references/foundational-thinking.md","size_in_bytes":1228},{"relative_path":"references/guard-the-context-window.md","size_in_bytes":250},{"relative_path":"references/laziness-protocol.md","size_in_bytes":286},{"relative_path":"references/make-operations-idempotent.md","size_in_bytes":1113},{"relative_path":"references/migrate-callers-then-delete-legacy-apis.md","size_in_bytes":862},{"relative_path":"references/minimize-reader-load.md","size_in_bytes":1690},{"relative_path":"references/model-the-domain.md","size_in_bytes":1663},{"relative_path":"references/never-block-on-the-human.md","size_in_bytes":751},{"relative_path":"references/outcome-oriented-execution.md","size_in_bytes":789},{"relative_path":"references/prove-it-works.md","size_in_bytes":1094},{"relative_path":"references/redesign-from-first-principles.md","size_in_bytes":590},{"relative_path":"references/separate-before-serializing-shared-state.md","size_in_bytes":1263},{"relative_path":"references/sequence-verifiable-units.md","size_in_bytes":1344},{"relative_path":"references/subtract-before-you-add.md","size_in_bytes":658},{"relative_path":"references/test-behavior-not-implementation.md","size_in_bytes":1080},{"relative_path":"references/type-system-discipline.md","size_in_bytes":3274}],"name":"poteto-principles","skill_md_contents":"---\nname: poteto-principles\ndescription: Apply the 24 battle-tested engineering principles for architecture design, refactoring, implementation, bug diagnosis, migration, and verification. Use when deciding technical tradeoffs, structuring systems, writing tests, or reviewing code changes.\nmetadata:\n  derived-from: https://github.com/cursor/plugins/tree/c86f349b102feb91f1966f8a6a60882a4e601b50/pstack/skills\n---\n\n# poteto-principles\n\nA battle-tested catalog of 24 foundational engineering principles for autonomous agents and engineers.\n\n## Why This Skill Is Needed & Target State\n\n**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.\n\n**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.\n\n## The 24 Principles\n\nRead all linked references in [`references/`](references/) relevant to your active task:\n\n- [`attack-the-premise`](references/attack-the-premise.md): When two or more fixes sharing one premise fail the same gate, suspect the premise rather than the fixes.\n- [`boundary-discipline`](references/boundary-discipline.md): Consolidate validation, type narrowing, and error handling at system boundaries; trust internal types unconditionally; keep business logic in pure functions.\n- [`build-the-lever`](references/build-the-lever.md): Avoid tedious repetitive manual edits; build the deterministic script, generator, or codemod that does the job rerunnably.\n- [`encode-lessons-in-structure`](references/encode-lessons-in-structure.md): When an instruction is repeated twice, convert it from natural language into a linter, schema, metadata, or verification check.\n- [`exhaust-the-design-space`](references/exhaust-the-design-space.md): For unprecedented or critical designs, construct 2-3 competing prototypes to contrast tradeoffs before deciding.\n- [`experience-first`](references/experience-first.md): When implementation convenience conflicts with user delight, choose user delight; polish fewer features to perfection.\n- [`explain-the-number`](references/explain-the-number.md): Before trusting a benchmark or metric, name what physical resource or code path bounds it (\"why not double?\").\n- [`fix-root-causes`](references/fix-root-causes.md): Never patch symptoms. Reproduce first, ask \"why\" recursively, and eliminate the underlying mechanism.\n- [`foundational-thinking`](references/foundational-thinking.md): Settle data structures and core domain types before writing algorithmic logic.\n- [`guard-the-context-window`](references/guard-the-context-window.md): Delegate verbose token dumps and research to subagents; retain only concise summaries in the primary context thread.\n- [`laziness-protocol`](references/laziness-protocol.md): Default to subtraction; make the smallest coherent change that solves the problem.\n- [`make-operations-idempotent`](references/make-operations-idempotent.md): Design commands and mutators so that repeated execution or mid-flight crash recovery converges to the same target state.\n- [`migrate-callers-then-delete-legacy-apis`](references/migrate-callers-then-delete-legacy-apis.md): When introducing a replacement API, migrate all call sites and eliminate the legacy interface in the same release wave.\n- [`minimize-reader-load`](references/minimize-reader-load.md): Reduce both the number of layers a reader must traverse and the working state they must hold in mind.\n- [`model-the-domain`](references/model-the-domain.md): Make invalid states unrepresentable in the data structure instead of scattering defensive branch checks.\n- [`never-block-on-the-human`](references/never-block-on-the-human.md): For reversible and reviewable actions, proceed with reasonable decisions and present verifiable results rather than stalling.\n- [`outcome-oriented-execution`](references/outcome-oriented-execution.md): In planned refactors and migrations, prioritize convergence on the verified final state over preserving fragile intermediate states.\n- [`prove-it-works`](references/prove-it-works.md): Verify work against the real runtime environment or live binary, never via self-reports, mocks, or passive assumptions.\n- [`redesign-from-first-principles`](references/redesign-from-first-principles.md): When integrating new requirements, design as if the requirement was present from the beginning rather than bolting on shims.\n- [`separate-before-serializing-shared-state`](references/separate-before-serializing-shared-state.md): Eliminate mutable shared state where possible; where unavoidable, enforce structural serialization via lockfiles or explicit phases.\n- [`sequence-verifiable-units`](references/sequence-verifiable-units.md): Break work into small, verifiable slices where each slice transitions from red to green before proceeding.\n- [`subtract-before-you-add`](references/subtract-before-you-add.md): Remove obsolete code, unused parameters, dead branches, and speculative scaffolding before introducing additions.\n- [`test-behavior-not-implementation`](references/test-behavior-not-implementation.md): Invoke the code as callers do and assert literal outcomes; delete tests that pass if the subject returns dummy stubs.\n- [`type-system-discipline`](references/type-system-discipline.md): Model variants as tagged unions; brand semantic primitives; validate external payloads at boundaries; never lie to the compiler with casts.\n\n## Invariant Rules\n\n1. **Cite the Principle with Evidence**: When applying a principle, cite its file name and state the concrete before/after change.\n2. **Structural Levers Over Narrative Rules**: Convert repeated warnings into mechanical linters or schema validations per `encode-lessons-in-structure`.\n3. **Subtract First**: Delete dead code, unused flags, and abandoned abstractions before adding new features per `subtract-before-you-add`.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}