Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions docs/doperpowers/specs/2026-07-08-pr-review-loop-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,9 +95,13 @@ whole-branch review; the escalation would have died at the board write).

### 3. New skill `skills/reviewing-prs/` — the product

- **`SKILL.md`** — loop doctrine, the Review Worker Protocol (embedded
verbatim in spawn prompts, like issue-tracker's Worker Protocol), the three
rubrics, the authority table, tech-debt-sink doctrine, codex-lock handling.
- **`SKILL.md`** — the canonical Review Worker Protocol. Every dispatched
worker explicitly invokes this skill; the bootstrap supplies its per-PR
placeholders as runtime bindings.
- **`references/operation-manual.md`** — loop doctrine, setup, operating
policy, the rubrics, authority model, tech-debt sink, and adoption checklist.
- **`references/review-worker-bootstrap.md`** — the thin per-PR spawn prompt:
skill invocation plus dispatcher-owned runtime bindings and context.
- **`scripts/review-dispatch.sh <pr#> | --sweep`** — dedupe (a live daemon
registry entry named `review-pr-<n>` means skip); context gathering
(`gh pr view --json title,body,baseRefName,headRefName,headRefOid,url,labels`
Expand Down Expand Up @@ -515,3 +519,25 @@ Pending — written at finish.
blocker, not a clean report. SELF-MERGE wording aligned ("non-blocker
findings, each explicitly routed"). Protocol + SKILL.md tech-debt sink
updated; spec body §Review Worker Protocol left as the historical draft.
- 2026-07-14 (skill-entrypoint restructure): restored the runtime boundary the
original design intended. `SKILL.md` is now the canonical Review Worker
Protocol; `review-dispatch.sh` emits a thin bootstrap that explicitly invokes
the skill and supplies all instance placeholders as runtime bindings. The
former operator-oriented skill body moved intact to
`references/operation-manual.md`. Review policy and routing are unchanged.
- 2026-07-15 (entrypoint hardening before landing): adversarial review of the
restructure found two defects of the new file-based entrypoint itself and
one doc drift, fixed on the PR before landing. (1) Trust boundary: the
bootstrap now binds `SKILL_FILE` (dispatcher-owned absolute path) and
instructs the worker to open it unconditionally, never resolving the
protocol from the workspace `.agents/skills` — that path is PR-controlled
in the detached review head, so a PR could ship a same-named skill that
replaces the merge rubric. A rendered prompt was immune by construction;
a runtime-opened file needs the pinned path. (2) Dead template tail:
SKILL.md carried unrendered `---- PR brief ----` sections that nothing
renders (dispatch renders the bootstrap, not SKILL.md); removed — briefs
and manifests ride the dispatch prompt, and the protocol now says so.
(3) `operation-manual.md` still said self-merge tolerates "only low
findings" while the protocol says non-blockers (everything below
critical/high, medium included); the manual now matches, with regression
asserts pinning both the manual wording and the tail's absence.
Original file line number Diff line number Diff line change
Expand Up @@ -161,9 +161,9 @@ same only-if-unset pattern. Worker-shell flags unchanged.

### 5. Documentation surfaces

- `skills/reviewing-prs/SKILL.md` "Review engine" section rewritten: one
native engine, one script, both species; species differ only in
nesting; engine-down semantics per §3.
- `skills/reviewing-prs/references/operation-manual.md` "Review engine"
section rewritten: one native engine, one script, both species; species
differ only in nesting; engine-down semantics per §3.
- codex-workers spec (`2026-07-10-codex-workers-design.md`): Revision
Note recording the two overturned conclusions, pointing here.
- Shakedown doc FU-7 section: dated correction note pointing here.
Expand Down Expand Up @@ -351,3 +351,8 @@ plan re-execution; everything else executed as written.
spec-compliance/decision-discipline addendum; the data file carries the
ticket requirements alone (no PR-claims section — Note 3 dropped that
check); a ticketless PR sends no developer instructions at all.
5. **2026-07-14 (skill-entrypoint restructure).** The Review Worker Protocol
moved from a supporting reference into `skills/reviewing-prs/SKILL.md` and
the former operator-oriented skill body moved to
`references/operation-manual.md`. The dispatcher now invokes the skill via
a thin runtime-binding bootstrap; engine policy and behavior are unchanged.
8 changes: 4 additions & 4 deletions skills/issue-tracker/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -216,10 +216,10 @@ reviewing-prs, and nobody sits between them and the board.
## Worker protocols

The implement-side protocol lives in doperpowers:implementing-tickets
(`references/implement-worker-protocol.md`); the review-side protocol in
doperpowers:reviewing-prs (`references/review-worker-protocol.md`). Both are
embedded VERBATIM in spawn prompts. This file owns only the schema they
write against.
(`references/implement-worker-protocol.md`) and is embedded verbatim in its
spawn prompts. The review-side protocol is doperpowers:reviewing-prs itself
(`SKILL.md`); its spawn bootstrap invokes the skill and supplies runtime
bindings. This file owns only the schema they write against.

## The ticket body (pre-spec)

Expand Down
Loading