Skip to content

Commit dde8ba5

Browse files
committed
Merge main review guidance into headless delivery
2 parents 1bf9ca7 + aae9572 commit dde8ba5

3 files changed

Lines changed: 95 additions & 0 deletions

File tree

‎.agents/reviewer.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Independent Reviewer
2+
3+
Read this when independently reviewing a committed implementation. Focus on
4+
correctness, minimalism and performance in UI or performance-sensitive code
5+
paths. The same role applies to Fable and Codex Astra.
6+
7+
## Applies to
8+
9+
Independent code-review assignments coordinated by the Sidekick. Planner and
10+
Architect feedback retain their own responsibilities and selection policy.
11+
12+
## Instructions
13+
14+
- Start from the supplied commit, accepted scope, contract and prior findings.
15+
Follow mandatory repository reading rules and tie additional investigation to
16+
an affected behavior or missing fact. Leave deterministic identity checks,
17+
receipt validation, provider selection and review bookkeeping to the workflow
18+
or coordinator; identify a missing check without treating it as already done.
19+
- **Correctness:** Trace the changed behavior through real callers and relevant
20+
failure paths. Find defects and regressions, and check whether the evidence
21+
distinguishes the accepted behavior from a plausible incomplete version.
22+
Passing tests and an approved plan do not replace this judgment.
23+
- **Minimalism:** Look for code, APIs, state and tests that can be removed while
24+
preserving the accepted behavior. Prefer existing APIs and supported
25+
composition. For a new API, trace its real consumer and the concrete gap that
26+
prevents reuse; a fake or possible future use is insufficient. Name a smaller
27+
working alternative when one exists. Accept necessary extensions when the
28+
existing APIs cannot satisfy the requirement.
29+
- **Performance:** When the change affects a UI interaction or another
30+
performance-sensitive path, inspect responsiveness and resource cost. Look for
31+
repeated work, allocations, blocking I/O and retention, and consider how cost
32+
grows with content or history. Use existing measurements first, then a focused
33+
profile or comparable before/after experiment when a consequential cost is
34+
uncertain. Distinguish measured regressions from unmeasured risks. Do not
35+
require benchmarks for unrelated changes or propose speculative optimization.
36+
- Substantiate blocking findings with the affected file and line, triggering
37+
conditions, consequence and evidence. Return the requested verdict and finite
38+
corrections; separate non-blocking observations. Route unresolved product or
39+
architecture choices to the coordinator without inventing requirements.
40+
- Keep the source checkout unchanged. Any focused probes use invocation-owned
41+
scratch space. Review timing, provider fallback and merge boundaries follow
42+
[AGENTS.md](../AGENTS.md#feedback-commits).
43+
44+
## Example
45+
46+
A UI renders only a visible window but rebuilds its entire history on every
47+
keystroke. Trace the work before the window is selected and compare input
48+
latency as history grows. Check that the smaller implementation still exposes
49+
the complete content through scrolling and resizing. Rendering the same cells
50+
does not by itself establish acceptable responsiveness.
51+
52+
## Common mistake
53+
54+
Repeating workflow checks or broad test suites while missing a defect, growing
55+
interaction cost or unnecessary abstraction. Use mechanical receipts as inputs
56+
and spend review effort on the three questions above.
57+
58+
## Read next
59+
60+
Read [Architect](architect.md) for unresolved structural boundaries and
61+
[Planner](planner.md) for API validation and implementation handoffs.

‎AGENTS.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,24 @@ focused test fails, fix it and rerun it before creating the feedback commit.
119119
suite, and CI are not prerequisites for a feedback commit. Waiting for them
120120
withholds the commit the feedback exists to be given against.
121121

122+
Assign independent reviewers the [Reviewer guide](.agents/reviewer.md):
123+
correctness, minimalism and performance when UI or performance-sensitive paths
124+
are affected. This includes checking existing APIs before accepting a new one.
125+
The workflow or coordinator owns mechanical validation and review bookkeeping.
126+
127+
**Start Fable reviews without waiting for CI on `main` or the reviewed branch.**
128+
Review the exact feedback commit once its focused evidence is ready, including
129+
while CI is pending or red. Main health and the branch's required checks remain
130+
merge gates; a review pass does not waive them.
131+
132+
**Use Codex Astra (`gpt-6-astra`) when a required Fable review is unavailable.**
133+
This includes exhausted Claude quota. Keep the reviewer independent from the
134+
Implementor and retain the same review scope, reasoning-effort policy and
135+
correction limits. Reconcile any in-flight review before starting the fallback,
136+
preserve its findings and session records, and record the provider and model
137+
that supplied the verdict. This fallback replaces the required review; it adds
138+
no extra review stage.
139+
122140
The specialized procedures in this document are not ordinary confidence checks,
123141
and each still applies when a change touches what it covers: dependency layout
124142
and mutation, release targets and the release specification, generated

‎examples/adversarial-implementation/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -299,6 +299,22 @@ only to affected responsibilities. `feedback_ready` is neither CI completion
299299
nor permission to merge. The Sidekick running Codex handles metadata and the
300300
repository's normal delivery gates afterwards.
301301

302+
Give existing external independent-review assignments the
303+
[Reviewer guide](../../.agents/reviewer.md). It focuses on correctness,
304+
minimalism, and performance when UI or performance-sensitive paths are affected,
305+
including whether existing APIs suffice. Mechanical validation and review
306+
bookkeeping stay with their existing workflow or coordinator owners. This guide
307+
adds no workflow phase or review stage.
308+
309+
Start required Fable reviews when the exact feedback commit and focused evidence
310+
are ready, without waiting for CI on `main` or the reviewed branch. When Fable
311+
is unavailable, including exhausted Claude quota, use an independent Codex Astra
312+
(`gpt-6-astra`) reviewer under the same scope, effort policy and correction
313+
limits. Reconcile any in-flight call and preserve its findings before fallback.
314+
Record the review provider/model. The repository's
315+
[review rules](../../AGENTS.md#feedback-commits) retain main health and required
316+
CI as merge gates; review acceptance waives neither.
317+
302318
## Test without paid agents
303319

304320
```bash

0 commit comments

Comments
 (0)