Determinism By Design
Treat every source of nondeterminism — time, randomness, ID generation, iteration order, concurrency schedule, environment — as an injected dependency behind a seam, so tests are hermetic, failures replay from a seed, and simulations are byte-identical. Use when writing code that touches clocks, timeouts, random values, UUIDs, retries with jitter, or concurrent tasks; when a test is flaky or timi…
Naming Things
Choose clear names for variables, functions, classes, and modules - length proportional to scope, problem-domain vocabulary, honest booleans, units in names or types - and catch the anti-patterns (single letters, abbreviations, Hungarian type prefixes, negated booleans, Base/Abstract, Utils/Helper grab-bags, vague Manager/Handler words). Use when naming or renaming anything in code, reviewing ide…
Keep A Changelog
Maintain CHANGELOG.md in Keep a Changelog 1.1.0 format — sort changes into Added/Changed/Deprecated/Removed/Fixed/Security, keep the Unreleased section current, cut version sections, and handle breaking changes, reverts, and yanked releases. Use when asked to "update the changelog", "add to the changelog", "write release notes", "cut/prepare a release section", "bump the version", or when user-fa…
Negative Result Taxonomy
Turns a failed attempt into something diagnosed rather than abandoned — each one is labelled FAMILY_DEAD (allowed only where the approach's best case was measured and missed), DESIGN_DEAD (what you write by default, owing a rebuild ticket with an established cause and the cheapest settling test), or INSTRUMENT_VOID (the apparatus failed to decide, which is never an idea failing), while a result t…
Rfc Writer
Author and maintain numbered RFC design documents in a project's rfcs/ directory, tracked by an INDEX.md. Use whenever the user asks to write an RFC, design proposal, design doc, technical spec, or architecture proposal; wants to record a design decision, its alternatives, or why an approach was rejected before building; asks to update an RFC's status after shipping; or asks to set up / clean up…
Escape Hatch Policy
Decide when an abstraction earns a raw/bypass/override escape hatch and how to design one that stays safe — the two-question test (un-modelable long tail vs cross-cutting invariants bypassed), declared-not-silent opt-outs, and hatch usage as a feature-gap signal. Use when someone asks for raw access, a passthrough field, a bypass flag, or a config override; when designing an API tempted to add a…
Gitmoji Conventional
Format git commit messages and Pull Request titles as Conventional Commits 1.0.0 with a deterministic gitmoji prefix, including breaking changes (💥 + ! + BREAKING CHANGE footer) and reverts. Use whenever generating or suggesting a commit message or PR title — "commit this", "write a commit", "commit message", "create PR", "open PR", "draft PR", "PR title", "squash and merge", "release commit" —…
Self Documenting Code
Decide when to refactor a comment away and when a comment is required - express the "what" through names, extracted predicates, constants, and types, and reserve comments for what code cannot say - intent, invariants, units, ranges, and interface contracts. Use when writing or reviewing comments, deciding whether a comment is needed, deleting or fixing stale or redundant comments, refactoring har…
Dependency Diligence
Evaluate a dependency before adopting it — check the project's architectural invariants first (one violated constraint rules out a whole family), weigh capability against total cost, and choose among adopt-behind-a-seam, take-the-idea-not-the-dep, or reject-with-a-recorded-verdict. Use when about to add a package or library, when asked "should we use X", when reviewing a PR that adds a dependency…
Pr Review Loop
Work a pull request's review loop to convergence — wait for AI reviewers (CodeRabbit, Greptile, and similar) and humans, dedup comments into findings, give each an evidence-backed verdict, fix what's valid, refute what's wrong, react and resolve coherently, meet the coverage floor, push, repeat — without ever merging. Use when a PR has review comments to address, when the user says "handle the re…
Composition Over Inheritance
Prefer composition and interfaces over class inheritance - apply the GoF principle and Effective Java's composition-plus-forwarding to avoid fragile base classes, run the Liskov behavioral is-a test, and recognize the narrow cases (framework hooks, sealed hierarchies, exceptions) where inheritance is right. Use when designing or refactoring class hierarchies, reviewing OOP code, deciding between…
Drift To Gate
Converts a rule that keeps being broken into a program that refuses, and then runs that control's whole lifecycle — proving it can say no, logging its refusals, widening its vocabulary into buckets rather than into the accept set, failing loud instead of silently, and metering itself so it can be retired. Use when the same rule is violated a second time, when a standing agreement lives only in pr…
Decide Before You Look
Pre-registers what a run will decide before the data exists — a six-line call block with a predicted number, an 80% interval required to be tighter than the range the decision turns on, a probability of surviving, the likeliest reason to be wrong, and the artifact already on hand that could answer it without running anything. Covers frozen thresholds and append-only amendments, refusing to lower…
Never Nesting
Flatten deeply nested code using guard clauses, early return/continue, function extraction, and error-handling redesign - and recognize when nesting should stay (symmetric branches, RAII/defer cleanup idioms). Use when writing or refactoring code with deep indentation, pyramid-of-doom or arrow-shaped if/else, nested loops or try/catch blocks, a buried happy path, or when the user mentions nesting…
Flag Dont Flip
Executes work against an existing RFC or design doc without silently changing its decisions. Produces a reviewable file-by-file plan before writing code, halts on conflicts with LOCKED decisions instead of resolving them, and records every departure in an append-only execution log — `rfcs/EXECUTION-LOG.md` — classified by whether it was knowable at design time, with a drift count per unit of work…
Reproduce Then Fix
Fix bugs by reproduction and root cause, never by plausible patch — no fix ships without a red reproduction seen failing first, an explained mechanism, and the repro kept as a regression test. Use when fixing any bug, flaky test, or incident; when asked to "just patch it" or "make the error go away"; when a fix is proposed without a failing test; when debugging something that "works on my machine…
Distill The Rule
Convert surprising findings into durable one-line rules — after a debugging session, audit finding, review surprise, or incident, strip the specifics down to the transferable mechanism and file it where future work will actually recall it. Use when a session ends with a hard-won discovery, when a defect's shape will clearly recur, when a sabotage or test passes unexpectedly, after a postmortem, w…
Fewer Tests More Proof
Consolidate and optimize a test suite so it proves more with fewer, stronger tests — shared conformance batteries over per-implementation copies, differential and property-based testing over hand-enumerated examples, deterministic control instead of flake-retry volume, sabotage-proven deletion of ritual and subsumed tests, all under an honesty floor that promise coverage never drops. Use when the…
Python Google Docstrings
Write Google-style Python docstrings — Args/Returns/Raises/Attributes sections that render under Sphinx Napoleon and read well in IDE tooltips. Use whenever writing, editing, or reviewing Python docstrings or API documentation, documenting functions, classes, modules, or constants, or when the user mentions docstrings, Google style, Napoleon, or asks to "document this code".
Less Code Same Behavior
Deep divergence and DRY audit that shrinks a codebase without changing behavior — find copy-paste, same-concern-drift, scattered responsibilities, type-lying configs, wrong abstractions, and bloated public surfaces, then consolidate (or unwind) while respecting the project's declared layers and import contracts. Use when the user asks to deduplicate, DRY up, consolidate, converge divergent code,…
Ratchet What You Build
Close the gap between "built the mechanism" and "the mechanism is mandatory" — every guard, check, battery, or safe default needs a closing move (default flipped on, CI gate, fail-closed wiring) or it silently decays. Use when finishing any protective mechanism, when a shipped check turns out to be opt-in or absent from CI, when a safe mechanism exists but the unsafe default still ships, when rev…
Self Audit
Adversarially audit your own just-finished work — a branch after RFC/feature execution, a fix series, a document set — hunting for defects you introduced, before merge or handoff. Use whenever the user says "do self-audit", "audit your work", "self-audit this branch", "check your own changes", "double-check what you built", "review your own diff", or asks to find the bugs in work you produced bef…
Altitude Docs
Write, polish, review, or align documentation pages to a production-grade standard using the altitude model (a deliberate high-level to low-level descent), Diátaxis-based page contracts, a shared consistency layer, and a ship rubric. Use when writing or restructuring any docs page — tutorial, quickstart, how-to guide, reference, explanation, concept page, landing page — when reviewing docs for co…
Authority Dissociation
Separates who does the work from who certifies it, so no actor supplies the material its own output is judged from — covering the fit/kill/promote/fund/retire authority split, self-designed metrics, firewalls against condemning a whole approach on one measurement, advisory findings that must be answered rather than merely tolerated, fail-closed defaults on permission questions, and attestation th…
Measure Before Optimizing
Optimize only what measurement proves matters - carry both halves of Knuth's rule (skip the 97%, do not pass up the critical 3%), profile first because Amdahl's law caps every speedup, benchmark without warmup/noise/mean-vs-percentile traps, take data-structure and algorithm wins before micro-tweaks, and make architectural performance calls (query shape, data layout) at design time because they c…
Failure Path Review
Systematically review the unhappy paths of asynchronous and background systems — consumers, workers, queues, retry loops, schedulers, shutdown — where poison messages, misclassified retries, crash-redelivery, and abandoned in-flight work hide because failure code only runs when things go wrong. Use when writing or reviewing message consumers, background loops, job runners, retry/backoff logic, or…
Error Taxonomy
Design and enforce an error contract — a small closed set of error kinds, each with a decided transport mapping, message exposure, and retryability — and classify every raise site against it. Use when designing error handling for an API or module, deciding what exception to raise or what status an error maps to, reviewing raise sites or catch blocks, classifying errors as retryable, cleaning up i…
Python Rest Docstrings
Write reST Python docstrings — Sphinx info field lists (:param/:returns/:raises) and cross-reference roles (:class:/:meth:/:func:) that render natively in Sphinx and IDE tooltips. Use whenever writing, editing, or reviewing Python docstrings or API documentation, documenting functions, classes, modules, or constants, or when the user mentions docstrings, reST, reStructuredText, Sphinx roles, or a…
Reading Isnt Proof
Never close a test gap in a multi-implementation contract on the strength of a code read - when one contract has two or more implementations and you are about to say "nothing tests X", write the shared conformance battery and run it, even when you believe there is no defect. Use when auditing ports/interfaces/adapters with several backends, verifying a mock or fake against the real implementation…