diff --git a/README.md b/README.md index 73dd241..fae5989 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,10 @@ 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, 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, diff --git a/SKILL.md b/SKILL.md index 27aacf7..784f527 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,37 @@ 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 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. +- **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.** 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, or a parent reviewing its child, is not independent. + +## 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 +159,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 +170,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 +182,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..17a395f 100644 --- a/references/quality-gates.md +++ b/references/quality-gates.md @@ -47,3 +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 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 94c523f..dbb21fd 100644 --- a/references/report-template.md +++ b/references/report-template.md @@ -23,6 +23,10 @@ Findings: Operations (High-risk only): - Migration; rollout; rollback; observability +Delegation (if used): +- 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 ```