best-of-n

Best-of-N

When to Invoke

Routed by /harness:pipeline only when /harness:intake set bestofn: true (critical OR [best-of-n] user override). Never user-facing; never invoked directly. Standard Build dispatches are the default — this is a Build dispatch mode, not a substitute for Review or Final Gate.

Inputs

• Slice spec at $state_dir/{task-id}/plan.md with per-AC failing-test stubs.
• Candidate roster from skills/best-of-n/config.json (Opus 4.7 + Sonnet 4.6 always; external slot via required_env).
• Pre-flight worktree-pool capacity (default cap 6 workstation / 12 CI; CLAUDE_BESTOFN_MAX_WORKTREES).

Procedure

See ~/.claude/orchestrator/parallel-dispatch-details.md § Best-of-N Build Team Dispatch.

Output

• Pipeline state: $state_dir/{task-id}/best-of-n.md (frontmatter verdict, sections: Candidates Run, Winner SHA, Per-Candidate Scores, Selection Rationale, Total Cost USD via cost_estimator, Cluster Sizes — N/A until FMV is wired).
• Scratchpad: $state_dir/{task-id}/scratchpad/best-of-n-selection.md (category: decision) — always carries the verbatim Selection Rationale; additionally carries a divergence record with diff-stat + Jaccard when the top two candidates clear the Step 5 tie-breaker boundary AND have changed-files Jaccard < 0.5 (mining path: observations.jsonl → /harness:learn Step 3d, never direct scratchpad → anti-pattern). Tie-breaker source + spec: see orchestrator details § Best-of-N Step 5.
• Winner branch merged into the pipeline working branch; loser worktrees + branches removed.

Verdict

Verdict	Meaning	Downstream
BoN_WINNER_SELECTED	≥2 candidates produced green builds; reviewer picked one.	Winner proceeds to /harness:code-review + /harness:security-review (standard Review).
BoN_FALLBACK_TO_SINGLE	<2 valid candidates after validation/runs (e.g. external required_env unset, all but one failed own tests). Fallback is silent and logged in ## Re-routes.	Single-candidate Build dispatch on the same slice.
BoN_INSUFFICIENT_RESOURCES	Pre-flight worktree-capacity check exceeded the cap.	Halt this dispatch; pipeline escalates to user (or falls back to single-engineer if policy permits).

Anti-Patterns

• Invoking on a non-critical task without the [best-of-n] user override — the 2-3x spend is not justified by baseline data.
• Running when the worktree pool is exhausted — must emit BoN_INSUFFICIENT_RESOURCES, never silently overcommit disk/inodes.
• Silent fallback to single-candidate without emitting BoN_FALLBACK_TO_SINGLE — every re-route must be auditable in pipeline state.

Tests

skills/best-of-n/tests/ holds scoring/selection coverage (test_best_of_n.sh). Structure-drift coverage lives at scripts/test_best_of_n_skill_structure.sh, which runs the canonical-template audit against this file.