/sonnet-pilot

name: sonnet-pilot
description: |
  Sonnet-first quality playbook: through context engineering, sub-agent delegation,
  and forced self-review loops, get Sonnet 4.6 to produce code/doc quality on par
  with Opus 4.7. Escalate to Opus only when quantitative gates trigger.
  Triggers: "sonnet", "Sonnet", "Sonnet mode", "sonnet-pilot".

  Do NOT use for: pure cost optimization, file-count cognitive heuristic,
  agent dispatch table, CLAUDE.md / rules audit, harness health check,
  default Haiku execution (use haiku-pilot for that).
  This SKILL is a Sonnet quality-enhancement router, not a generic decision tree.
allowed-tools: Read, Grep, Glob, Bash, TodoWrite

Sonnet Pilot — Quality-First Execution Playbook

Thesis

**Deep context engineering + precise delegation = quality floor protection + predictable escalation.**

> Augment Code eval (2026-04): Best-quality AGENTS.md provides performance gain equivalent to one model tier (Haiku→Sonnet or Sonnet→Opus effective). Bad documentation is worse than no documentation, by ~30%. > AgentOpt (arxiv 2604.06296): On HotpotQA, strongest planner alone (Opus full stack) = 31.71%; weak planner + strong solver (layered delegation) = 74.27%. **Individual model capability does NOT predict ensemble performance.**

**What this SKILL actually does** (empirically validated, A/B/C benchmark, n=5 wiki tasks, Opus 4.7 graded):

• Sonnet + SKILL = 283/300; Sonnet Plain = 283/300; Opus = 286/300
• **SKILL net gain on routine extraction = 0**: on structured wiki tasks, Sonnet already performs near-Opus without this playbook
• **SKILL value = floor protection on hard tasks**: complex tasks with ambiguous requirements, multi-step agentic, cross-module design — where Sonnet without structure tends to miss assumptions, skip self-review, or produce over-engineered output

→ Think of this SKILL as **insurance**: no observable premium on easy days; prevents 10–30% quality loss on hard days. → If your tasks are mostly "extract facts from a structured document" → you may not see measurable gain; activate this for complex implementation and agentic tasks. → Sonnet as planner + advisor()/reviewer (Opus) on-demand > Opus full-stack for most tasks.

> Cost ratio: Sonnet ($3/$15) vs Opus ($15/$75). Quality first does NOT mean always-Opus; **Opus only fires when quantitative gates trigger.**

---

Per-Session Pre-flight (run once per session)

1. Reference Pattern Technique

| ❌ Abstract description | ✅ Point to a file | |----------------------|-------------------| | "Write a validation module" | "Follow the pattern in `src/auth/validator.ts`" | | "Add a hook similar to useUser" | "Pattern: `hooks/useUser.ts:42-78`" | | "Reference the deploy flow we used last time" | "Follow `<your-playbook>.md` Step 3-6" |

**Sonnet-specific**: Sonnet given an abstract description tends to design from scratch; concrete reference = narrows design space to "variant of correct pattern", not "invent from zero".

2. Decision-Log Requirement (Opus has this built-in; Sonnet must enforce)

For every non-obvious technical decision, before completion output 2 lines:

Choice: <what you decided>
Rejected: <option considered but excluded> — Reason: <one sentence>

**Why it matters**: Opus naturally does this in reasoning; Sonnet tends to skip the intermediate decision record and emit results directly, making reasoning quality undiffable and review hard. Decision-log is a synthetic substitute for Opus's deeper thinking, externalized.

3. Reasoning Chain Before Code

Before implementation, output (don't skip): 1. **1-2 sentence task understanding** (your interpretation, not parroting) 2. **Key assumptions** (≥ 1, prefixed with "Assumption: ...") 3. **Implementation plan** (bullet list, ≤ 5 steps) 4. If multiple reasonable interpretations exist → **list options for user confirmation**, don't pick one yourself

> Source: `core.md` § "Think-Before-Coding". Sonnet has higher confidence than Haiku, paradoxically MORE prone to skipping assumption verification; this pre-flight enforces it.

4. Self-Review Loop (quality gate)

Before declaring "complete":

git diff --stat   # confirm change scope
git status        # confirm no unintended additions

**Explain each modified file in one sentence**. Then:

• Any change > 30 LoC → dispatch `quick-code-reviewer` sub-agent for post-implementation review
• Touches auth/payment/user-data → dispatch `security-reviewer`
• Architecture or cross-module design → call `advisor()` before declaring done

**Sonnet-specific**: Sonnet's high confidence is a double-edged sword — easy to skip self-review. This pledge is the externally bolted-on "doubt mechanism".

5. Intermediate Checkpoint (multi-step tasks)

For tasks with ≥ 3 independent steps, **pause and verify** after each:

• Output: "Completed Step N / M: <one-sentence result>"
• Confirm intermediate output matches expectation before proceeding
• If anything unexpected → stop and ask, don't power through

> Empirical basis: AgentOpt experiments show step roles in multi-step pipelines matter more than overall model capability; Sonnet's failure mode is "reasoning without verification checkpoints".

6. Mid-Write Outline Verification (architecture / counter-factual / synthesis tasks)

**Trigger**: tasks tagged Architecture / Counter-factual / Synthesis (per § Task-Type Fast-Path table).

**Procedure** (run once at ~200 words drafted, before continuing):

| Check | Action on fail | |-------|----------------| | Still inside the question's scope? | Drop tangential paragraphs | | Projected total ≤ 800w? (current_wc × est_remaining_sections) | Cut outline; merge sections | | All N mandatory citations / subquestions covered? (list them; checkmark) | Add missing items first; do not write more body until covered |

**Why this exists**: Pre-flight #4 (Self-Review Loop, `git diff --stat`) fires *after* the answer is written. By that point, runaway answers are already 700–800 words. Mid-write