delegate-local

name

delegate-local

description

Use this skill to offload non-reasoning text work to locally-installed models (Ollama or MLX) via `delegate.sh`, keeping content on-device and freeing the main-agent context window. Saves API tokens too, though context protection and privacy are the headline values, not cost. MUST use whenever the user asks to summarise a log/diff/file/PR/issue, draft a commit message/changelog/release note, triage or classify many items, extract structured fields from free text, skim many files for a one-liner, or rewrite or reformat prose. MUST also use when the user explicitly asks to delegate, names a local backend or model (Ollama, MLX, "a local model"), wants content kept on-device or offline for privacy, or wants to save API tokens. Bare "run it locally" usually means running the app, server, or tests on the user's own machine, not delegating to a local model, so treat "locally" as a delegation signal only when paired with an explicit delegate verb, a named local model, or a keep-it-private reason. MUST also use after the user sets durable auto-delegate intent ("delegate where it fits", "auto-delegate", "route to local where it makes sense"), defaulting to delegating any subsequent matching task without re-confirming. Do NOT use for code correctness review, architectural decisions, debugging or tracing errors, implementing features, or any task whose output triggers a destructive or shared-state action without review. Do NOT use for open-ended "find anything interesting / suggest improvements" prompts that ask the model to surface things not in the input — those invite fabrication.

Delegate Local

Offload non-agentic text tasks to locally-installed models via the local inference backend. The headline value is privacy (content stays on-device) and context protection (the main-agent window is not consumed by paragraph-fills); token cost savings are real but typically pennies per session and a side effect, not the reason to reach. Local models are strong summarisers and weak reasoners — scope accordingly.

Core insight (from local-brain): you do not need a framework. You need context | ollama run model.

Operating mode

Default to auto-delegate. When this skill is loaded into the conversation and the user's task matches the Fits list below, delegate immediately without asking permission. After every successful delegate.sh call, read the delegate-meta: line emitted to the tool's stderr — it carries model, tier, backend, tokens_local, and duration_ms as space-separated key=value pairs (plus recipe="NAME" when a --recipe flag was used). String-typed fields are double-quoted (model="qwen3.6:35b-a3b-q8_0"); integer fields are bare. On recipe calls the line may also carry checks_failed=N (a deterministic output check the model's text still violates after the wrapper has already re-generated once to fix it — eyeball that aspect before using it) and checks_autofixed=N (a trailing padding clause the wrapper auto-stripped for you — quickly confirm nothing meaningful was lost). In your reply, surface the model and the local-token count so the user can both spot a bad answer and see what stayed on-device: e.g. "Delegated to qwen3.6:35b-a3b-q8_0 (prose tier) — ~578 tokens kept local in 1.4 s." Frame it as "kept local," not "saved from Claude" — tokens_local is the local model's tokenizer view of total chars in + out divided by 4 (the same value scripts/metrics-summary.sh rolls up under estimated_tokens_avoided), not Anthropic's billable count. Do not ask "should I delegate this?" — the skill being loaded means yes by default. Re-confirm only if the task is borderline or the input contains content the user explicitly flagged as sensitive.

If the user says any of: "delegate where it fits", "use ollama where appropriate", "auto-delegate", "route to local where it makes sense", or similar — treat that as durable consent for the rest of the conversation: from that point on, every matching task goes through ollama run without further prompting.

When to delegate

Fits:

• Summarise a long log, diff, file, or PR description.
• Draft a commit message, changelog entry, or release note for a single-file mechanical change.
• Classify or triage N items (relevant/noise, bug/feature).
• Closed-form classification with an explicit, finite option set (e.g. "high|medium|low|info" severity, "REAL|FP" filter against a stated allowlist). The 2026-05-03 retrospective measured 5/5 reps perfect on FP-filter when the allowlist rule was explicit and a one-shot example was included.
• Compose structured prose from a fixed list of items (PR comment from a findings list, release-note bullets from a changelog block). The 2026-05-03 retrospective measured 3/3 PASS on PR-comment composition once the prompt forbade placeholder substitution explicitly.
• First-pass "what does this file do" over many files.
• Extract structured fields (JSON) from free-form text.
• Reformat or rewrite prose.
• Minimal single-file code patches where you supply the failing test alongside the source and verify by re-running the test after applying the patch. Scope is narrow and the verification step is load-bearing — multi-file edits, cross-module reasoning, and tests the director cannot re-run are out of scope. See the v8 probe evidence and the director-side pattern in the Reasoning-tier and Discipline sections.

Do NOT delegate:

• Multi-step reasoning, planning, or tool-calling.
• Tasks needing repo-wide context that does not fit one prompt.
• Code correctness, security, architectural judgements.
• Anything whose output directly triggers a destructive or shared-state action without review.
• The user asked for your analysis specifically.

The natural shape is structure is yours, prose is delegated: headings, code blocks, file links, table layouts, and CLI examples are decisions to own; flowing paragraphs of explanatory text are what the model fills. Tasks that look textual but encode structural decisions (link-index rewrites, table moves, cross-reference collapses, "delete this section and replace with a pointer to the canonical home") are not delegation candidates even though their output is text — the work is deciding which home is canonical, not writing prose.

Density threshold — per-edit AND session-level: if you would otherwise type more than ~4 paragraphs of fresh prose in a single delegation site, the skill earns its keep. But also evaluate at session level: if the session will produce more than ~4 paragraphs of total delegatable prose across all edits combined, delegation is the default even if each individual edit is small. A docs-cleanup session touching 9 files with 1-2 paragraphs each is well above threshold in aggregate, even though no single edit crosses it alone. When in doubt, delegate — the setup overhead of delegate.sh is near-zero and a rejected output costs less than writing it yourself.

If no provider is reachable, or none serves a model for the tier, delegate.sh says which of the two it is on stderr — do the work yourself and mention why.

Supervised code drafts — a divergent, executable second opinion

The discriminator is sharper than "weak agent, so don't." Local models are weak unsupervised agents but usable as a supervised draft generator under a verify loop. This is scoped to delegation as a sub-step of your own implementation work — the skill still does not own feature implementation, you do — and within that work you may delegate one bounded code draft. The reason it earns its keep is something a self-generated draft cannot give you: a differently-trained model proposes an approach, or makes a mistake, you would not have generated yourself, and running the draft answers "does it compile, pass the test, behave as I assumed" empirically rather than by static reasoning.

Fire a code draft only when BOTH hold:

• Value trigger (at least one): the approach is genuinely forked and you are unsure which way to go; OR executing the draft would teach more than reasoning about it (a compile result, a test result, real API behaviour).
• Bounded guard (always): a single file or function, small output, with a concrete verification — a test to run or an explicit acceptance check — named up front.

The draft is always disposable. Verify before keeping anything: apply it and run the named verification; a draft that applies but fails the verification is treated as a REFUSE, never kept on the strength of its prose. Use --recipe code-draft — it routes to the code tier and emits a focused full snippet, not a diff. Record the honest verdict afterwards via delegate-feedback.sh --source agent: hit if you kept it, miss if it was useless, or scaffold "<what it taught>" if you discarded the code but the divergence or the executable feedback genuinely improved your result. This is not "delegate all coding" — generic, low-divergence, easily-self-drafted code does not qualify, because for those the local round-trip only adds latency. The amendment is an experiment under an evidence gate; see ADR 0025.

Pattern

Three steps, in order, every time: gather → delegate → verify.

1. Gather the context you can fit in a short prompt (≤ 8k tokens; local models degrade above that).
2. Delegate with a constrained prompt that asks for an exact output shape.
3. Verify every specific claim the model returns against the actual files before acting on it. Treat the model's output as a hypothesis, not a finding.

Use scripts/delegate.sh <tier> "<prompt>" — it resolves the tier to a model on the first reachable provider, calls that provider's POST {base}/chat/completions with thinking suppressed (enable_thinking:false by default; override with DELEGATE_THINK=true if reasoning chains genuinely help) and temperature:0, and appends one JSON line per invocation to ~/.local/share/delegate-local/metrics.jsonl for scripts/metrics-summary.sh to roll up later. The HTTP API returns clean text, so no ANSI stripping is needed downstream.

The ≤ 8k tokens is a theoretical upper bound; the practical ceiling on a given host is often much lower. The 2026-05-05 IP-146 share-readiness session observed qwen3.6:35b via delegate.sh hanging for 3+ minutes on a single bundled ~1.3k-char prompt and being killed by the harness with exit 144. Splitting the same content into atomic single-paragraph prompts (~350 chars each) returned in 10–20 s per call. If delegate.sh appears to hang for more than ~30 s with no output, the prompt-plus-stdin is probably too large for your host — kill the call and break it into smaller atomic sub-tasks rather than waiting. First call against a freshly-loaded model is also slower than subsequent calls against the same model, because the daemon warms up; this is fixed-cost per model, not per call.

Recipe-shaped prompts have a sharper threshold than the byte-count framing suggests — issue #110's 2026-05-13 follow-up measured the 35B-class prose-tier model stalling on ~3-4 KB recipe inputs on both Ollama and MLX while a 0.6B-class model handled the same shape in 1 second; see prompts/pr-description.md calibration history for the full evidence.

Pitfall — shell-variable expansion leaks secrets or drops tokens. Any prompt argument referencing a literal $VARNAME token (environment variables, CI variables, shell parameters) must be single-quoted, wrapped in a <<'EOF' heredoc, or escape the dollar as \$VARNAME. Otherwise the surrounding shell substitutes the variable before delegate.sh ever sees it: unset variables expand to empty so the token vanishes from the prompt (the model produces output with a matching hole, indistinguishable from a forgotten token), while set variables expand to their literal value so the secret leaks into the prompt sent to the model and into the metrics JSONL row that captures prompt_chars for audit. Observed in production on a documentation draft referencing $PR_AGENT_GITLAB_TOKEN — the unescaped reference dropped to nothing in that case (the variable was unset locally), but on a CI host where the same name is the live token, the model would have received the secret directly. The failure is silent: no error, no warning.

# Wrong: $PR_AGENT_GITLAB_TOKEN expands — leaks the secret if set, vanishes if unset
bash scripts/delegate.sh prose "Document the job that copies $PR_AGENT_GITLAB_TOKEN."
# Right: single quotes disable expansion
bash scripts/delegate.sh prose 'Document the job that copies $PR_AGENT_GITLAB_TOKEN.'
# Right: backslash-escape the dollar inside double quotes
bash scripts/delegate.sh prose "Document the job that copies \$PR_AGENT_GITLAB_TOKEN."
# Right: quoted heredoc keeps the literal token in stdin without any expansion
cat <<'EOF' | bash scripts/delegate.sh prose "Summarise the doc below."
Document the job that copies $PR_AGENT_GITLAB_TOKEN from the group CI variable.
EOF

Recipes — calibrated prompt templates for recurring task shapes

For task shapes that come up often — drafting a commit message, drafting a PR description, summarising an issue's CI logs into a timeline comment — there is a calibrated recipe in prompts/<task>.md rather than just a description of "use the prose tier". Recipes ship the proven prompt skeleton, the canonical context-gathering commands, the verbatim-example anchors, and the explicit anti-hallucination guards drawn from prior session HITs. The reason they exist: small / local models default to whatever output shape is most common in their training (bullets when asked for "concise commit message"), and abstract style descriptors do not reliably override that prior — verbatim-example anchoring plus explicit guards do. Each guard in a recipe corresponds to a real past MISS, so the recipe accumulates calibration over time without rediscovering it every conversation.

Recipe-covered tasks are hard triggers, not judgement calls. When you are about to write a commit message, use --recipe commit-message. When you are about to write a PR description, use --recipe pr-description. When you are about to summarise an issue, use --recipe summarise-issue. When you are about to draft a maintainer reply to a contributor or reporter (a PR-review comment, an issue status comment, a bug-report one-liner), use --recipe maintainer-reply for the short closed shape — one sentence of cause or praise, then one ask — and --recipe maintainer-review-reply when the reply has to carry the evidence behind a judgement (file paths, hashes, issue refs, measured counts), because that recipe preserves every anchor instead of capping the length. When you are about to draft the body of a new GitHub issue from facts, use --recipe github-issue-body. When you are about to classify or triage a list of items into a fixed set of buckets, use --recipe bulk-classify. When you are about to write the intro narrative for a release announcement, use --recipe release-announcement. Do not skip the recipe because "this one is simple enough to write directly" — the recipes exist precisely because the setup cost is near-zero and the calibration guards prevent the small regressions (wrong conventional-commit type, padding tails, hallucinated file references) that hand-written prompts rediscover every time. The only valid reasons to skip a recipe are when the content requires multi-file reasoning context that exceeds the 8k token prompt limit, or when the recipe is flagged as flaky or refused on the resolved model (a recipe whose flaky_on_models: frontmatter matches the resolved model exits 4 — release-note and long-thread-distillation carry such blocks; pr-description's was retired 2026-06-28 once its stall was traced to cold-load rather than a generation failure, so on a cold 35B MLX host it just needs DELEGATE_PREFLIGHT_TIMEOUT=90 on the first call — see ADR 0027).

Gather the listed context and invoke bash scripts/delegate.sh --recipe <name> --var key=value ... ["<prompt>"] — the trailing prompt is optional when --recipe supplies the instruction, which is what makes the stdin-only form below work. You do not pass a tier on a recipe call: every recipe declares its own in frontmatter, and delegate-meta: reports the one it resolved. Pass --tier <name> only to deliberately route a recipe somewhere else (#411). The --recipe flag prepends the recipe's prompt template, substitutes each {{key}} placeholder from the matching --var, and refuses to send a partly-substituted template to the model so missed inputs surface as a clear error rather than a degraded answer. When you are about to write a commit message and have the staged diff in hand, git diff --cached | bash scripts/delegate.sh --recipe auto --var why="..." "..." lets the wrapper infer the commit-message recipe from the piped diff and backfill recent_commits/diff_stat from git, so the only thing you supply is the intent — one call instead of assembling every --var by hand. Always record the verdict after the call via bash scripts/delegate-feedback.sh --source agent hit|miss|scaffold [reason]. On an agent-recorded miss or scaffold the reason is required and the call exits 2 without it — you always know why you rewrote your own draft, and a rejection with no reason counts in every denominator while telling the loop nothing. Also add --final <path> (or --final - with the text on stdin) naming what you actually shipped instead. The draft is already stored for you; the shipped text is the half only you have. Together they turn "dropped every load-bearing fact" into a list of the specific anchors that went missing, which is what the recipe fix is calibrated from — see docs/self-improvement-loop.md — --source agent tags it as the agent's own usage judgment (did you use the output as-is, or rewrite/discard it), which is the honest meaning of a verdict the agent records about its own delegation, and keeps it out of the human taste-judgment tier the headline hit-rate is computed from (ADR 0015); a human recording their own taste judgment omits --source. Without a verdict the delegation stays as an "untracked" metrics row and the recipe library cannot self-correct from production data. delegate.sh prints a one-line stderr reminder after every successful call to make this step impossible to forget (silenceable via for callers who genuinely don't want it). By default attaches the verdict to the most recent delegate row in the metrics JSONL and refuses if that row is older than 5 minutes — a safeguard for the cases where metrics were off () or the delegation was killed before its row was written, since the implicit "most recent row" would otherwise be someone else's delegation. Pass to pin the verdict to a specific delegate row when you need to bypass this. Recipes start small — and today — and grow append-style as new HIT patterns get distilled. If a task pattern recurs and no recipe covers it, the discipline is to file a issue so the recipe library tracks coverage gaps rather than letting them evaporate. See for the recipe shape and contribution flow.

Pass --var values literally. Every recipe's Invocation example shows plain literal values rather than --var hash="$(git rev-parse --short HEAD)", because by the time you reach the delegation you already hold those values — you ran the git or gh command as its own earlier step and read its output, so pushing it back through the shell buys nothing. It also costs something: sandboxed shells refuse command substitution outright, including a Claude Code session working inside a git worktree, and a refusal on the very first --recipe call reads as "delegate-local is broken" when nothing is. Command substitution still works wherever the shell allows it, and a recipe that takes its context on stdin takes plain input redirection (bash scripts/delegate.sh --recipe github-issue-body --var sections="## Problem" < facts.txt); treat both as conveniences for a human at a terminal rather than the documented form.

Parallel-capture callers that fan N delegations into N background shells and want clean per-call output files (bash delegate.sh ... > out_$i.txt 2>&1 &) historically had to choose between contaminated stdout (the nudge line mixed into out_$i.txt via 2>&1) and lost coverage (silencing the nudge via DELEGATE_LOCAL_NO_VERDICT_NUDGE=1 and never recording the verdict). DELEGATE_LOCAL_VERDICT_NUDGE_FD=N resolves the trade-off by redirecting the nudge to caller-chosen file descriptor N instead of fd 2; the recipe is DELEGATE_LOCAL_VERDICT_NUDGE_FD=3 bash delegate.sh prose "X" > out.txt 2>&1 3>>nudge.log — stdout+stderr land cleanly in out.txt, the nudge accumulates on nudge.log via fd 3, and coverage tracking stays intact because the caller can post-process nudge.log to drive a verdict-recording loop. The gotcha: the caller must redirect fd N to somewhere (file, pipe, or another fd); if fd N is closed when the nudge fires, the write fails silently and no nudge lands anywhere.

Discipline for closed-format work

The 2026-05-03 retrospective measured the same 4-sub-task suite with and without prompt discipline. Without discipline (single shot, thinking on, no example, four sub-tasks bundled in one prompt) the local model scored 1.5 of 4. With discipline (thinking off, one-shot example, atomic single-sub-task call, explicit qualifier rules) qwen3-coder-next:latest scored 3.6 of 4 — within 9% of Haiku's 3.95. The same four practices recur in 2026 practitioner reports:

• One sub-task per call — but batch independent prose items. Bundling multiple sub-tasks in one prompt collapses the "single atomic output" property that makes local models reliable. If you have four things to classify, four delegate.sh calls are more reliable than one prompt that asks for four answers. The exception is independent prose items of the same shape (module descriptions, config table entries, changelog bullets, index one-liners): these can batch into a single prose-tier call because they share the same output format and don't cross-reference each other. "Write a one-line description for each of these 6 modules" is one call, not six.
• Include a one-shot example in the prompt. Local models infer the output shape much better from one concrete Example: ... → output: ... block than from prose description alone. The example must use a different finding/item from the actual input so it doesn't leak the answer.
• Make qualifier rules explicit. When a finding text says "this is intentional in single-user dev contexts", local models tend to override that qualifier with prior beliefs (CVSS conventions, "code execution is always high"). Spell out in the prompt: "if the input says behaviour X is intentional in context Y, severity reflects design intent, not vulnerability class".
• Use directive-shaped hard rules, not just examples, for closed-form classification with finite output enums. The 2026-05-03 v4/v5 experiments showed that a single one-shot example does not shift the model's prior on what severity means (qwen3-coder-next stayed at 3/5). What did move the score to 5/5 (Opus parity) was an explicit hard-rule directive: "if the finding text contains 'intentional', 'by design', 'documented as', or 'design choice', severity is capped at medium. This cap is non-negotiable." The v7 follow-up confirmed this generalises: applying the same priority-ordered keyword-triggered "first match wins, non-negotiable" pattern to PR triage (REFACTOR/BUGFIX/FEATURE/DOCS/PERF) hit 5/5 on both deepseek-r1:32b and qwen3-coder-next:latest. The pattern is task-agnostic: spell out the rules as numbered priority-ordered hard directives with keyword triggers and a one-shot example, regardless of whether the rules are calibration caps, category mappings, or some other shape. Independent per-item classification works across a wider model range than cross-reference rule application (which v6 showed needs reasoning-architecture preservation to scale down).
• Thinking off is the default. delegate.sh sends think:false in the API payload automatically. The chain-of-thought tax for closed-format work showed up as both alarmist drift on classification and direct format failures (placeholder substitution).
• Anti-padding directive on prose-tier prompts. Prose-tier output has a strong tendency to end every paragraph with a trailing sentence that restates the point with a participial clause ("ensuring proper notification routing is established", "this distinction is crucial for determining…", "to address the identified gap effectively"). The 2026-05-05 IP-146 share-readiness session observed this on 100% of paragraphs across a multi-file documentation pass; a session-2 follow-on confirmed adding to the prompt visibly reduced (though did not eliminate) the padding. Sharpened 2026-05-21 per issue #138 — explicit participial-clause keyword triggers (ensuring, leading to, supported by, reflecting) added after the original directive let those shapes survive on ~33% of prose-tier outputs in a 2026-05-20 session. The canonical sharpened text is Same directive-rule pattern that closed the v5 calibration gap, applied to prose-tier work — append the sharpened anti-padding block to every prose-tier prompt by default rather than stripping the trailing sentence by hand afterwards. The symmetric failure mode at the opener was observed on a 2026-05-11 maintainer-reply polish (issue #97): the prose tier compressed a warm conversational hook ("Hey @nneul, fun one and the short answer is yes …") down to a clipped acknowledgement that stripped the human cue carrying the project's voice. When the input begins with a warm opener (, , , , or any acknowledgement/greeting prefix), append to the prompt alongside the anti-padding line. Preserve-opener and anti-padding are the same rule applied to opposite ends of the message.

git diff HEAD~5 | bash ~/.claude/skills/delegate-local/scripts/delegate.sh prose \
  "Summarise this diff in 3 bullets focused on user-visible changes."

cat build.log | bash ~/.claude/skills/delegate-local/scripts/delegate.sh reasoning \
  "List only the lines indicating test failures. One per line, no commentary."

Always report the model used ("Delegated to qwen3.6:35b-a3b-q8_0 (prose tier)") so a bad answer is visible to the user. For long inputs, use the long-context tier. To opt out of metrics for a single invocation, set DELEGATE_LOCAL_NO_METRICS=1. To resolve the model without delegating (e.g., for inspection), call pick-model.sh directly.

Prompt scope — closed vs open

Local models reliably produce closed-form output (extract, classify, restructure) but invent findings when asked open-ended questions (find loose ends, suggest improvements, what should we worry about). In one measured session, an 80B model produced four confident concerns from a 10-commit diffstat plus subject lines; all four were wrong on verification (claimed missing automation that existed, claimed missing test coverage that existed, etc.).

Closed prompts that work well:

• "List the lines in this log that match <pattern>."
• "Extract {name, party, position} as JSON from each candidate block."
• "Classify each TODO as P0/P1/P2."
• "Does this YAML match this expected shape? Output CLEAN or list deviations."

Open prompts that produce hallucination:

• "Find anything interesting in this diff."
• "What patterns or loose ends do you see?"
• "Suggest improvements."
• "Is there something we should worry about?"

If the answer would be valuable specifically because the model is reasoning beyond what is in the prompt, that is the wrong job for a local model. Do it yourself or ask Claude.

Tier → model routing

pick-model.sh <tier> resolves a tier to the best installed model at runtime. Do not hardcode model names in calls — the installed set changes. The default backend is auto: on Apple Silicon with mlx_lm.server running on port 8080, routing goes through MLX (Metal-native, lower memory, faster prefill); otherwise it falls back to Ollama. See docs/install-mlx.md for install and auto-start via launchd.

Tier	Use for
code	Code summaries, diff explanations, renaming.
prose	Commit messages, docs, release notes.
reasoning	Structured extraction, classification, triage.
long-context	Large logs, many-file scans, big diffs.
vision	Image OCR, screenshot triage, visual description.
embedding	Local semantic search ("which doc talks about X").
premium-general	Explicit opt-in for verbose enumeration; not a quality upgrade over prose (see baseline).
reasoning-vision	Structured extraction or classification from screenshots.

The prose tier is for generating prose (commit messages, summaries), not for inferring about prose. For analytical work over a diff or log, use reasoning even if the input is text-heavy.

For closed-form classification where the rule applied to one item must propagate context across other items in the list (severity classification of a multi-finding security review, priority triage of related TODOs), prefer code tier over prose tier. The 2026-05-03 v5 retrospective measured qwen3-coder-next:latest at 5/5 (Opus parity) on a 5-finding severity classification with an explicit hard-rule directive, while qwen3.6:35b prose tier scored 2/5 on the same input — the prose-tier model applied the directive literally to findings that contained the trigger keyword and ignored it for findings that inherited the context implicitly, where the code-tier model propagated context across the full list.

The 2026-05-03 v6 follow-up sharpens this: the discriminating axis is reasoning-architecture, not parameter count. deepseek-r1:32b at 19 GB hit Opus parity (5/5) on the same workload as qwen3-coder-next:51 GB. qwen3-coder:30b-a3b at 32 GB (same family, smaller MoE) dropped to 2/5 — same-family scale-down lost the cross-reference capability. The v6 evidence promoted deepseek-r1 to the head of the reasoning tier prefs in scripts/pick-model.sh. When choosing between similarly-priced model options for cross-reference classification work, prefer reasoning-distilled models (deepseek-r1, phi-reasoning, qwq) over equivalent-size coder models from the same family as a model that lost the capability at scale.

The 2026-05-04 adversarial-smaller probe qualifies the v6 finding further: reasoning architecture is necessary but not sufficient. deepseek-r1:14b (9 GB, same family as the 32b parity winner) produced incorrect source-code edits on every adversarial cell — it ignored the REFUSE hatch, diagnosed the problem correctly in prose, then patched with an off-by-one anyway. Architecture-plus-scale is the actual requirement for honest-under-pressure behaviour. Do not substitute the 14b for the 32b when delegating any task where a silent wrong answer is worse than no answer.

Also: avoid phi4-reasoning for SEARCH/REPLACE or other structured-output delegation. Its in-band <think> tokens echo the prompt's one-shot example verbatim inside the thinking block, producing multiple duplicate SEARCH/REPLACE blocks per response that break any reasonable parser. The 2026-05-04 adversarial-smaller probe measured 6 of 6 parse failures on phi4-reasoning with ~2.5–7.5 minutes of wall-time per cell and 19–53 KB outputs. Prefer deepseek-r1 at whatever size fits the hardware, or a non-reasoning fallback, over phi4 for any delegation shape that parses the model's output programmatically.

The premium-general tier exists for tasks where the user has explicitly chosen a larger model. Do not route prose work to it by default — the 2026-05-01 baseline measured qwen3.5:122b as the worst T3 performer in the matrix (citation rate 0.16, vs 0.71 for the 31B gemma4 and 0.36 for the default qwen3.6:35b), with high claim volume that ignored the prompt's 4-claim cap. Bigger does not mean better; verify outputs from this tier especially carefully.

Preference order per tier lives in scripts/pick-model.sh. Edit that file (not the skill body) when your installed models change.

Call shape per tier

code, prose, reasoning, long-context, and premium-general all use the standard delegate.sh <tier> "<prompt>" wrapper — context on stdin, prompt as the argument, response on stdout, metrics appended to the JSONL.

vision and reasoning-vision resolve a model name but have no working dispatch path on the default provider set, so treat them as scaffolding rather than a surface to call. delegate.sh sends text only, and mlx_lm.server 0.31.3 — which is what the vision tier resolves to when MLX is running — rejects image content outright with Only 'text' content type is supported. (measured 2026-08-18). Pull a vision model into a provider that accepts images, pin the list to it, and build the payload by hand:

# Set this to a provider you have confirmed accepts image content parts —
# there is no default that does. The resolution line is tab-separated, so
# `cut` splits it without a literal tab surviving a copy-paste.
export DELEGATE_BASE_URL="http://<image-capable-provider>/v1"
RESOLVED=$(bash ~/.claude/skills/delegate-local/scripts/pick-model.sh --print-resolution vision)
BASE=$(printf '%s' "$RESOLVED" | cut -f1); MODEL=$(printf '%s' "$RESOLVED" | cut -f2)
IMG_B64=$(base64 < /tmp/screen.png | tr -d '\n')
curl -s -H "Content-Type: application/json" "$BASE/chat/completions" \
  -d "$(jq -n --arg m "$MODEL" --arg p "Describe what is in this screenshot." --arg i "$IMG_B64" \
        '{model:$m, messages:[{role:"user", content:[{type:"text", text:$p},
          {type:"image_url", image_url:{url:("data:image/png;base64," + $i)}}]}], stream:false}')" \
  | jq -r '.choices[0].message.content'

embedding has a wired-up primitive — scripts/embed.sh — that takes text on stdin (or via --text "...") and prints the embedding vector to stdout as a compact JSON array of floats. It writes a source:"embed" row to the same metrics JSONL delegate.sh uses, so embedding traffic surfaces in metrics-summary.sh rollups alongside delegation traffic. The recipe prompts/semantic-search.md wraps scripts/semantic-search.sh (a thin cosine-similarity ranker built on embed.sh) and gives the agent a "find the doc that mentions X" surface that avoids reading every file:

# Primitive — embed a single string.
echo "the text to embed" | bash ~/.claude/skills/delegate-local/scripts/embed.sh

# Recipe — rank N files by cosine similarity to a query.
bash ~/.claude/skills/delegate-local/scripts/semantic-search.sh \
  "how do I run the test suite" prompts/*.md README.md

embed.sh bypasses delegate.sh because the wrapper assumes text-in / text-out — embedding output is a vector and the metrics fields differ (embedding_dim rather than output_chars). Image (vision, reasoning-vision) tiers still need the bespoke curl shape above — folding their call shapes into a wrapper is future work.

Failure modes — concrete examples

These are real failure modes observed in production use, surfaced as warnings when you find yourself doing them.

• The "find anything interesting" prompt. Producing fabricated concerns is the highest-volume failure. If your prompt asks the model to surface things that are not in the input, expect invented findings. Constrain it to listing what is present, in a fixed shape, then verify.
• Asking a reasoning model to verify its own claim. The model cannot read your filesystem. If it says "X probably exists in file Y", that is a hypothesis. Run grep yourself.
• Treating long output as confidence. Reasoning models emit chain-of-thought, which can mask a wrong answer in plausible-sounding scaffolding. Look at the final verdict, not the volume.
• Hardcoding model names in calls. Models drift out every few weeks. Always go through pick-model.sh <tier>.
• Putting secrets into the prompt. Local is safer than cloud, but the prompt still ends up in shell history and ollama logs.
• Bigger model = better answer. Not always. The largest installed model (80B) was the worst performer on inference tasks in measured runs; an 11GB reasoning model beat it. Prefer the smallest model sufficient — see scripts/audit-models.sh for upgrade signals.
• Cross-PR / multi-feature commit message drafting. Asking the prose tier to summarise a diff that spans many commits or unrelated features invites fabrication — the model pattern-matches on the markdown text and invents which feature shipped where. In one observed session, a 35B prose-tier model produced a confident 4-paragraph commit message claiming code routing changes that the diff did not contain, and dropping a category ("crypto") that the diff explicitly mentioned. Commit-message drafting is in the Fits list only for single-file mechanical changes; for multi-feature or cross-PR summaries, do it yourself.
• Prose/code contradiction in structured output. A model can refuse in words and comply in code in the same response. The 2026-05-04 adversarial-multifile probe observed qwen3-coder-next:latest emitting a correct REFUSE line ("both tests cannot be satisfied, this is contradictory") attached to a SEARCH/REPLACE patch that silently satisfied the wrong test. Skim-reading the REFUSE prose would pass the response through; running the patched source against the expected tests would catch it. When delegating code work with a REFUSE hatch, the REFUSE line is advisory — the patched source is authoritative. Always verify by running the test.

Keeping the model set current

Local models drift; better ones ship every few weeks. The audit script uses llmfit to compare your installed models against the current HuggingFace catalogue scored for this hardware, and flags uninstalled models that beat the installed leader by 3+ points.

bash ~/.claude/skills/delegate-local/scripts/audit-models.sh

It prints installed models, shows tier routing, runs llmfit recommend --use-case <coding|general> for each tier, and lists suggested pulls with their llmfit composite score (quality + speed + fit + context). It never pulls automatically — you confirm each upgrade. Ollama tags sometimes differ from the HuggingFace name, so verify on https://ollama.com/library before pulling.

Requires llmfit and jq on PATH. Without llmfit the script still prints routing; the upgrade-check section is skipped with a hint.

When reviewing, the rule from ai-model-advisor applies: prefer the smallest model sufficient for the task. Bigger is not better if a 9GB model handles the prompt in half the time.

To refresh llmfit's model database before auditing: llmfit update.

Red flags — stop and do the work yourself

• You are about to delegate something that requires reading more files.
• You cannot summarise the task in a single prompt ≤ 8k tokens.
• The user will act on the answer without reading it.
• You are unsure whether the model's answer would be correct.
• The task involves secrets or credentials (local is safer, but still avoid putting secrets into any prompt).