metis

Metis

Write code as plain data and focused functions, with call sites that read cleanly and a structure that makes the next change cheap. These are strong defaults, not laws.

The task's scope and the repo's conventions outrank every rule here. Restructuring and cleanup apply only to code the task already changes, and new types or files the change itself needs are in scope; put anything wider in your report as a proposal. Fixing every site of the defect you were asked to fix is in scope. Relax a default when a local convention, the framework, the language's idioms, an object-oriented integration boundary, or generated code imposes a different shape, and keep the intent: clear responsibilities, understandable state transitions, readable tests.

Apply these defaults quietly. Code, comments, commit messages, and written reports never cite these rules or justify routine choices. In chat you may say briefly which defaults shaped a decision. Reason at length only about choices that are hard to reverse.

Apply sections by phase:

• Designing or starting a task: Design, Working process
• Implementing: Design (Boundaries and invariants), Working process, Comments and slop
• Writing tests: Tests
• Reviewing a diff or PR: Code review mode
• Before claiming done or committing: Final verification

Design

API shape

1. Start from the call site, by wishful thinking. Write the top-level code first as if the perfect helpers already existed, named the way you would want to call them. If that code reads awkwardly, the abstractions are wrong. For a hard subsystem, treat the sketch as a hypothesis. Get the implementation right first, then fit the interface to it, because an interface fixed too early rules out the implementations that would have worked.
2. Prefer deep modules: a simple interface over substantial work. A helper earns its place by changing the interface, such as its units, errors, types, or a step name the caller needs. If its interface is nearly as complex as what it hides, deepen it or inline it, unless callers outside the codebase depend on it (Design 18). A refactor should remove complexity, not move it into pass-through helpers.
3. Add new behavior through a focused function, variant, adapter, or wrapper rather than edits spread across existing branches. Hide awkward external APIs behind an adapter, so the rest of the code speaks the interface you wish existed.
4. Keep interfaces narrow enough that callers don't depend on operations they never use. Expose finished data directly instead of hiding it behind accessors. Add an interface when a second implementation or a test fake needs one, or when the repo's convention adds them anyway.