agentleFS
SaikaAcoSaikaAco/saika-hermes-skills/skills/context-budget-orchestration/SKILL.md

context-budget-orchestration

Skill2 starsChanged 4 months agoMITView on GitHub

Use when work is multi-step, context-heavy, research-heavy, or delegated. Contains bulky context, phases work, bounds retries, delegates independent reasoning, and reserves capacity for verification.

The file

Show its rules and text

We split this skill into the rules it gives an agent

51 rules. About 0 are common, 47 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈47

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep the parent Hermes session effective when a task can expand through tool output, long files, research trails, implementation loops, or …

    line 18
  2. Distinctive:

    Contain: keep bulky deterministic material out of the parent context.

    line 22
  3. Distinctive:

    Reserve: stop expanding early enough to verify artifacts and deliver a grounded result.

    line 24
  4. Distinctive:

    Never repeat a materially identical failed attempt.

    line 55
  5. Distinctive:

    Use a supported Python 3 interpreter compatible with the script (Python 3.10+ is sufficient).

    line 87
  6. Distinctive:

    Before dispatch, inspect the active tool schema and effective runtime configuration.

    line 101
  7. Very specific:

    Use only advertised parameters.

    line 103
  8. Distinctive:

    Do not restore obsolete Python/runtime code to satisfy outdated API wording.

    line 107
  9. Distinctive:

    Use when one or more conditions hold:

    line 111
  10. Distinctive:

    Use lightly or skip for a quick lookup, a small local edit, one short file, or a deterministic operation whose orchestration overhead …

    line 121
  11. Distinctive:

    Before heavy work, state a compact budget:

    line 125
  12. Distinctive:

    Treat the available interaction/call budget as a phase budget, not a target to consume.

    line 150
  13. Distinctive:

    If the runtime exposes no explicit budget, estimate from task size and expected output.

    line 160
  14. Distinctive:

    If the request materially expands, finish the current phase and record state before continuing in a fresh phase.

    line 165
  15. Distinctive:

    Do not synthesize a conclusion that depends on a child until its result arrives and the parent verifies its evidence handles.

    line 168
  16. Distinctive:

    If a required child is still running and no independent work remains, preserve a compact current-state artifact and yield for its …

    line 169
  17. Distinctive:

    If required work cannot fit inside the reserve, stop optional branches and continue in a fresh phase rather than claiming completion.

    line 170
  18. Distinctive:

    If the result settles the user-facing question, deliver it immediately, leading with the actual decision or next action.

    line 179
  19. Distinctive:

    Keep exact approvals fail-closed.

    line 183
  20. Distinctive:

    Before nontrivial delegated or background work, the parent records internally:

    line 187
  21. Distinctive:

    Shrink or re-shard bounded children: when work is independently acceptable, the parent can integrate it, each shard fits the live window, …

    line 213
  22. Distinctive:

    Mix surfaces within the same DAG: when useful: bounded reasoning children, durable implementation workers, and background deterministic …

    line 217
  23. Very specific:

    Do not spawn agents merely to move mechanical output elsewhere.

    line 221
  24. Distinctive:

    Every delegated task should include:

    line 261
  25. Distinctive:

    read back changed files;

    line 294
  26. Very specific:

    run tests/builds/validators.

    line 296
  27. Very specific:

    After that, switch surface: DOM/accessibility/direct file/API before more coordinate clicking.

    line 306
  28. Distinctive:

    Stop broad collection when outputs repeat, contradict without new evidence, or no longer change the decision.

    line 310
  29. Distinctive:

    Before every nontrivial delegation, record internally:

    line 321
  30. Distinctive:

    Do not reuse it unchanged when:

    line 346
  31. Distinctive:

    When strategy or precedent identifiers are available, material expansion requires a new task class or an explicitly scope-qualified …

    line 354
  32. Distinctive:

    When the user prioritizes elapsed time over token economy:

    line 360
  33. Distinctive:

    use higher reasoning effort for review or architecture and reserve the highest permitted effort for a decisive shard whose complexity or …

    line 364
  34. Distinctive:

    prefer one bounded, adequately resourced fan-out over serial trial and error.

    line 370
  35. Distinctive:

    After any timeout, do not dispatch another attempt until all are true:

    line 374
  36. Distinctive:

    Before retrying, the parent must be able to support this sentence with evidence:

    line 391
  37. Distinctive:

    If the sentence cannot be supported, do not retry.

    line 398
  38. Distinctive:

    Stop and inspect: Verify that the previous worker or process is no longer live.

    line 406
  39. Distinctive:

    Parent writes the retry DAG: Before another orchestrated attempt, define bounded shards, dependencies, exact source or file scopes, output …

    line 419
  40. Distinctive:

    Retry only incomplete shards: Prefer independently completable fan-out so one timeout cannot hide or cancel successful siblings.

    line 424
  41. Distinctive:

    Never treat silence, an absent result, a timeout notice, or an exhaustion summary as success.

    line 441
  42. Distinctive:

    Keep the accepted user outcome, current blocker, and subtask contribution in the existing contract.

    line 456
  43. Distinctive:

    If no useful authorized action can advance the outcome, surface the actual blocker rather than inventing safe-looking busywork.

    line 478
  44. Distinctive:

    Use these decisions inside existing task records and required receipts.

    line 482
  45. Distinctive:

    Stop after the approved call: Follow-up calls require a new proposal and explicit approval.

    line 518
  46. Distinctive:

    Create one compact ledger in an approved workspace only when no suitable record exists.

    line 559
  47. Distinctive:

    Keep the ledger short and raw logs behind handles.

    line 595
  48. Distinctive:

    When the parent starts repeating calls, losing constraints, or depending on memory of a long transcript:

    line 602
  49. Distinctive:

    stop broad reading and optional branches.

    line 604
  50. Distinctive:

    update the state ledger;

    line 606
  51. Distinctive:

    never turn a fallback summary into an unverified completion claim.

    line 609

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Context Budget Orchestration

Overview

Keep the parent Hermes session effective when a task can expand through tool output, long files, research trails, implementation loops, or multi-agent reasoning.

The method has three layers:

  1. Contain: keep bulky deterministic material out of the parent context.
  2. Orchestrate: delegate bounded, independent reasoning with explicit contracts.
  3. Reserve: stop expanding early enough to verify artifacts and deliver a grounded result.

This skill defines methodology, not permission. It does not authorize paid providers, external side effects, persistent changes, or broader delegation than the user and runtime permit.

This is an independently maintained public derivative of the context-budget orchestration method developed by SaikaAco with Hermes Agent. It preserves the method's causal gates, sizing, recovery, and outcome-preservation rules without requiring its original operator's paths, profiles, private policies, plugins, or model choices. The related Hermes skill is optional guidance, not a prerequisite. Use the active tool schemas and the official Hermes documentation to resolve runtime compatibility.

Three operating modes share the same admission and verification boundaries:

  1. Automatic containment: reduce deterministic bulk first; delegate independent reasoning only within existing permission when it would materially protect parent context.
  2. Explicit delegation: coordinate bounded children using the configured runtime model/provider and supported reasoning effort; do not infer this mode from “serious”, “deep dive”, “review”, or “dual model”.
  3. Optional paid external review: complete the primary analysis first, then obtain approval for one costed review call and adjudicate every substantive comment. A review request alone is not payment or disclosure authorization.

Causal execution gates

Apply these gates before any costly or stateful execution or retry, including downloads, dependency acquisition, builds, test suites, clones, VMs, deployments, migrations, long background commands, and repeated external API operations. Gate numbers retain the method's lineage; no private principles file is needed.

Gate 4 — First-failure bundle

On the first failure, stop the costly sequence and preserve a machine-readable bundle before any retry. Bind at least:

  • exact artifact identity;
  • command and bounded environment identity;
  • attempt results and full safe error evidence;
  • causally reachable state;
  • measured recovery/stop state;
  • evidence handles and hashes.

A summary status cannot replace the underlying attempts and errors. Do not parse truncated display text as structured data; retain complete safe evidence behind handles, excluding secrets. Failure paths must persist the bundle in finally or equivalent recovery logic, including when the run stops early.

Gate 5 — Causal retry embargo

Never repeat a materially identical failed attempt. Before a retry, record:

  1. the evidenced failure cause;
  2. the single causal variable changed, with before/after values;
  3. why that change can remove the cause and the evidence supporting it;
  4. a new attempt fingerprint covering artifact, command, environment, runtime configuration, and material limits.

A longer timeout alone is not a causal change unless preserved evidence shows ongoing progress or proves latency was causal. Unknown cause means evidence collection, not retry. A changed hash, prompt, surface, or effort label alone does not establish causality. Timeout retries must additionally pass the sizing and topology embargo below.

Gate 6 — Cost ladder

Declare the cheapest applicable ordered proof ladder before execution:

  1. static identity and configuration;
  2. official/reference control;
  3. bounded sentinel;
  4. build or dependency acquisition;
  5. clone, VM, deployment, or migration;
  6. full run.

Every lower applicable tier must pass before a costlier tier starts. Give an explicit reason for each non-applicable tier; do not omit a cheaper relevant check to bypass it. Stop whenever an unresolved cheaper check could falsify the route. This ordering follows the packaged validator, which ranks a full run above the other costly operations.

Mechanical receipt and its limits

For reusable executors or multi-phase work, validate a receipt before entering a costly tier. Package-relative support files:

  • Receipt schema
  • Receipt template
  • Executor checklist
  • Standard-library receipt validator
  • Validator regression tests

Use a supported Python 3 interpreter compatible with the script (Python 3.10+ is sufficient). From the package directory, the validator interface is:

python3 scripts/validate_causal_execution_gate.py <receipt.json>

The receipt uses schema: causal-execution-gate-v1, task/attempt IDs, lowercase SHA-256 attempt/environment fingerprints, artifact identities, command argument array, runtime configuration, material limits, declared ladder, and current tier. Each ladder entry records applicability, status, evidence handles, and reason. Applicable PASS entries need evidence; NOT_APPLICABLE entries need a reason. Lower declared tiers must be resolved, the current tier must not already be FAIL, and higher tiers cannot have premature terminal results.

For an initial attempt, both prior_failure and retry are null. For a retry, include the prior attempt ID/fingerprint/cause and full first-failure bundle, plus changed_causal_variable, differing before/after values, removal_rationale, and evidence handles. Recovery must be measured, with a state and supporting handles. Do not invent evidence or treat the unfilled template as an admission receipt.

The script returns JSON and exit code 0 for an admitted receipt; rejection or unreadable input exits 2. It performs selected structural and causal-consistency checks, not complete JSON Schema validation. It does not recompute hashes, inspect referenced evidence, prove cause/removal, discover omitted cheaper tiers, enforce runtime budgets, or contain execution. Producers and verification owners remain responsible for those properties and for schema conformance. Schema identifiers are metadata, not a requirement to contact a private service; use the packaged schema locally. Validator success is an admission aid, never execution authority.

Runtime API compatibility

Before dispatch, inspect the active tool schema and effective runtime configuration. This document does not imply that a custom or newer API is installed.

  • Use only advertised parameters. Preserve explicit role restrictions where the runtime honors them; a worker instruction is not a capability restriction when the runtime ignores the role. If essential containment is unavailable, do not launch that route.
  • Choose per-call/per-worker model or effort only when supported and authorized. Otherwise retain the configured delegation model/provider/effort or inherited parent setting, and report the actual effective configuration. Do not mandate a particular operator's model, effort spelling, floor, ceiling, or routing profile.
  • Some Hermes interfaces resolve delegation.reasoning_effort before inherited parent effort but lack independent per-worker controls. Recheck after upgrades. Never change global settings during running jobs to imitate per-worker controls. If a required level cannot be supplied, disclose it rather than claiming compliance.
  • Precedent, retry, and lineage-budget rules remain workflow requirements, not necessarily runtime enforcement. Do not pass a custom precedent argument unless supported; keep task-class, strategy, reasoning, and evidence in the existing task record instead. A configured limit or role label is not proof of an enforcing runtime consumer.
  • Do not restore obsolete Python/runtime code to satisfy outdated API wording. Prefer supported configuration and accurate instructions; propose a narrowly scoped runtime change only for an essential unmet capability, with separate authority before mutation.

When to use

Use when one or more conditions hold:

  • the task has three or more meaningful phases;
  • many files, long logs, PDFs, webpages, or past sessions may be involved;
  • research, implementation, review, and verification must be coordinated;
  • independent subproblems can run in parallel;
  • raw tool output would crowd out synthesis;
  • the work may continue across sessions;
  • the user explicitly requests delegation or subagents.

Use lightly or skip for a quick lookup, a small local edit, one short file, or a deterministic operation whose orchestration overhead exceeds the work. Respect an explicit request not to delegate.

Context-budget preflight

Before heavy work, state a compact budget:

## Context budget
- Task size: small | medium | large | huge
- Parent role: execute | orchestrate | synthesize | verify
- Expected parent context cost: low | medium | high
- Bulk-output strategy: direct tools | deterministic reduction | subagent summaries | external ledger
- Delegation: none | one bounded child | parallel children | map-reduce
- Verification reserve: what must remain possible before finalization

Size heuristic

SizeTypical shapeDefault response
Smallno more than two sources/files and a few callsdirect work
Mediumseveral files/sources or commandsbatch reads; consider one bounded child
Largebroad research, test/build loops, many filesdelegate independent reasoning early
Hugerepository-wide, multi-phase, or multi-sessionexternal ledger plus map-reduce

Task shape matters more than raw file count. One enormous log may need containment more than ten tiny files.

Proportional phase gates

Treat the available interaction/call budget as a phase budget, not a target to consume.

Budget pointPhaseRequired behavior
first 10%Scope and routeLock endpoint, success criteria, source/tool matrix, delegation choice, and stop conditions.
10–60%Collect or implementBatch independent calls, dispatch required children early, write artifacts incrementally, and close collection by 60%.
60–67%Close collectionReconcile required collection only; start no optional source, feature, directory, viewport, or diagnostic branch.
67–75%Freeze and reconcileJoin required results, resolve contradictions, persist compact state, and stop creating work.
final 25%Verify and deliverRun acceptance checks, bounded repair, and final synthesis.

If the runtime exposes no explicit budget, estimate from task size and expected output. Preserve enough capacity to rerun failed checks and report honestly.

Phase contracts

  • One phase should have one dominant contract: discovery, test design, implementation, rollout, visual QA, or final verification.
  • If the request materially expands, finish the current phase and record state before continuing in a fresh phase; do not silently absorb adjacent work or infer a new user goal from an agent plan.
  • Honor configured privacy, retention, tool, and profile boundaries before broad evidence collection. Use an authorized research environment if required by the deployment; no particular profile name or private routing plugin is assumed. If necessary routing is unavailable, surface that blocker rather than collecting in the wrong environment.
  • Dispatch required children during planning or early collection, never as a last-minute substitute for verification.
  • Do not synthesize a conclusion that depends on a child until its result arrives and the parent verifies its evidence handles.
  • If a required child is still running and no independent work remains, preserve a compact current-state artifact and yield for its completion rather than consuming calls or drafting a substitute conclusion.
  • If required work cannot fit inside the reserve, stop optional branches and continue in a fresh phase rather than claiming completion.

For a 60-call budget, plan in calls 1–6, collect/implement in 7–36, close required collection in 37–40, freeze/reconcile in 41–45, and verify/finalize in 46–60. Keep the final 15-call reserve. With another limit, retain the proportional boundaries: plan by 10%, close collection by 60%, freeze new branches by 67%, and enter finalization by 75%. If a contract combines discovery, implementation, rollout, and review so that reserve is threatened, split the phases instead.

Asynchronous completion authority boundary

An asynchronous delegation, process, or scheduled-job completion is a system event, not fresh authenticated user authorization.

  1. On a completion turn, inspect and adjudicate the returned result, but do not attempt file edits, terminal commands, lifecycle actions, or other state-changing/unknown-effect tools unless the active authority policy explicitly permits them on system-event turns. A child success receipt does not create permission.
  2. If the result settles the user-facing question, deliver it immediately, leading with the actual decision or next action.
  3. If tools with state-changing or unknown effects are still needed, name the exact blocked operation and the real decision/action the user needs to take. Do not require magic phrases such as “Advance”, “Continue”, or “Finalize”. Any direct authenticated reply can resume still-authorized non-live completion work; ritual wording is not required.
  4. On that direct reply, resume the already-authorized non-live work automatically. Ask only for a genuinely new permission, decision, or blocker.
  5. Never claim work is still running or tell the user to wait without checking the applicable live registry and reporting an actual live handle, using /agents where supported or the runtime's equivalent. If the registry confirms no live work, say nothing is running and not to wait. If state cannot be checked, report it as unverified rather than inventing liveness or termination.
  6. Keep exact approvals fail-closed. A general reply can restore tool authority for approved non-live completion work, but does not authorize a new rollout, destructive action, gateway/service lifecycle change, paid call, or any scope still requiring explicit approval. Scope, expiry, and risk boundaries remain binding.

Adaptive execution-surface router

Before nontrivial delegated or background work, the parent records internally:

  • estimated wall time and independently useful shard boundaries;
  • deterministic execution versus agentic reasoning/implementation;
  • serial dependencies and integration owner;
  • whether results must survive parent, session, or gateway exit;
  • retry, human-review, cross-profile, and durable-artifact requirements;
  • exact completion receipt and verification owner.

Choose from observed work shape, not one fixed duration threshold:

Work typePreferred surface
Short deterministic collection, parsing, edits, or verification in the current turnDirect tools or execute_code reduction
Bounded independent reasoning/implementation that can rejoin the live parentdelegate_task where available; normally target 4–8 minutes with summary reserve
Long deterministic build, test, migration rehearsal, or batch command with a defined endTracked background process; where supported, terminal(background=true, notify_on_complete=true); parent verifies output/artifact
One long independent agent mission without dependency/retry/review lifecycle needsTracked background agent process with live handle and completion notification
Agentic work requiring restart survival, dependencies, safe retries, human-review waits, cross-session/profile continuation, or durable ownershipConfigured durable task system, such as Hermes Kanban where available, with stable idempotency key, bounded runtime/retries, explicit workspace class, artifacts, and verification owner
User decision with material trade-offsConcise decision brief and clarification

Do not assume a background handle proves restart durability. Verify each surface's actual lifetime, storage, isolation, and notification guarantees. No private task-system plugin is required, but a weaker process-local surface cannot replace required durable semantics. If no available authorized surface provides them, preserve the checkpoint and report the blocker rather than silently weakening the contract.

Flexible timeout routing

A timeout never selects a durable queue automatically. Complete the timeout postmortem and salvage first, then route only the failed remainder:

  1. Shrink or re-shard bounded children when work is independently acceptable, the parent can integrate it, each shard fits the live window, and parent loss would not destroy required durable state.
  2. Move only the irreducible or lifecycle-heavy chunk to durable work when dependencies, retries, human review, cross-session/profile continuation, or persistent ownership require it.
  3. Move deterministic long execution to a tracked background process rather than spending agent wall time waiting for scripts, builds, or tests.
  4. Use a tracked background agent only for an independent one-shot mission; use durable task ownership when dependency, retry, review, or handoff state matters.
  5. Mix surfaces within the same DAG when useful: bounded reasoning children, durable implementation workers, and background deterministic verification.

Do not migrate the whole project because one shard timed out. Conversely, do not keep subdividing a tightly shared-state remainder that cannot be independently accepted or repeatedly saturates bounded children; that is evidence for a durable worker. Record the evidenced causal sentence and selected surface in the retry DAG.

Do not spawn agents merely to move mechanical output elsewhere. Prefer search_files, line-limited read_file, and execute_code filtering to raw output dumps. Deterministic scanning, counting, parsing, aggregation, and formatting belong in tools; judgment belongs in parent or child reasoning. Use only tools present in the runtime.

Delegation decision rules

Delegate when a subtask is independent, bulky, or benefits from fresh context. Keep it in the parent when tight coordination, user interaction, or a small local change makes delegation slower or less reliable.

Good targets:

  • codebase reconnaissance with file/line handles;
  • parallel evidence collection across distinct source classes;
  • independent design alternatives under identical constraints;
  • diff or plan review after an artifact exists;
  • isolated failure triage;
  • long-document synthesis;
  • adversarial verification of a material claim.

Poor targets:

  • one command or simple lookup;
  • tiny edits;
  • tasks requiring user clarification;
  • durable work that must survive the current session;
  • external side effects the parent cannot independently verify.

Reasoning effort

Check the actual runtime before choosing effort. Use the lowest supported, authorized effort that can reliably satisfy the contract, respecting configured quality floors and ceilings. Routine narrow collection, checking, comparison, and implementation need less reasoning than diagnosis, architecture, review, evidence synthesis, or high-stakes reconciliation. Use the configured orchestration model and quality level; this package prescribes no model name or mandatory effort label.

After failed verification, material uncertainty, conflicting evidence, missed constraints, or substantial repair, reassess scope and evidence first. Raise effort only through a supported control and when warranted. If no such control exists or effort is already at its ceiling, report the limitation and change scope/topology causally instead of claiming a fictitious escalation. Shared configured effort may apply to every worker; report that honestly. Custom minimum/maximum settings do not prove runtime clamping unless a consumer enforces them.

Mechanical work belongs in tools, not a low-effort reasoning child. High effort is never a substitute for a clear endpoint, lean context, or verification.

Automatic containment and explicit delegation

For automatic containment, delegate before long files, pages, papers, or logs flood the parent, but only within existing delegation/provider permission. When context_pct is exposed, begin containment roughly 10–15 percentage points before the configured compression threshold; otherwise use task-size and expected-output heuristics. At high pressure, stop broad reads, update the compact ledger, and delegate remaining independent analysis. Compression is the backstop, not the main strategy. An explicit “do not delegate” wins: use filtering, ledger state, and compression instead. Automatic containment neither authorizes a paid external reviewer nor requires maximum effort.

For an explicit delegation request, give a bounded orchestrator the endpoint, parent-written DAG when required, constraints, evidence standard, tool boundaries, and concise output contract. Use an orchestrator role only if advertised and honored; otherwise keep coordination in the parent with supported bounded leaves and disclose the limitation. No model or global configuration change is implicit. The orchestrator may use zero, one, or multiple workers where runtime permissions allow; do not force fan-out for one coherent analysis, and do not use zero workers to evade sizing gates. The parent verifies important evidence and side effects and owns final delivery.

Standard subagent contract

Every delegated task should include:

  • Goal: accepted user outcome, current blocker, this shard's contribution, and exact deliverable; a child deliverable is not whole-project completion.
  • Context: needed original evidence, actual interfaces, constraints, preserved successes, and acceptance criteria.
  • Boundaries: what not to modify, assume, or contact.
  • Output schema: concise result with verifiable handles.
  • Budget: exact input scope, expected calls, target wall time, stop conditions, concise word cap, and no raw logs/transcript unless essential.

Recommended response:

## Result
<one to three sentences>

## Evidence / handles
- <file and line range, URL, command, test, artifact, or ID>

## Key details
- <up to five bullets>

## Risks / uncertainty
- <remaining uncertainty>

## Suggested next step
- <one action>

For implementations and reviews, require files touched or inspected, tests run or recommended, exact blockers, and no success claim without a handle the parent can verify.

Parent verification gate

A subagent summary is a lead, not proof. Before reporting completion, the parent must verify material claims and external side effects against the original surface:

  • read back changed files;
  • inspect diffs;
  • run tests/builds/validators;
  • fetch published URLs;
  • compare identifiers or bytes where appropriate;
  • distinguish “reported by child” from “verified by parent.”

The parent owns the final synthesis and decision.

Circuit breakers

  • The causal retry embargo applies first: there is no free blind retry. A same-surface retry needs new evidence and a materially different, cause-removing hypothesis. After at most one such retry on a failed GUI, API, browser, or command surface, switch surface unless an additional attempt has independently evidenced causal justification and remains within budget and authority.
  • After that, switch surface: DOM/accessibility/direct file/API before more coordinate clicking; deterministic probes before visual guesses; exported data before private-history pagination.
  • Submit one coherent task to an external coding application, then observe through accessibility or terminal evidence rather than repeatedly refocusing or resubmitting it.
  • For bounded background processes, use completion notification rather than polling when available; in Hermes use notify_on_complete=true where supported. Poll only long-lived services or when the user explicitly asks for live progress and no completion notification exists. If the runtime has no notifications, declare a bounded completion-check strategy rather than a busy polling loop.
  • Batch screenshots, viewport checks, and console inspection into one verification pass per implemented state.
  • Stop broad collection when outputs repeat, contradict without new evidence, or no longer change the decision.

Hard first-attempt sizing and retry embargo

Optimize for one robust run rather than repeated cheap attempts. When elapsed time matters more than token economy, spend the necessary reasoning budget in the first attempt through deterministic reduction and independently completable parallel shards.

Mandatory first-attempt sizing record

Before every nontrivial delegation, record internally:

  • the number and total expected bytes of named input artifacts;
  • the number of independent reasoning domains;
  • expected tool or API calls;
  • serial dependencies;
  • target wall time per shard;
  • deterministic work that should remain in the parent or a programmatic tool.

A single reasoning child is admissible only when all of these are true:

  • the task has one reasoning domain;
  • it names no more than four input artifacts;
  • total expected input is no more than 100 KiB;
  • it requires no repository-wide or full-tree search;
  • it expects no more than eight tool or API calls;
  • it does not combine discovery, derivation, and review in one worker.

Crossing any threshold requires a parent-written task DAG and either direct parallel children or a bounded orchestrator. Keep every shard independently completable and target roughly four to eight minutes per reasoning shard.

Material expansion invalidates strategy reuse

A previously successful strategy applies only to materially comparable scope. Do not reuse it unchanged when:

  • a new reasoning domain is added;
  • named artifacts or expected bytes grow by more than twofold;
  • discovery expands into derivation, implementation, or adversarial review;
  • a second independent verdict is required;
  • expected calls cross the single-child ceiling.

When strategy or precedent identifiers are available, material expansion requires a new task class or an explicitly scope-qualified strategy. A pass on a smaller task does not validate the same topology for a larger one.

First-run resource preference

When the user prioritizes elapsed time over token economy:

  • reduce deterministic inputs before delegation;
  • dispatch every independent required shard in the first attempt;
  • use higher reasoning effort for review or architecture and reserve the highest permitted effort for a decisive shard whose complexity or failed verification warrants it;
  • give every shard exact artifacts, output schema, stop conditions, and a word cap;
  • preserve sibling results independently so one timeout cannot hide them;
  • prefer one bounded, adequately resourced fan-out over serial trial and error.

Retry embargo and acceptance test

After any timeout, do not dispatch another attempt until all are true:

  • the prior handle is verified no longer live;
  • available call count, timeline, partial output, and kill condition are inspected;
  • useful artifacts and sibling results are salvaged;
  • the cause is classified;
  • a compact postmortem and revised task DAG exist;
  • the new attempt changes scope or topology in a way that addresses the classified cause.

For that task, quarantine the timed-out combination of strategy identifier, worker count, serial-dependency structure, and materially equivalent contract. Reusing a worker count with a genuinely narrower, causally changed contract is not reuse of the same failed topology. More effort or a longer prompt alone is not a topology change.

Before retrying, the parent must be able to support this sentence with evidence:

The previous attempt failed because <classified cause>; this attempt removes that cause by <material DAG or topology change>.

If the sentence cannot be supported, do not retry.

Timeout and exhaustion postmortem

A timeout or exhausted budget is diagnostic evidence, not permission to retry the same topology with more effort or a longer wall clock. Apply the sizing and retry embargo above, then use this diagnostic workflow.

  1. Stop and inspect. Verify that the previous worker or process is no longer live. Inspect the parent and child timelines, actual fan-out, longest tool or model calls, context growth, partial outputs, and the exact timeout or exhaustion condition. Keep this forensic pass bounded; use the most recent relevant logs and session records rather than a broad history investigation.
  2. Salvage completed work. Preserve useful sibling results, artifacts, tests, and evidence handles. One failed shard does not invalidate successful independent work.
  3. Classify the cause. Distinguish oversized scope, serial dependency, unbounded collection, external latency, deterministic test duration, provider failure, and a genuine concurrency or call-budget cap. Do not blame a concurrency cap when fewer than the allowed workers were dispatched.
  4. Parent writes the retry DAG. Before another orchestrated attempt, define bounded shards, dependencies, exact source or file scopes, output contracts, stop conditions, and verification owners. An orchestrator receives this plan; it is neither a dumping ground for the whole project nor a substitute for parent audit.
  5. Retry only incomplete shards. Prefer independently completable fan-out so one timeout cannot hide or cancel successful siblings. Avoid broad repository-wide inventories, wildcard searches, or full-tree byte comparisons unless the parent explicitly justifies and bounds them.
  6. Use orchestrators for coordination. Supply the task DAG, existing evidence, contradictions, and bounded decisions. Do not place discovery, implementation, testing, and review serially behind one worker deadline.
  7. Separate execution surfaces. Assign one implementation owner per overlapping file cluster; use deterministic tools for builds and tests; freeze the artifact before independent review.
  8. Audit the actual topology. Compare requested versus dispatched workers, require evidence handles and literal verdicts, verify writes, tests, and hashes at the parent, and treat omitted or unverified work as blockers.
  9. Escalate surgically. Raise effort or narrow the contract only for the failed shard. Increase global timeout, concurrency, or budget only when the postmortem shows that resource limit was causal.

Never treat silence, an absent result, a timeout notice, or an exhaustion summary as success. Record the repaired topology in the project ledger when the same task class may recur.

At branch-freeze or finalization, if the remaining criteria cannot fit in the reserve: stop optional collection and GUI exploration; preserve current artifacts, evidence handles, failed checks, and next action in the existing state record; report the bounded blocker or continue in a fresh authorized phase. Never claim completion from a maximum-iteration fallback summary.

Outcome-led execution

Apply these portable governance principles before choosing topology. All safety, admission, sizing, retry, and verification requirements remain binding.

  • Keep the accepted user outcome, current blocker, and subtask contribution in the existing contract. Propagate user-approved goal changes; an agent-created plan is not a new user goal.
  • The parent owns necessity and causal diagnosis. For repairs, give the author the actual failing operation, evidence, and matching interfaces. Use a scout only for genuinely missing facts, not as an automatic extra phase. Review whether an implementation is needed before reviewing its correctness.
  • Supporting work must remove a concrete blocker or establish a required safety property that existing tools/evidence cannot establish. If accessory work starts generating more accessory work, reconsider the route before adding another layer. Infrastructure is appropriate when it is the requested outcome, not a substitute for it.
  • Complete useful authorized work to a meaningful checkpoint. Do not turn routine reads, individual tests, or internal callbacks into separate human decisions. Consolidate necessary approvals without changing their exact scope, expiry, or risk boundaries; new authority still needs approval. This does not override the asynchronous-completion authority boundary.
  • Judge progress by resolved user-outcome blockers and real acceptance evidence. Reuse valid successes and recheck affected facts after changes. A completed pass is not a new launch and is not discarded merely because an old launch permission expired. Never relabel evidence to satisfy a different contract or treat past success as authority for a new run.
  • If no useful authorized action can advance the outcome, surface the actual blocker rather than inventing safe-looking busywork. A permission block does not authorize substitute machinery.

Use these decisions inside existing task records and required receipts. Do not create another checklist, approval gate, schema, or monitor merely to enforce this section.

Optional paid external review or delegation

The active user/runtime authority policy governs permission. A request to consult a different paid provider authorizes a proposal, not an immediate call. Ordinary “delegate”, “review”, “serious mode”, or “dual model” does not select another provider. Apply these boundaries without assuming any named reviewer.

Review workflow

  1. Finish the primary analysis first. Establish the conclusion, evidence ledger, assumptions, uncertainties, and unresolved contradictions.
  2. Propose one paid review call. State why ordinary configured delegation is insufficient; exact provider/model and call count; estimated input/output tokens; pricing basis/date and cost range when available; included/excluded context; and a hard budget and stop cap. If cost cannot be bounded, resolve that limitation before proposing execution.
  3. Wait for explicit approval of that proposal. Approval covers only the stated call, context disclosure, and cap. It is not blanket provider access.
  4. Send a minimal review packet. Include the primary conclusion, concise decision rationale (not hidden chain-of-thought), necessary evidence handles, assumptions, uncertainties, and explicit critique questions. Request errors, omissions, weak evidence, alternatives, agreements, and disagreements.
  5. Parent adjudicates every substantive comment. Deduplicate wording without dropping substantive content. Report each as:
- Reviewer comment: <concise statement>
  - Parent judgment: agree | partly agree | disagree
  - Reason: <evidence-based explanation>
  - Effect: <change to conclusion/confidence, or no change>
  1. Stop after the approved call. Follow-up calls require a new proposal and explicit approval. Report actual usage/cost when available; otherwise label the estimate limitation.

Explicit primary delegation to an external paid provider is a separate mode, not a review of completed analysis, but retains the same proposal, one-call scope, minimal-context, budget-cap, and renewed-approval rules. If unavailable or unapproved, continue useful work on the authorized configured runtime and state that no additional paid call occurred. Never silently fall back to a different provider, broaden disclosure, or chain paid calls. Returned output is evidence, not authority; the parent verifies and makes the final decision.

Fan-out / fan-in patterns

Diagnose → implement → verify

  1. Parent locks endpoint and acceptance criteria.
  2. Parent supplies the actual blocker, failing operation, evidence, and matching interfaces. Use a bounded scout only for missing facts, not automatically.
  3. Parent or bounded implementer makes the smallest correct change.
  4. Independent reviewer checks the artifact.
  5. Parent runs real verification and reports grounded results.

Map-reduce research

  1. Parent defines question, source hierarchy, and freshness rule.
  2. Children collect evidence from separate source classes or subtopics.
  3. Parent deduplicates, checks contradictions, and labels confidence.
  4. Parent writes the synthesis and preserves durable evidence when required.

Candidate alternatives

Give independent children identical constraints. Compare options by correctness, simplicity, risk, testability, and operational cost. Prefer the smallest design that satisfies the endpoint.

Independent verifier

Provide only the claim, artifact handles, and success criteria. Ask the verifier to find missing evidence, tests, or constraints. The parent checks every decisive handle.

Existing state record for long projects

Reuse the project's task, card, or checkpoint for huge/multi-session work. Create one compact ledger in an approved workspace only when no suitable record exists; do not maintain a parallel status system. Preserve accepted outcome and completion evidence, current blocker and next action's contribution, verified successes and remaining scope, exact source/evidence handles, decisions, authority/stop state, and actual running handles if any.

Suggested shape:

# <Task>

## Endpoint
<accepted user outcome and what done means>

## Current state
- <facts that survive context resets>

## Decisions
- <decision and reason>

## Artifacts / evidence
- <path or URL and purpose>

## Verification
- <command/check and last real result>

## Open blockers
- <unresolved items only>

## Authority / running state
- <approval scope, expiry, stop state, verified live handle or no live work>

## Next action
- <one action and its contribution to the accepted outcome>

Keep the ledger short and raw logs behind handles. On recovery, resolve conflicts against original artifacts and the latest user instruction. A completed child or an expired old launch receipt neither redefines the goal nor erases valid completed evidence. This is recovery state, not a transcript.

Context-pressure recovery

When the parent starts repeating calls, losing constraints, or depending on memory of a long transcript:

  1. stop broad reading and optional branches;
  2. finish or safely pause the current phase;
  3. update the state ledger;
  4. delegate only isolated missing facts;
  5. resume from the ledger in a fresh phase or allow compression as a backstop;
  6. never turn a fallback summary into an unverified completion claim.

Common pitfalls

  1. Over-delegation: children add latency and noise to tiny tasks.
  2. Under-delegation: broad raw reading destroys parent context quality.
  3. Late delegation: required results arrive after the verification window.
  4. Raw-summary bloat: bounded tasks still need concise output contracts.
  5. Unverified side effects: child reports do not prove publication or mutation.
  6. Transcript as database: durable projects need external recovery state.
  7. Maximal effort everywhere: expensive reasoning does not repair unclear scope.
  8. Retry loops: repeated use of a failed surface without new evidence is not progress.
  9. Optional-branch creep: collection expands until no verification reserve remains.
  10. Permission drift: methodology does not grant provider, payment, or external-action authority.
  11. Precedent overreach: a topology that passed for a small task is not evidence that it fits materially expanded scope.
  12. Fictitious runtime controls: instructions, unsupported role/effort fields, or configured limits do not prove enforcement. Do not mutate global settings during jobs to mimic independent worker controls.
  13. Timeout-driven overmigration: salvage siblings and route only the failed remainder; a timeout alone does not select a durable queue.
  14. Async authority drift: completion is not a new user instruction or a rollout/payment approval; report exact blockers without magic phrases.
  15. Outcome loss: expired launch authority does not erase valid passes, and accessory work must not replace the accepted user outcome.
  16. Receipt overclaim: a validator PASS checks supplied structure, not truth, hashes, containment, complete cost-ladder coverage, or permission.
  17. Review comment loss: deduplicate wording without dropping substantive agreement or disagreement; stop at the approved call count.

Verification checklist

  • Endpoint, success criteria, stop conditions, and reserve were stated before heavy work.
  • Deterministic bulk output was reduced to decision-relevant summaries before parent synthesis.
  • Required independent reasoning was delegated early with bounded contracts.
  • User and runtime delegation/provider limits were respected.
  • Only advertised APIs were used, effective model/effort and enforcement limitations were reported, and no global settings changed to mimic per-worker controls.
  • Costly tiers followed the declared cost ladder; required receipts were validated without treating their PASS as evidence or execution authority.
  • First failures preserved complete safe machine-readable evidence and measured recovery; every retry had an evidenced causal change.
  • Every nontrivial delegation was sized before dispatch; single-child work stayed within all ceilings or used a parent-written DAG.
  • Same-surface retries were capped and switched after failure.
  • Every timeout retry passed the embargo and changed topology or scope to remove the classified cause.
  • Required child results arrived before synthesis.
  • Async results were treated as system events, exact approvals stayed fail-closed, and running claims had verified live handles.
  • Material claims and side effects were verified by the parent.
  • New branches froze before the final verification phase.
  • Work requiring durability used a surface with verified lifecycle guarantees; timeouts salvaged successes before routing the remainder.
  • Huge or multi-session work reused a compact existing state record, or created one only when none existed.
  • Valid successes, accepted outcome, original evidence, and authority/stop state survived recovery without unnecessary accessory machinery.
  • Any optional paid review followed an approved costed one-call proposal, minimal disclosure, complete comment adjudication, and stop cap.
  • Final claims cite tool output, files, URLs, tests, or user-provided evidence.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.