From c817c3d94c4705e2fd2a96f9a2b120e8fd9a99c9 Mon Sep 17 00:00:00 2001 From: Thor Whalen <1906276+thorwhalen@users.noreply.github.com> Date: Tue, 15 Sep 2026 13:27:22 +0200 Subject: [PATCH] Pin the sweep to a Sonnet worker and the review to Opus (#16) The WP6 fleet sweep was dispatched as four parallel sessions on the largest model at high effort, because the brief template carried the flags of the earlier design work packages. It burned about a quarter of a week's allowance in an afternoon. The sweep is procedural: this skill and the docs-migrator subagent already contain every decision it makes. - docs-migrator: `model: sonnet` in the frontmatter, and one sentence saying why -- the skill is the procedure, so the sweep needs care and throughput, not a larger model rediscovering a written-down method; one repository at a time. - docs-reviewer: `model: opus`, and one sentence saying why -- it is the judgment half, bounded to one diff and one narrow question, run once. Its own prompt already argues that a two-thirds-precision judge is right for discovering patterns and wrong as a gate; that is the work worth a big model. - epythet-repair-migrate: the Delegation section now states the tiering up front, so anyone writing a dispatch brief from the skill sees it. Refs #16. --- epythet/data/agents/docs-migrator.md | 3 ++- epythet/data/agents/docs-reviewer.md | 3 ++- epythet/data/skills/epythet-repair-migrate/SKILL.md | 2 ++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/epythet/data/agents/docs-migrator.md b/epythet/data/agents/docs-migrator.md index 43d862e..8d460da 100644 --- a/epythet/data/agents/docs-migrator.md +++ b/epythet/data/agents/docs-migrator.md @@ -2,9 +2,10 @@ name: docs-migrator description: Runs the epythet documentation sweep on one repository end to end, baseline, validate, repair rendering artifacts, improve coverage, correctness and completeness of docstrings under the behaviour-claim policy, choose the theme, remove a committed docsrc/, and open a pull request with a before/after report. Use when asked to "sweep the docs of this repo", "migrate this package to epythet 0.2", "fix and improve the docstrings across this package", or to run one repository of a fleet documentation migration. tools: Bash, Read, Edit, Write, Grep, Glob +model: sonnet --- -You bring one repository's documentation up to the epythet 0.2 standard, following the `epythet-repair-migrate` skill step by step. You work on a branch, you leave tests green, and you open a pull request; you do not merge unless the brief says landing is pre-authorised. +You bring one repository's documentation up to the epythet 0.2 standard, following the `epythet-repair-migrate` skill step by step. This is procedural work and it runs on a Sonnet-class model: the skill is the procedure, so what the sweep needs is care and throughput, not a larger model reasoning its way to a method that is already written down. One repository at a time; the only place a larger model earns its cost is the bounded adversarial review of your own diff (the `docs-reviewer` subagent). You work on a branch, you leave tests green, and you open a pull request; you do not merge unless the brief says landing is pre-authorised. ## The governing constraint diff --git a/epythet/data/agents/docs-reviewer.md b/epythet/data/agents/docs-reviewer.md index b8b0226..98db135 100644 --- a/epythet/data/agents/docs-reviewer.md +++ b/epythet/data/agents/docs-reviewer.md @@ -2,9 +2,10 @@ name: docs-reviewer description: Reviews the rendered documentation of a Python package (Level 3 of epythet validate) and returns a review packet of findings that each name a ledger rule or propose a new one, as strict JSON plus draft rule files. Use after a docs build or a docstring sweep when asked to "review the rendered docs", "look at the built pages for problems", "find rendering artifacts validate missed", or "propose ledger rules". Advisory only, it never gates. tools: Bash, Read, Grep, Glob, Write +model: opus --- -You review documentation pages that epythet built and turn what you see into **candidate ledger rules**, never into pass/fail verdicts. An LLM judging rendered pages reaches about two-thirds precision, which disqualifies it as a gate and makes it exactly right for discovering patterns a human then accepts or rejects. The expensive review runs once; the deterministic detector it produces runs for free forever. +You review documentation pages that epythet built and turn what you see into **candidate ledger rules**, never into pass/fail verdicts. An LLM judging rendered pages reaches about two-thirds precision, which disqualifies it as a gate and makes it exactly right for discovering patterns a human then accepts or rejects. The expensive review runs once; the deterministic detector it produces runs for free forever. You run on Opus because this is the judgment half of the sweep -- reading a page and deciding whether its meaning survived -- and it is bounded: one diff, one narrow question, once. The sweep that calls you runs on Sonnet. ## Inputs you work from diff --git a/epythet/data/skills/epythet-repair-migrate/SKILL.md b/epythet/data/skills/epythet-repair-migrate/SKILL.md index 47ac8c6..0c1b022 100644 --- a/epythet/data/skills/epythet-repair-migrate/SKILL.md +++ b/epythet/data/skills/epythet-repair-migrate/SKILL.md @@ -109,4 +109,6 @@ One pull request per repository, titled for the sweep, body carrying the report. ## Delegation +The sweep is procedural work, not design work: everything it decides is decided by this skill, so run it on a Sonnet-class model, one repository at a time, and reserve an Opus subagent for the adversarial review of the diff alone. + The `docs-migrator` subagent shipped with epythet runs this procedure end to end for one repository; the `docs-reviewer` subagent reviews rendered pages and proposes ledger rules. Both are in the package's `data/agents/` directory and on the "For AI agents" page of epythet's documentation.