Skip to content

olibyte/jev-trader / .agents/skills/principles

principles

Verified

Apply named engineering principles such as laziness, prove-it-works, and model-the-domain. Use when choosing a design, sequencing work, reviewing a diff, or the user names a principle.

Codex $principles. Claude Code, Cursor, and Antigravity /principles.

Principles

Read the matching file under references/ in full before you apply a principle. Cite only files you read this session.

Index

  • Attack the Premise (principle-attack-the-premise). Apply when two or more fixes that share one premise have failed the same gate. Take a census of which actors hold the imbalance before the next fix, then question the premise instead of writing another fix that assumes it.
  • Boundary Discipline (principle-boundary-discipline). Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions.
  • Build the Lever (principle-build-the-lever). Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun.
  • Encode Lessons in Structure (principle-encode-lessons-in-structure). Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text.
  • Exhaust the Design Space (principle-exhaust-the-design-space). Apply when facing a novel UI interaction or architectural decision with no precedent in the codebase. Build 2-3 competing prototypes and compare side by side before committing.
  • Experience First (principle-experience-first). Apply when product, UX, or feature-scope tradeoffs come up. Choose user delight over implementation convenience; ship fewer polished features over more rough ones.
  • Explain the Number (principle-explain-the-number). Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think.
  • Fix Root Causes (principle-fix-root-causes). Apply when debugging. Trace each symptom to its root cause and fix it there; reproduce first, ask why until you reach it, resist nil-check guards that silence crashes.
  • Foundational Thinking (principle-foundational-thinking). Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious.
  • Guard the Context Window (principle-guard-the-context-window). Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads.
  • Laziness Protocol (principle-laziness-protocol). Apply when refactoring, evaluating diff size, tempted to add abstractions, layers, or signal threading, or reaching for a new helper or dependency. Bias toward deletion, reuse, and the smallest change that solves the problem.
  • Make Operations Idempotent (principle-make-operations-idempotent). Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state regardless of partial prior runs.
  • Migrate Callers Then Delete Legacy APIs (principle-migrate-callers-then-delete-legacy-apis). Apply when introducing a new internal API while old callers still exist. Migrate callers and delete the old API in the same wave instead of preserving compatibility layers.
  • Minimize Reader Load (principle-minimize-reader-load). Apply when reviewing or shaping code that's hard to trace. Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope.
  • Model the Domain (principle-model-the-domain). Apply when writing stateful logic, or when code branches a lot or repeats a shape assumption across files.
  • Never Block on the Human (principle-never-block-on-the-human). Apply when tempted to ask 'should I do X?' on reversible work.
  • Outcome-Oriented Execution (principle-outcome-oriented-execution). Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code.
  • Prove It Works (principle-prove-it-works). Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'
  • Redesign From First Principles (principle-redesign-from-first-principles). Apply when integrating a new requirement into an existing design.
  • Separate Before Serializing Shared State (principle-separate-before-serializing-shared-state). Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant.
  • Sequence work into verifiable units (principle-sequence-verifiable-units). Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer.
  • Subtract Before You Add (principle-subtract-before-you-add). Apply when sequencing an addition, refactor, or rewrite. Remove dead code, redundant validators, and stub references first, then build on the simpler base.
  • Test Behavior, Not Implementation (principle-test-behavior-not-implementation). Apply when you write, change, or keep a test. Call the code as its users do and assert the exact result they see. Rewrite or delete a test that would pass if every imported function returned undefined.
  • Type System Discipline (principle-type-system-discipline). Apply when designing types, reviewing a function signature, or writing code in any statically-typed language. Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, refuse to lie to the compiler, exhaust variants, derive from authoritative schemas.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall