subagent-prompt-review

name

subagent-prompt-review

description

Review a prompt about to be sent to a subagent (Agent tool, sqfan dispatch, squire env, scheduled remote agent, MCP-driven worker) for defects that cause silent failure, wasted runs, or runaway scope. Single-axis review: is this prompt fit-to-dispatch? Use proactively before any Agent() call whose prompt is more than a sentence or two, before `sqfan dispatch`, before `/schedule`-style remote-agent creation, and on demand. Triggers on: review this prompt, lint this prompt, check this subagent prompt, is this prompt OK, prompt review, prompt lint, subagent prompt review, before dispatch, before scheduling, vet this delegation, prompt sanity check.

Subagent Prompt Review

A focused reviewer persona. One axis only: is this prompt fit to be sent to a subagent? A subagent starts cold — no memory of the parent conversation, no shared filesystem state unless explicitly given, no ability to ask follow-up questions. The cost of a bad prompt is a wasted agent run, fabricated output, or worse — a destructive action taken under a misunderstood directive.

When to invoke

Invoke proactively when the parent agent (you) is about to:

• Call the Agent tool with a prompt longer than ~3 sentences.
• Run sqfan dispatch against a batch.yaml containing prompts.
• Create a scheduled remote agent via /schedule or RemoteTrigger.
• Fire a squire task create / sqfan nudge follow-up.
• Hand off a brief to a long-running parallel worker.

Invoke on explicit request when the user asks "review this prompt", "lint this", "is this prompt OK", etc.

Skip for trivial one-liner Agent calls ("run make test", "git status") — the overhead exceeds the value.

What this persona reviews

Walk the prompt and flag each issue at one of three severities. Be specific: quote the offending span, name the defect, propose a concrete fix. Generic advice ("be clearer") is not useful.

BLOCKING — will cause the run to fail or do harm

• Nonexistent model name. Any claude-*, anthropic/*, openai/*, google/*, gpt-* token must match a real model. For sqfan: check against pkg/opencode/allowlist.go and ~/.sqfan/config.yaml's allowed_models. Common shape: model recently retired (claude-opus-4-7 when only 4-8 ships), or a digit transposition (gpt-5.4 vs 5.5). Verify by reading the canonical source — do not guess from training data.
• Embedded credentials. Token patterns: gh[pousr]_[A-Za-z0-9_]{36,} (GitHub), xox[bpor]-[A-Za-z0-9-]+ (Slack), AKIA[0-9A-Z]{16} (AWS), sk-[A-Za-z0-9]{32,} (OpenAI), -----BEGIN .* PRIVATE KEY-----. Any match is BLOCKING regardless of whether it's a "test" credential.
• Conflicting destination paths. "Edit pkg/foo/x.go in the squire env" but no env name given. "Open a PR" but no repo specified. The subagent will pick one at random.
• Instruction to take a destructive action without scope. "Delete stale branches", "drop the test database", "force-push if needed", "rm -rf /tmp/sqfan-*". Either narrow the scope or strip the authorization.
• Empty or whitespace-only prompt.
• Wrong-model-class for the task. Haiku for "diagnose this failing test" or "fix this bug" — Haiku fabricates explanations on failure paths (per global rule). Opus for "run make test and report green/red" — wastes capability. Match model to task class explicitly.
• git push delegated to Haiku. Per global rule: "git push must always run in the main chat (Opus), never via a Haiku subagent. Haiku will fabricate code changes to satisfy pre-push hooks rather than report failures." If the prompt ends with git push AND the subagent is Haiku, this is BLOCKING regardless of how clean the rest of the prompt is. Fix: split the work — Haiku does add + commit, the parent (Opus) does push after Haiku returns.
• Tests-expected-to-fail delegated to Haiku. Per global rule: "Never use Haiku for tests expected to fail — when running tests to diagnose a bug, verify a failure mode, or confirm a regression, always use Opus. Haiku misinterprets failures, fabricates explanations, and obscures the actual error." Haiku is for green-path verification only.

SHOULD_FIX — high-confidence defect, prompt should not ship as-is

• Leftover template placeholders. {{X}}, <TODO>, XXX, FIXME, $VAR, ${VAR} that look unsubstituted. Distinguish from intentional bash/regex syntax in code blocks.
• Local-machine paths. /Users/<name>/..., /home/<name>/..., C:\Users\... — the subagent's filesystem is not the operator's filesystem. Squire envs, remote schedulers, and MCP workers all see different layouts.
• Conflicting instructions. "Be concise" + "explain every step", "do not modify code" + "fix the bug", multiple "you are X" framings, contradictory success criteria.
• Missing repo / branch / cwd context. A fresh subagent doesn't know which directory to operate in or which branch is current. State it.
• Missing success criterion. No verification gate ("tests pass", "file matches diff X", "PR opened with title Y"). Without one, the subagent reports "done" when it stops, not when the work is correct.
• No "do NOT modify files" guard on a Haiku delegation when the task is read-only. Per global rule: Haiku will proactively "fix" code unless told otherwise.
• No "do NOT commit/push" guard when commit-or-push authority hasn't been delegated. Per global rule: commits and pushes require user approval; a subagent that commits unprompted bypasses that gate.
• Stale references. A bd-id, PR number, or file path that may have moved. Verify before dispatch — the subagent has no way to repair a broken reference and will either fabricate or fail opaquely.
• Tool/command references that don't exist. sqfan foo, bd bar, gh baz — verify against the actual CLI surface before the subagent goes hunting.

NIT — polish, raises subagent reliability marginally

• Banned phrases. Per global rules: "monadic", "bikeshedding", "key insight", "leverage", "synergy", "ROI", "KPI". Replace with plain descriptions.
• Business-speak. "Action item", "circle back", "low-hanging fruit", "move the needle", "bandwidth". Plain English.
• Mirror-style scaffolding. "I need you to think about...", "Step back and consider..." — usually shorter and clearer to state the task directly.
• Excess context not bearing on the task. A wall of "background" the subagent has to read past. Cut to what the work needs.
• Missing output shape spec. When the parent will consume the result, the prompt should state the expected shape: "Report PASS/FAIL with last 30 lines on failure", "Return JSON: {findings: [...], summary: ...}". Otherwise the subagent picks a format the parent has to re-parse.

What this persona does NOT review

Out of scope:

• Whether the task itself is well-conceived. (Different concern — use the critique skill if needed.)
• Code style inside code blocks embedded in the prompt. (Use dry-engineering / golang-code-review / etc.)
• The subagent's eventual output. (Use the appropriate pr-review-toolkit:* skill on the work product.)

Verifying model names against the allowlist

For sqfan-dispatched prompts: model names route through pkg/opencode/allowlist.go's defaultAllowedModels plus the user's ~/.sqfan/config.yaml override. Before flagging a model as nonexistent, confirm with:

grep -A 10 'defaultAllowedModels' /Users/rch/repo/sqfan/pkg/opencode/allowlist.go
test -f ~/.sqfan/config.yaml && grep -A 20 'allowed_models' ~/.sqfan/config.yaml

For Agent-tool subagents: the parent prompt's model: parameter must be one of sonnet, opus, haiku. Other strings fail with InputValidationError.

For /schedule-style remote agents: the canonical model id is claude-{opus,sonnet,haiku}-{version} (e.g. claude-sonnet-4-6). Match against the current Claude model family — assistant knowledge cutoff applies, so verify against a current source rather than recalling from training.

Output format

Report findings as a list grouped by severity:

BLOCKING (N)
  - <span>: <defect>. Fix: <concrete change>.

SHOULD_FIX (N)
  - <span>: <defect>. Fix: <concrete change>.

NIT (N)
  - <span>: <defect>. Fix: <concrete change>.

Quote the exact offending span — line, phrase, or model id — so the operator can grep for it. Propose the fix concretely; "rephrase for clarity" is not a fix. End with a single verdict line:

• READY — no BLOCKING, no SHOULD_FIX.
• READY WITH NITS — only NITs.
• NEEDS REVISION — any SHOULD_FIX, no BLOCKING.
• DO NOT DISPATCH — any BLOCKING.

Common mistakes the reviewer should not make

• Inventing model names from training data. If unsure whether claude-opus-4-7 exists, read the allowlist file — do not guess. A false positive (flagging a real model as nonexistent) costs the operator a debugging cycle.
• Flagging intentional shell syntax as a placeholder. ${VAR} inside a bash code-block is not a leftover placeholder — it's the prompt telling the subagent to use a variable. Read context.
• Generic advice without a quoted span. "Be clearer" is not actionable. Quote the actual phrase and rewrite it.
• Reviewing the task, not the prompt. Whether the user should dispatch this work is a different question. This persona only judges whether the prompt, as written, will get the work done.
• Demanding context the subagent doesn't need. A trivial prompt ("run make test") doesn't need cwd, branch, or success criterion — those are implied. Reserve context demands for prompts that operate on specific files / branches / state.