From 63ef11b118b3029760d00d20b4f984ba77d35aee Mon Sep 17 00:00:00 2001 From: elkaix Date: Tue, 10 Nov 2026 23:22:53 -0500 Subject: [PATCH 1/3] Add delegation and fan-out guidance Fan out only for independent read-only slices, keep one code writer, brief every worker with scope and output contract, bound width, and treat worker returns as evidence rather than verdicts. Mirror the rule in the README, quality gates, and report template. --- README.md | 3 +++ SKILL.md | 47 +++++++++++++++++++++++++---------- references/quality-gates.md | 2 ++ references/report-template.md | 3 +++ 4 files changed, 42 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 73dd241..90ad2f0 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,9 @@ the risk, and an honest `COMPLETE` / `PARTIAL` / `BLOCKED` report. coherent slice, then verify. A failure is sorted as an implementation defect, a bad assumption, an environment problem, or an ambiguous contract, and the agent loops back to the matching step. +- **Delegation, with one writer.** Fan out only for independent, read-only slices; brief each + worker with an objective, scope, output contract, and budget; treat returns as evidence, + not verdicts, and keep synthesis in the parent. - **Evidence scaled to risk.** Pre-fix evidence, recorded commands, and independent review scale with the mode. A skipped or unavailable check never counts as a pass. - **Design rules.** Seven rule groups for the code the agent writes (ownership, boundaries, diff --git a/SKILL.md b/SKILL.md index 27aacf7..0a5387d 100644 --- a/SKILL.md +++ b/SKILL.md @@ -56,7 +56,7 @@ deterministic reproducer or directly observed failure. Never fabricate a red run **Implement.** Fix the invariant at the smallest correct shared layer. Infer architecture from the code and reuse its conventions and helpers; do not impose patterns because they -are familiar, and apply the design rules in section 3 to the code you add. Wire every +are familiar, and apply the design rules in section 4 to the code you add. Wire every required path: unused helpers and fake success paths are not delivery. Validate untrusted input at boundaries and make failure explicit; never swallow errors, fabricate data, or weaken authorization. Preserve compatibility unless the change @@ -79,15 +79,36 @@ cannot establish intended behavior, keep both and report the ambiguity. **Review.** Read the final diff and status as a domain engineer: boundaries, failure paths, security, concurrency, compatibility, resources. Remove debug artifacts, dead code, and unrelated formatting. For High-risk work, request an independent read-only review scoped to -correctness when available, without blocking required work; its absence is a reported -limitation, not by itself a reason for `PARTIAL`. Self-review, including of a child agent's -work, is not independent. Rerun affected checks after the last relevant edit; an old green -run does not verify a new tree. When available, load -[quality gates](references/quality-gates.md) only for affected domains, and for Substantial -work and above answer its review questions against the final diff; if a reference is -missing, use this protocol and note it only when it materially reduces verification. - -## 3. Design +correctness per section 3 when available, without blocking required work; its absence is a +reported limitation, not by itself a reason for `PARTIAL`. Rerun affected checks after the +last relevant edit; an old green run does not verify a new tree. When available, load +[quality gates](references/quality-gates.md) for affected domains; for Substantial work and +above also answer its review questions against the final diff; if a reference is missing, +use this protocol and note it only when it materially reduces verification. + +## 3. Delegation + +Fan out across multiple workers only for independent, read-only slices whose value justifies +roughly an order of magnitude more tokens than one agent. Keep the parent as the sole code +writer; do not dispatch parallel writers. Split research by sub-question, not by source; +simple or sequential work stays in the main thread. + +- **Brief before dispatch.** Give each worker an objective, output contract, owned scope, + sources or tools, budget, and stop condition; dispatch after acceptance criteria are fixed. +- **Return evidence, not verdicts.** Require `file:line` or a source URL with date, the + command and observed output, and what was not checked. "Done" is a claim, not a pass. +- **Keep context clean.** Workers write detail to a scratch file outside tracked sources and + return a short summary plus its path, not a transcript; or return concise evidence directly. +- **Bound the fan-out.** Start with 2–4 workers, give each a distinct slice, set per-worker + timeouts, and do not spawn follow-up exploratory batches when returns diminish. +- **Synthesize centrally.** Deduplicate, reconcile conflicting observations by evidence + strength (reproduced > read > claimed); contracts govern intended behavior. Preserve + dissent and keep the decision in the parent. +- **Review independently.** A reviewer gets the diff, acceptance criteria, and contracts, + not the author's reasoning. An author cannot review their own diff, and a parent cannot + independently review its child's work. + +## 4. Design Rules for the code you write, applied within the repository's own structure. The test for every addition: am I adding code, or a new place future readers must understand? @@ -137,7 +158,7 @@ When rules conflict: correctness → explicit invariants → clear ownership → effects → bounded resources → failure safety → locality → replaceability → extensibility → optimization. -## 4. Safety +## 5. Safety - Stay inside the workspace and task scope. Never print environment values, credentials, or secret files; check a variable's presence, not its value. @@ -148,7 +169,7 @@ optimization. - Commit, push, open a PR, merge, and deploy are separate permissions. When committing, stage exact paths and inspect the staged diff. -## 5. Findings and evidence +## 6. Findings and evidence Record material defects you discover as you go. Interrupt only when one changes scope, safety, strategy, or completion status; otherwise list it in the report with a next action. @@ -160,7 +181,7 @@ Keep enough evidence to reproduce each material claim. For performance, migratio security, or environment-dependent results, record exact commands, environment, and revision. Report only results you observed. -## 6. Report +## 7. Report | Status | Meaning | | --- | --- | diff --git a/references/quality-gates.md b/references/quality-gates.md index a29fee9..fdb52a3 100644 --- a/references/quality-gates.md +++ b/references/quality-gates.md @@ -47,3 +47,5 @@ For Substantial work and above, answer each against the final diff: 9. Do tests protect behavior rather than implementation details? 10. Is the complexity justified by a real requirement, and would another engineer know where to modify this behavior six months from now? +11. If work was delegated, does the report name each worker's scope, what it actually + read, and which delegated claims remain unverified? diff --git a/references/report-template.md b/references/report-template.md index 94c523f..b921f6d 100644 --- a/references/report-template.md +++ b/references/report-template.md @@ -23,6 +23,9 @@ Findings: Operations (High-risk only): - Migration; rollout; rollback; observability +Delegation (if used): +- Worker -> scope -> read/not read; claims verified or still unverified + Limits: - Unknowns, unavailable checks or reviews, pre-existing failures, remaining work ``` From 250adfbf40f17fbeeb14c20fe3872211677d4019 Mon Sep 17 00:00:00 2001 From: elkaix Date: Tue, 10 Nov 2026 23:42:25 -0500 Subject: [PATCH 2/3] Harden delegated work failure handling Fail closed on worker timeout, failure, partial or malformed output; pin revision and working-tree state; bound total budget with an exhaustion action; report failed or unrun slices as gaps; capture slice status, evidence, and coverage in the report template. --- README.md | 2 +- SKILL.md | 17 +++++++++-------- references/quality-gates.md | 5 +++-- references/report-template.md | 3 ++- 4 files changed, 15 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 90ad2f0..8be2cad 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ the risk, and an honest `COMPLETE` / `PARTIAL` / `BLOCKED` report. to the matching step. - **Delegation, with one writer.** Fan out only for independent, read-only slices; brief each worker with an objective, scope, output contract, and budget; treat returns as evidence, - not verdicts, and keep synthesis in the parent. + not verdicts, report failed or unrun slices as gaps, and keep synthesis in the parent. - **Evidence scaled to risk.** Pre-fix evidence, recorded commands, and independent review scale with the mode. A skipped or unavailable check never counts as a pass. - **Design rules.** Seven rule groups for the code the agent writes (ownership, boundaries, diff --git a/SKILL.md b/SKILL.md index 0a5387d..784f527 100644 --- a/SKILL.md +++ b/SKILL.md @@ -88,10 +88,9 @@ use this protocol and note it only when it materially reduces verification. ## 3. Delegation -Fan out across multiple workers only for independent, read-only slices whose value justifies -roughly an order of magnitude more tokens than one agent. Keep the parent as the sole code -writer; do not dispatch parallel writers. Split research by sub-question, not by source; -simple or sequential work stays in the main thread. +Fan out only for independent, read-only slices whose value justifies roughly an order of +magnitude more tokens than one agent. The parent is the sole code writer; never dispatch +parallel writers. Split research by sub-question, not by source. - **Brief before dispatch.** Give each worker an objective, output contract, owned scope, sources or tools, budget, and stop condition; dispatch after acceptance criteria are fixed. @@ -99,14 +98,16 @@ simple or sequential work stays in the main thread. command and observed output, and what was not checked. "Done" is a claim, not a pass. - **Keep context clean.** Workers write detail to a scratch file outside tracked sources and return a short summary plus its path, not a transcript; or return concise evidence directly. -- **Bound the fan-out.** Start with 2–4 workers, give each a distinct slice, set per-worker - timeouts, and do not spawn follow-up exploratory batches when returns diminish. +- **Bound the fan-out.** Dispatch 2–4 workers with distinct slices, per-worker timeouts, + and a total token/time budget; stop dispatch and cancel active workers on exhaustion. +- **Fail closed.** Pin revision and working-tree state; discard returns if either changes. + A worker that times out, fails, or returns partial or malformed output is unverified; + retry once only for transient host/network errors. Report failed or unrun slices as gaps. - **Synthesize centrally.** Deduplicate, reconcile conflicting observations by evidence strength (reproduced > read > claimed); contracts govern intended behavior. Preserve dissent and keep the decision in the parent. - **Review independently.** A reviewer gets the diff, acceptance criteria, and contracts, - not the author's reasoning. An author cannot review their own diff, and a parent cannot - independently review its child's work. + not the author's reasoning; an author, or a parent reviewing its child, is not independent. ## 4. Design diff --git a/references/quality-gates.md b/references/quality-gates.md index fdb52a3..17a395f 100644 --- a/references/quality-gates.md +++ b/references/quality-gates.md @@ -47,5 +47,6 @@ For Substantial work and above, answer each against the final diff: 9. Do tests protect behavior rather than implementation details? 10. Is the complexity justified by a real requirement, and would another engineer know where to modify this behavior six months from now? -11. If work was delegated, does the report name each worker's scope, what it actually - read, and which delegated claims remain unverified? +11. If work was delegated, does the report name each slice's scope, revision, evidence, + read/not-read coverage, status, and which claims remain unverified, and does an + in-scope gap block `COMPLETE`? diff --git a/references/report-template.md b/references/report-template.md index b921f6d..dbb21fd 100644 --- a/references/report-template.md +++ b/references/report-template.md @@ -24,7 +24,8 @@ Operations (High-risk only): - Migration; rollout; rollback; observability Delegation (if used): -- Worker -> scope -> read/not read; claims verified or still unverified +- Slice -> worker -> revision (clean/dirty) -> evidence path -> read/not read + Status: DONE/FAILED/TIMED_OUT/UNRUN; claims: verified/unverified Limits: - Unknowns, unavailable checks or reviews, pre-existing failures, remaining work From adce6dbcfaafc1c1bb68395b4e958847c45ad104 Mon Sep 17 00:00:00 2001 From: elkaix Date: Tue, 10 Nov 2026 23:43:02 -0500 Subject: [PATCH 3/3] Mirror delegation timeouts and review boundaries in README --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8be2cad..fae5989 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,9 @@ the risk, and an honest `COMPLETE` / `PARTIAL` / `BLOCKED` report. assumption, an environment problem, or an ambiguous contract, and the agent loops back to the matching step. - **Delegation, with one writer.** Fan out only for independent, read-only slices; brief each - worker with an objective, scope, output contract, and budget; treat returns as evidence, - not verdicts, report failed or unrun slices as gaps, and keep synthesis in the parent. + worker with an objective, scope, output contract, budget, and timeout; treat returns as + evidence, not verdicts; report failed or unrun slices as gaps; review independently and + keep synthesis in the parent. - **Evidence scaled to risk.** Pre-fix evidence, recorded commands, and independent review scale with the mode. A skipped or unavailable check never counts as a pass. - **Design rules.** Seven rule groups for the code the agent writes (ownership, boundaries,