An agentic skills framework & software development methodology that works.
Cut review-cost drivers: turn-aware models, inline diffs, scoped evidence
Jesse Vincent5e03007c85d4
diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.mdindex ae801025c..9a0f06608 100644--- a/skills/subagent-driven-development/SKILL.md+++ b/skills/subagent-driven-development/SKILL.md@@ -104,6 +104,12 @@ most capable model; a subtle concurrency change does.omitted model inherits your session's model — often the most capable andmost expensive — which silently defeats this section.+**Turn count beats token price.** Wall-clock and context cost scale with how+many turns a subagent takes, and the cheapest models routinely take 2-3× the+turns on multi-step work — costing more overall. Use a mid-tier model as the+floor for implementers and reviewers; reserve the cheapest tier for+single-file mechanical fixes.+**Task complexity signals (implementation tasks):**- Touches 1-2 files with a complete spec → cheap model- Touches multiple files with integration concerns → standard model@@ -154,6 +160,11 @@ final whole-branch review. When you fill a reviewer template:- Include the spec/design's global constraints that bind the task (versionfloors, naming and copy rules, platform requirements) in the requirementsyou paste — a reviewer can only enforce what you hand them.+- Paste the task's diff (`git diff BASE..HEAD` output) into the reviewer+ prompt when it fits comfortably (up to a few hundred lines). A reviewer+ with the diff in hand needs few or no tool calls.+- Dispatch fix subagents for Critical and Important findings. Record Minor+ findings and move on — they roll up to the final whole-branch review.## Prompt Templatesdiff --git a/skills/subagent-driven-development/code-quality-reviewer-prompt.md b/skills/subagent-driven-development/code-quality-reviewer-prompt.mdindex cb9dbc64f..6fb27e3f4 100644--- a/skills/subagent-driven-development/code-quality-reviewer-prompt.md+++ b/skills/subagent-driven-development/code-quality-reviewer-prompt.md@@ -32,6 +32,14 @@ Subagent (general-purpose):git diff [BASE_SHA]..[HEAD_SHA]```+ ## Diff++ [DIFF]++ If the diff is provided above, review from it directly — do not re-run+ the git commands or re-read the files it already shows. Fetch anything+ further only for a named concrete risk.+## Read-Only ReviewYour review is read-only on this checkout. Do not mutate the working tree,@@ -84,12 +92,15 @@ Subagent (general-purpose):significantly grow existing files? (Don't flag pre-existing filesizes — focus on what this change contributed.)- Answer each item above with file:line evidence, not a bare yes or no.- An unsupported "yes" is not a review.+ Cite file:line evidence for every finding and for any check you would+ otherwise answer with a bare "yes." Cite, don't narrate — a tight report+ that points at lines beats a long one that retells the diff.## CalibrationCategorize issues by actual severity. Not everything is Critical.+ Important means this task cannot be trusted until it is fixed;+ "coverage could be broader" and polish suggestions are Minor.Acknowledge what was done well before listing issues — accurate praisehelps the implementer trust the rest of the feedback.@@ -127,5 +138,8 @@ Subagent (general-purpose):- `[TASK_TEXT]` — the task's requirements text or plan reference, for context- `[BASE_SHA]` — commit before this task- `[HEAD_SHA]` — current commit+- `[DIFF]` — paste `git diff BASE..HEAD` output when it fits comfortably+ (up to a few hundred lines); otherwise replace with "(not provided — run+ the git commands above)"**Reviewer returns:** Strengths, Issues (Critical/Important/Minor), Task quality verdictdiff --git a/skills/subagent-driven-development/spec-reviewer-prompt.md b/skills/subagent-driven-development/spec-reviewer-prompt.mdindex 8e6d7f37d..43e8d3d31 100644--- a/skills/subagent-driven-development/spec-reviewer-prompt.md+++ b/skills/subagent-driven-development/spec-reviewer-prompt.md@@ -30,6 +30,13 @@ Subagent (general-purpose):Only read files in this diff. Do not crawl the broader codebase.+ ## Diff++ [DIFF]++ If the diff is provided above, review from it directly — do not re-run+ the git commands or re-read the files it already shows.+Spec compliance is judged by reading the diff against the requirements.The implementer already ran the tests and reported TDD evidence — do notre-run them. If a requirement cannot be verified from this diff alone