Add simplicity-reviewer, a counterweight to over-engineering

[troldal]

Why

Every reviewer in the process pushes the same way: each finds a gap, and each gap becomes another check, overload, trait or reason text. No agent asks whether an addition earns its cost. Recent examples:

• phase 1 grew from 0.5–1 to 6.5–9.5 developer-days once its design and reviews were done;
• the combinators went from four static_asserts to 18 deleted declarations;
• F3 needed three review rounds of protection against malformed client solvers.

This adds the counterweight.

What

• .claude/agents/simplicity-reviewer.md, in the project's agent pattern (opus, high; read-only, with Write for scratch probes only). It is "an expert in API and library design specializing in finding the smallest design that meets a requirement".
  • For each item it weighs cost (code, overloads, reasons, compile time, diagnostic length, days) against how likely the mistake is for an ordinary caller.
  • It gives a verdict of keep, simplify, cut or defer, with the simpler alternative, what is lost and what is saved.
  • Moves it can propose: merging duplicate reasons; giving exotic misuse the compiler's own error; documenting instead of enforcing; deferring to the owning phase; reusing an existing mechanism; trimming test plans.
  • Hard limits: never weaken rule 5; never reopen a §2/§12 decision; keep std::is_invocable_v false for an ordinary caller's mistakes; keep portability, the compiler floor and determinism; respect the current phase. A cut to an approved design, or a narrowed rule, is marked needs a decision for the maintainer.
• CLAUDE.md:
  • a row in the agent table;
  • step 3: it always reviews design notes, core notes included;
  • step 7: it reviews a diff that adds public names, overloads, traits or reason texts to the library, or more than about 300 lines under include/.

Verification

• The frontmatter parses with PyYAML. The description is one unquoted line starting "Use this agent when".
• docs-auditor checked the agent and the CLAUDE.md edits against CLAUDE.md's rules, DESIGN and the other agents. Its four findings are applied: the step-3 wording, the approved-DESIGN-section case in the table row, a definition of "large diff", and the Write tool for scratch probes.
• Worktree sessions load agents from the main checkout, so the agent takes effect once this is merged and the main checkout has it.

Next

Run it on the approved phase-1 design (DESIGN §6, [phase 1, approved 2026-10-04; not built]) before B7 is built. Any cut it proposes goes to the maintainer.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

The agent’s final instruction incorrectly routes step-7 implementation findings through the step-4 architect workflow.

Review effort: Balanced
Findings: 1

Open (1)

• Make reviewer handoff conditional for implementation reviews · New

What changed in this PR

Adds a simplicity-focused reviewer to counter over-engineering in design and implementation reviews.

Changes:

• Defines the reviewer’s scope, constraints, workflow, and output.
• Integrates it into design-note and implementation review processes.

File	Description
CLAUDE.md	Registers the agent and its invocation points.
.claude/​agents/​simplicity-reviewer.md	Defines the new reviewer.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.