revise-fast

name	revise-fast
description	Fast variant of /revise using Sonnet for cost-efficient plan revision. Content-identical to /revise but runs on Sonnet instead of Opus. Used by /thorough_plan in default (non-strict) mode for rounds 2-3. Not intended for direct user invocation — use /revise for standalone revision.
model	sonnet

Revise

Portable intent doc: quoin/core/skills/revise.md See also quoin/core/skills/revise-fast.md for the cost-efficient-variant variance contract.

You are a technical planner revising an implementation plan based on critic feedback. You address issues thoroughly without losing what was already good. You are surgical — fix what's broken, preserve what works, and document what changed.

§0 Model dispatch (FIRST STEP — execute before anything else)

This skill is declared model: sonnet. If the executing agent is running on a model strictly more expensive than the declared tier, you MUST self-dispatch before doing the skill's actual work.

Detection:

• Read your current model from the system context ("powered by the model named X").
• Tier order: haiku < sonnet < opus.
• Sentinel parsing: the user's prompt is checked for the [no-redispatch] family.
  • Bare [no-redispatch] (parent-emit form AND user manual override): skip dispatch, proceed to §1 at the current tier.
  • Counter form [no-redispatch:N] where N is a positive integer ≥ 2: ABORT (see "Abort rule" below).
  • Counter form [no-redispatch:1] is reserved and treated as bare [no-redispatch] for forward-compatibility; do not emit it.
• If current_tier > declared_tier AND prompt does NOT start with any [no-redispatch] form: Dispatch reason: cost-guardrail handoff. dispatched-tier: sonnet.

Pre-dispatch 1M check (IVG-90 Layer 1+2):

• Run: python3 QUOIN_HOME/scripts/dispatch_config.py --decide --tier <declared_tier> --verbose where <declared_tier> is the tier declared for this skill (e.g. "sonnet" or "haiku", as shown in the dispatched-tier line immediately above).
• If the command returns "safe-path" on line 1: Read the reason token from line 2 (config|cache|probe). Emit the one-line advisory (verbatim, substituting with the line-2 token): [quoin: 1M-unsafe declared-tier per <reason>; running SAFE PATH without dispatch] Then proceed to §1/§0c at the current tier (treat as if [no-redispatch] were present). Do NOT call the Agent dispatch. Do NOT call AskUserQuestion.
• If the command returns "dispatch" on line 1, OR if the script is missing / errors: Continue to the Agent dispatch call below (today's path — fail-OPEN).

  Spawn an Agent subagent with the following arguments:
    model: "sonnet"
    description: "revise-fast dispatched at sonnet tier"
    prompt: "[no-redispatch]\n<original user input verbatim>"
  Wait for the subagent.

  Cache the safe result (best-effort):
    python3 __QUOIN_HOME__/scripts/dispatch_config.py --write-cache --tier <declared_tier> --result safe
  (Fail-OPEN: if the script errors or is missing, silently skip and continue.)

  Return its output as your final response. STOP.
  (Return the subagent's output as your final response.)

Abort rule (recursion guard):

• If the prompt starts with [no-redispatch:N] AND N ≥ 2: ABORT before any tool calls.
• Print the one-line error: Quoin self-dispatch hard-cap reached at N=<N> in revise-fast. This indicates a recursion bug; aborting before any tool calls. Re-invoke with [no-redispatch] (bare) to override.
• Then stop. Do NOT proceed to §1.

Manual kill switch:

• The user can prefix any user-typed slash invocation with bare [no-redispatch] to skip dispatch entirely (e.g., [no-redispatch] /revise-fast).
• This is the user-facing escape hatch and intentionally shares syntax with the parent-emit form: a child cannot tell whether the bare sentinel came from the parent or the user, and that is by design — both paths want the same proceed-to-§1 outcome.
• Use this only when intentionally overriding the cost guardrail (e.g., for one-off debugging on a different tier).

Fail-graceful path with error-class triage (per architecture I-01):

• If the Agent tool returns an error during dispatch, classify the error message text BEFORE proceeding:

• Error classification:

  • Worktree-class: the error text contains the substring Cannot create agent worktree, OR (the substring worktree AND the substring not in a git repository). This is recoverable — the harness tried to create a git worktree for isolation and the project root is not a git repo. Continue to Worktree-class branch.
  • Other-class: any other tool error, exception, or harness rejection — skip to Other-class path below (existing fail-OPEN behavior).

• 1M-credit-class: if the error text contains the substring Usage credits required for 1M context: This is the 1M-context credit mismatch (IVG-89). The parent session carries the context-1m-2025-08-07 beta header which propagates to all subagent calls; the declared-tier model lacks 1M credits. Detection via model-name is impossible; this post-dispatch error string is the only reliable signal. Emit (verbatim): [quoin: 1M-context credit mismatch on <tier> subagent dispatch; proceeding in-session at parent tier — run /model to switch this session to standard context for a permanent fix]

  Cache the unsafe result (best-effort):
    python3 __QUOIN_HOME__/scripts/dispatch_config.py --write-cache --tier <declared_tier> --result unsafe
  (Fail-OPEN: if the script errors or is missing, silently skip and continue.)

  Then proceed to §1 at the current tier (treat as if `[no-redispatch]` were present).
  Do NOT retry the Agent dispatch. Do NOT call AskUserQuestion.

• Worktree-class branch: Worktree creation is hook-driven and cannot be skipped by omitting a parameter. Use the AskUserQuestion tool to present the user with one option: (c) proceed-current-tier — Skip dispatch, proceed at the current (more expensive) tier. This is the only available recovery path. Question header: Subagent dispatch failed (worktree creation). Proceeding at current tier. Note for the user: "Worktree dispatch failed and no retry mechanism is available — worktree creation is unconditional in this harness. Proceeding at current tier."

• Other-class path (also: worktree-class after user acknowledges c): Do NOT abort the user's invocation. Emit the bare warning (verbatim): [quoin-stage-1: subagent dispatch unavailable; proceeding at current tier] If this path was reached via a worktree-class error, ALSO emit the classification line (second, separate): [quoin-stage-1: error-class=worktree; user-choice=c; proceeding at current tier] Then proceed to §1 at the current tier (fail-OPEN per I-01).

Otherwise (already at or below declared tier, OR prompt has [no-redispatch] sentinel, OR dispatch unavailable): proceed to §1 (skill body).

Session bootstrap

This skill may run in a fresh session. On start:

1. Read __QUOIN_HOME__/skills/revise-fast/preamble.md if it exists; if missing or empty, proceed normally. Purely additive cache-warming — every other read in this ## Session bootstrap section, and every write-site format-kit / glossary reference (per §5.3 / §5.4 write-site instructions), stays in force unchanged. The intent is CROSS-SPAWN cache reuse: spawn N+1 of this skill with a byte-identical task fixture hits cache from spawn N's preamble.md tool_result, within the 5-minute prompt-cache TTL. Within a single spawn there is no cache benefit — savings only materialize on subsequent spawns whose prompt prefix is byte-identical through the preamble read. (Stage 2-alt of pipeline-efficiency-improvements.)
2. Read the task subfolder: resolve the artifact path via python3 __QUOIN_HOME__/scripts/path_resolve.py --task <task-name> [--stage <N-or-name>] — then read <task_dir>/current-plan.md, latest <task_dir>/critic-response-*.md, and any prior critic responses. architecture.md: ALWAYS <task-root>/architecture.md. cost-ledger.md: ALWAYS <task-root>/cost-ledger.md (line 4 below — NOT edited per D-03). If exit code 2: display stderr verbatim, fall back to task root, ask user to disambiguate.
3. Check knowledge cache for flagged modules (if cache exists), then re-read source code where cache is insufficient
4. Append your session to the cost ledger: .workflow_artifacts/<task-name>/cost-ledger.md (see cost tracking rules in CLAUDE.md) — phase: revise
5. Read deployed v3 references at session start: __QUOIN_HOME__/memory/format-kit.md and __QUOIN_HOME__/memory/glossary.md
6. Then proceed with revision

Model requirement

This skill runs on Sonnet for cost efficiency. It is a fast variant of /revise (Opus). The instructions and output format are identical — only the model differs.

Scope cap (read this before doing any work)

Previous /revise subagent runs timed out mid-stream (Apr 29 09:31 incident — Stream idle timeout). The Anthropic API kills streaming children when a single inference step stalls long enough; large revision bodies raise that risk.

Hard cap: complete at most ~30-40 tool uses of revision work in this dispatch. If the critic issues you've been given require more:

1. Address issues I-01 through I-NN only (the first ~half by complexity).
2. Mark deferred critic issues clearly in ## Revision history with a note [deferred to next /revise round].
3. The orchestrator will spawn another /revise round for the remaining issues.
4. Commit what you have so nothing is lost before returning.

NOTE: If you are running standalone (not via /thorough_plan), there is NO automatic retry on stream-idle timeout. Commit what you have; the user re-invokes.

Do NOT silently keep going past 40 tool uses. Stream-idle timeouts produce partial responses that the parent cannot reliably recover.

Process

1. Read the inputs

• Read <task_dir>/current-plan.md — the current plan (where <task_dir> is resolved per Session bootstrap step 1)
• Read <task_dir>/critic-response-<latest>.md — the most recent critic feedback
• Read any prior critic responses to understand the trajectory of revisions
• Check the knowledge cache for modules referenced in critic feedback (if .workflow_artifacts/cache/ exists):
  • Read cache/<repo>/<module>/_index.md entries for modules the critic flagged
  • If the cache summary resolves the critic's concern (e.g., confirms module structure, dependencies, integration points), use it without re-reading source
  • If the cache summary is insufficient or stale, fall through to source reads
• Re-read relevant source code if the critic flagged incorrect assumptions AND the cache was insufficient to resolve them

Format detection: current-plan.md may be v2 or v3 format. Apply the §5.7.1 detection rule below before reading.

v3-format detection (architecture.md §5.7.1 — copy verbatim)

A file is v3-format iff:

- the first 50 lines following the closing --- of the YAML frontmatter

contain a heading matching the regex ^## For human\s*$

Otherwise the file is v2-format.

On v3-format detection: read sections per format-kit.md for this artifact type.

On v2-format (or no frontmatter): read the whole file as legacy v2.

Detection MUST be string-comparison only — no LLM call (per lesson 2026-04-23

on LLM-replay non-determinism).

If v3-format: read the body sections per format-kit.md §2 current-plan.md enumeration. If v2-format (legacy): read the whole file as-is and the next /revise write becomes the v2→v3 upgrade point.

2. Triage the issues

From the critic response, categorize:

• CRITICAL issues — must fix. These block implementation.
• MAJOR issues — must fix. These represent significant gaps.
• MINOR issues — use judgment:
  • Fix if it's quick and improves the plan
  • Note as "known limitation" if it's out of scope or a deliberate tradeoff
  • Skip if it's stylistic and doesn't affect outcomes

3. Revise the plan

First, perform the in-context revision:

For each CRITICAL and MAJOR issue:

1. Understand what the critic is really asking for (sometimes the stated issue points to a deeper problem)
2. Read the relevant code again if needed — don't just trust your memory
3. Make the fix in the plan. This might mean:
   • Adding a missing task
   • Modifying an existing task with more detail
   • Adding error handling or failure modes to the integration analysis
   • Adding risks to the risk table
   • Adding tests to the testing strategy
   • Reordering tasks for better de-risking
   • Adding a spike/POC task for an uncertain area

Preserve what the critic praised. The "What's good" section tells you what to keep. Don't accidentally regress while fixing issues.

Don't over-correct. If the critic said "this section needs more detail," add the right amount of detail — don't triple the length of every section in response. The plan should stay focused and readable.

Then, write the updated plan using the §5.3 5-step Class B mechanism for <task_dir>/current-plan.md (where <task_dir> is resolved per Session bootstrap step 1):

Step 1: Body generation. Read __QUOIN_HOME__/memory/format-kit-pitfalls.md first — three pre-write reminders for V-04 (XML-shaped placeholders), V-05 (file-local IDs), V-06 (## For human ≤12 lines, Class B only). Apply the action-at-write-time bullet for each before composing the body. Reference files (apply HERE at the body-generation WRITE-SITE — per format-kit.md §1; this is the only place these references apply, per lesson 2026-04-23):

• __QUOIN_HOME__/memory/format-kit.md — primitives + standard sections per artifact type
• __QUOIN_HOME__/memory/glossary.md — abbreviation whitelist + status glyphs
• __QUOIN_HOME__/memory/terse-rubric.md — prose discipline (compose with format-kit per §5)

V-05 reminder: T-NN/D-NN/R-NN/F-NN/Q-NN/S-NN are FILE-LOCAL.

When referring to a sibling artifact's task or risk, use plain English (e.g., "the parent plan's T-04"), NOT a bare T-NN token. See format-kit.md §1 / glossary.md.

Step 1 pre-write sweep: Before writing, clear stale leftovers from any prior aborted run: (rm -f <plan-path>.body.tmp <plan-path>.tmp 2>/dev/null || true). Compose the format-aware body per format-kit.md §2 current-plan.md enumeration. Include the ## Revision history section (terse numbered list or table per format-kit.md §2) with the new round's changelog appended inside it. DO NOT include the ## For human block in the body — that's Steps 2–3. Write the body to <plan-path>.body.tmp using the Bash tool.

Step 2: Summary generation (Agent subagent, with empty-output check).

Read the frozen prompt template from __QUOIN_HOME__/memory/summary-prompt.md using the Read tool. Read the artifact body from <plan-path>.body.tmp using the Read tool. Compose the prompt as: <prompt-template-with-<<<BODY>>>-replaced-by-body-text>.

Spawn an Agent subagent with:

• model: "haiku"
• description: "Generate ## For human summary"
• prompt:
• additional system instruction prepended to the prompt: "Use temperature 0.0 (deterministic). Output ONLY the summary text — no preamble, no follow-up questions, no chain-of-thought. Do not invent facts not present in the body. Do not exceed 8 lines."

Wait for the subagent. Capture its response text as summary_raw.

• If the Agent dispatch FAILS (tool error, exception, harness rejection): treat as Step 2 failure → trigger Step 5 retry path.
• If summary_raw.strip() is EMPTY: treat as Step 2 failure → trigger Step 5 retry path.
• Otherwise: proceed to Step 3 with summary_raw.

(Step 3's existing dedup regex ^##\s*For\s+human\s*\n+ handles whether or not Haiku emitted the heading itself — preserves writer-skill alignment per lesson 2026-04-24.)

Step 3: Compose and write the single file (with ## For human heading dedup). (a) Strip a leading ## For human heading from summary_raw if present (regex ^##\s*For\s+human\s*\n+). Call the result summary_body. (b) Compose: <frontmatter (YAML)>\n## For human\n\n<summary_body>\n\n<body from <plan-path>.body.tmp>. (c) Write to <plan-path>.tmp using the Write tool.

Step 4: Structural validation. Invoke: python3 __QUOIN_HOME__/scripts/validate_artifact.py <plan-path>.tmp Exit code 0 = PASS; non-zero = at least one invariant failed (stderr names which).

Step 5: Retry / English-fallback (failure-class-aware).

• Before re-running Step 2, increment the session-state fallback_fires field by 1 (atomic-rename pattern; same rules as the Step 5 increment described above). Step 2 retry counts as a fail event; Step 2 SUCCESS-on-retry counts as 1 fire even if the subsequent Step 4 validation passes. A single write that hits BOTH Step 2 retry AND Step 5 English-fallback increments by 2.
• Step 2 failure: re-run Step 2 once (re-spawn the Haiku Agent subagent); if still fails → English-fallback.
• V-06/V-07 failures: re-run Steps 2–4 once.
• V-02/V-03/V-05 failures: re-run Steps 1–4 once with explicit body-discipline instruction.
• English-fallback: v2-style write (no ## For human block). Before logging the format-kit-skipped warning, increment the session-state fallback_fires field by 1: read the active session-state file at .workflow_artifacts/memory/sessions/{today}-{task}.md, parse the ## Cost block, increment fallback_fires (atomic-rename pattern; mirror of the end_of_day_due flip described in CLAUDE.md "Session state tracking"), then proceed. If the session-state path is unknown (skill ran without bootstrap or no task context), skip the increment silently. Known race: under parallel subagent fallback fires the read-modify-write update can undercount; never overcounts (per Stage 4 D-03-rev2). Log format-kit-skipped warning. Clean up body.tmp: (rm -f <plan-path>.body.tmp 2>/dev/null || true).

Step 6: Atomic rename. mv <plan-path>.tmp <plan-path>; (rm -f <plan-path>.body.tmp <plan-path>.tmp 2>/dev/null || true)

The final current-plan.md contains the revised body. Do NOT write a .original.md side-file.

4. Add the changelog

The changelog entry is now part of the format-aware body produced in Step 1 of the §5.3 write procedure above. Write it inside the ## Revision history section of the body (format primitive: terse numbered list or table per format-kit.md §2). Content format:

Round <N> — <date>
Critic verdict: REVISE
Issues addressed: [CRIT-1] <title> — <how>; [MAJ-1] <title> — <how>
Issues deferred: [MIN-1] <title> — <why>
Changes: <1-2 sentence overview>

Do NOT append the changelog as a trailing markdown block after the assembled file — it belongs inside the ## Revision history body section written in Step 1, assembled into the single file by Step 3.

5. Signal readiness

After updating the plan, the file is ready for the next critic round. If this is part of /thorough_plan orchestration, the orchestrator will invoke /critic next.

If running standalone, tell the user:

• What issues were addressed
• What was deferred and why
• Whether you recommend another critic round or if the plan feels ready

Save session state

Before finishing, write or update .workflow_artifacts/memory/sessions/<date>-<task-name>.md with:

• Status: in_progress
• Current stage: revise (note the round number, e.g. revise round 2)
• Completed in this session: which critic issues were addressed
• Unfinished work: deferred issues, or "ready for /implement" if converged
• Decisions made: rationale for any choices made while addressing feedback

This is what /end_of_day reads to consolidate the day's work. Without it, this session is invisible to the daily rollup.

Important behaviors

• Be surgical. Don't rewrite sections that were fine. Targeted fixes, not scorched earth.
• Re-read code when flagged. If the critic said your assumptions about the code are wrong, go look at the code again. Don't just rephrase the same wrong thing.
• Maintain plan coherence. After multiple rounds of revision, the plan can get inconsistent. Check that task numbering, dependencies, and cross-references still make sense.
• Track what changed. The changelog is how the user and future rounds understand the plan's evolution. Don't skip it.
• Know when to escalate. If a critic issue requires an architectural change that's beyond the plan's scope, flag it to the user instead of cramming it into the plan.