docs(prompts): teach all roles the structured verb shapes (pre-gateway parity)

Counterpart to bcc748c. The verb signatures now expose structured
fields (approach/options/rationale/what_done/etc), but the role
prompts still showed old flat-string examples — the LLM pattern-
matches prompts before schemas, so it would have kept writing one-
line decisions even after deploy.

Each role's Journaling Cadence table now shows the full call shape
for every scope, with decision and reflect explicitly named as
structured (context/options/chosen/rationale/consequences and
what_done/what_learned/what_struggled/next_steps respectively).

PM prompts also gained:
- `i_will_plan` widened to show approach / technical_considerations /
  risks / open_questions, with an explicit "empty values produce an
  empty Plan tab — a regression" line
- `delegate` shows `nature` (technical/non_technical) and notes the
  sibling-dedup guard
- Cell PM gets the dev-only task_type rule (code/documentation/research)
- Main PM gets the planning-only rule for Cell PM delegations
- `say`/`dm` lists every valid channel slug verbatim so the LLM stops
  inventing ("backend-dev", "backend")

Prompts are read at agent spawn, so this takes effect on the next
container restart — no Python rebuild required. Combined with bcc748c
this is the full pre-gateway-parity restoration.
This commit is contained in:
Renn F
2026-05-11 04:30:36 +02:00
parent bcc748c8a3
commit 92badfe6a0
6 changed files with 51 additions and 49 deletions
+8 -8
View File
@@ -52,17 +52,17 @@ A pass without evidence is a betrayal of your role: the entire downstream chain
## Journaling cadence
You have five journal scopes. QA's job is fundamentally about evidence — sparse journaling here means a downstream PM can't tell whether you actually inspected the diff or just clicked pass:
You have five journal scopes. QA's job is fundamentally about evidence — sparse journaling here means a downstream PM can't tell whether you actually inspected the diff or just clicked pass. **Decision and reflect scopes take structured fields** — fill them; a flat phrase is a regression.
| Scope | When | Example |
| Scope | When | How to call |
|---|---|---|
| `note` | Quick observations while reviewing | "Diff touches 3 files; only `service.py` is load-bearing — others are tests/types" |
| `decision` | Before deciding to pass or fail | "Going to fail this on criterion 2: the rate-limit logic isn't covered by any test" |
| `struggle` | When something is ambiguous and you need to ask | "Criterion says 'graceful degradation' but spec doesn't define what 'graceful' means here. DMing dev." |
| `learning` | Required before pass/fail. Capture what this review taught you. | "asyncio cancellation in this codebase needs `await asyncio.shield(...)` — would have caught this in 5 min if I'd known" |
| `reflect` | Optional — for QA-process retrospection | "Took 40 min to review a 200-line PR; bottleneck was reading the dev journal first. Net positive." |
| `note` | Quick observations while reviewing | `note(scope='note', text='Diff touches 3 files; only service.py is load-bearing — others are tests/types')` |
| `decision` | Before deciding to pass or fail | `note(scope='decision', text='<one-line verdict>', context='<what you reviewed>', options=['Pass: <…>', 'Fail: <…>'], chosen='<your call>', rationale='<which criterion + evidence>', consequences='<what dev / PM has to do next>')` |
| `struggle` | When something is ambiguous and you need to ask | `note(scope='struggle', text="Criterion says 'graceful degradation' but spec doesn't define what 'graceful' means here. DMing dev.")` |
| `learning` | Required before pass/fail. Capture what this review taught you. | `note(scope='learning', text='asyncio cancellation in this codebase needs await asyncio.shield(...) — would have caught this in 5 min if I'd known')` |
| `reflect` | Optional — for QA-process retrospection | `note(scope='reflect', text='<short summary>', what_done='<what you inspected>', what_learned='<patterns you saw>', what_struggled='<where review was hard>', next_steps='<process improvements>')` |
The gateway requires `learning` before `pass`/`fail`. Your `notes` argument carries the public verdict; the journal carries the reasoning.
The gateway requires `learning` before `pass`/`fail`. Your `notes` argument carries the public verdict; the journal carries the reasoning — and the panel renders your decision's `options`/`chosen`/`rationale`/`consequences` as named sections so PMs can read them at a glance. **A decision with only `text=…` is a regression — always fill the structured fields.**
## Mandatory checklist before `pass` / `fail`