P11-gated

Metis

Write code that favors plain data, pure logic, clear call sites, and early architectural thinking. These are strong defaults, not rigid laws: follow the surrounding codebase, framework constraints, and language norms when they clearly matter more.

Before anything else, name the phase you are in, then read ONLY the sections listed for that phase plus the Design principles. Actively skip the other sections — holding out-of-phase rules in mind dilutes the in-phase ones.

• Designing or starting a task: Design principles, LLM agent process
• Implementing or fixing code: Working rules, Implementation rules, plus the SOLID checklist for non-trivial modules
• Writing tests: Testing checklist
• Reviewing a diff or PR: Code review mode ONLY — skip Implementation rules and Working rules entirely; your whole attention belongs to the lenses
• Before claiming done, committing, or pushing: Final verification checklist

Design principles

1. Start from the call site, by wishful thinking: pretend the perfect helpers already exist, name them the way you would want to call them, and get the top-level usage reading cleanly. If the calling code reads awkwardly, the abstractions are wrong — and you find out before building anything.
2. Prefer plain data plus focused functions, modules, or systems over behavior-heavy objects. Draw boundaries around what systems do, not what entities are.
3. Choose the simplest state model that matches reality: discriminated unions for mutually exclusive states, composable data for orthogonal features, and a plain flat record when neither pressure exists — do not over-architect the simple case.
4. Isolate mutation and I/O near the edges. Orchestration decides what happens; inner helpers do narrow, understandable work.
5. Push ifs up, fors down. Keep high-level control flow in parents and leaf functions low-branch and easy to test.
6. Assert at boundaries, both where data enters and where it leaves: parsing, persistence, external APIs, state transitions, and function contracts. Check what must be true and, when useful, what must not be.
7. Prefer explicit, behavior-focused tests without indirection that hides intent.
8. Sanity-check the likely bottleneck first — network, disk, memory, then CPU. Prefer architecture changes over late micro-optimizations.
9. Design for the hardest real requirement first, then simplify downward. Do not architect for the easy case and try to scale it up later.
10. When elements of a batch can invalidate each other — duplicates, conflicts, cross-record constraints — classify the whole batch before applying any element, even when applying incrementally looks cleaner.