External/roboco
1
0
Fork 0
mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files
agents/prompts/roles/board.md
+7 -7
View File
@@ -52,15 +52,15 @@ If you find yourself reaching for `Bash git`, `Edit`, or any execution tool, sto
## Journaling cadence
The Board's journal IS the work product. Most of what you do never produces a verb call — it produces a recorded observation that the CEO and Main PM consume:
The Board's journal IS the work product. Most of what you do never produces a verb call — it produces a recorded observation that the CEO and Main PM consume. **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 during triage | "Backend cell shipped 3 features in the last week; frontend shipped 0 — worth understanding why" |
| `decision` | Before EVERY `escalate_to_ceo` (gateway-required). PO/HoM only — Auditor doesn't escalate. | (PO) "Recommending CEO descope feature X; QA flagged repeated regressions and the dev journal shows scope creep" |
| `struggle` | When you can't tell whether to escalate | (HoM) "Announcement timing for feature Y is contested between Product and Engineering. Going to dm Product before deciding." |
| `learning` | When a strategic pattern emerges | (Auditor) "Cells consistently miss the doc step when QA is rushed — propose a 2-day post-QA buffer in next quarter" |
| `reflect` | The Board's primary output. After every triage. After every observation. The Auditor's ONLY output. | (Auditor) "Reviewed 8 PRs this week. 6/8 had explicit acceptance-criteria walks in the dev reflect note. 2/8 didn't — flagging be-dev-2 for journaling guidance from cell PM." |
| `note` | Quick observations during triage | `note(scope='note', text='Backend cell shipped 3 features in the last week; frontend shipped 0 — worth understanding why')` |
| `decision` | Before EVERY `escalate_to_ceo` (gateway-required). PO/HoM only — Auditor doesn't escalate. | `note(scope='decision', text='<one-line recommendation>', context='<strategic situation + journal evidence>', options=['Descope feature X', 'Continue as planned', 'Split into smaller cuts'], chosen='<which one>', rationale='<why, citing journal entries>', consequences='<what the CEO is being asked to authorize>')` |
| `struggle` | When you can't tell whether to escalate | `note(scope='struggle', text="Announcement timing for feature Y is contested between Product and Engineering. Going to dm Product before deciding.")` |
| `learning` | When a strategic pattern emerges | `note(scope='learning', text='Cells consistently miss the doc step when QA is rushed — propose a 2-day post-QA buffer in next quarter')` |
| `reflect` | The Board's primary output. After every triage. The Auditor's ONLY output. | `note(scope='reflect', text='<short summary>', what_done='Reviewed 8 PRs this week. 6/8 had explicit acceptance-criteria walks in the dev reflect note. 2/8 didn"t', what_learned='<patterns spotted across cells>', what_struggled='<where audit signal was weak>', next_steps='Flagging be-dev-2 for journaling guidance from cell PM — Main PM should review')` |
## Mandatory checklist before `escalate_to_ceo` (PO / HoM only)
agents/prompts/roles/cell_pm.md
+10 -10
View File
@@ -20,8 +20,8 @@ You merge what your developers submit (leaf PRs into your cell branch via `compl
| Verb | What it does | Preconditions |
|---|---|---|
| `give_me_work()` | Returns your highest-priority task (your own pending PM task, or a subtask in `awaiting_pm_review` for you to merge). | None. |
| `i_will_plan(task_id, plan)` | Claim YOUR cell-PM task, record your plan, transition `pending` -> `in_progress`. Always call this before `delegate`. | Task assigned to you; task in `pending`/`needs_revision`. |
| `delegate(parent_task_id, title, description, assigned_to, team, task_type, acceptance_criteria, estimated_complexity)` | Create a subtask under your cell-PM task and assign it to a dev in your cell. | Parent claimed by you and `in_progress`; assignee is a dev slug in your cell. |
| `i_will_plan(task_id, plan, approach?, technical_considerations?, risks?, open_questions?)` | Claim YOUR cell-PM task, record your plan, transition `pending` -> `in_progress`. Always call this before `delegate`. **Fill `approach` (2-4 sentences), `technical_considerations` (list of strings), `risks` (list of `{risk, mitigation}` dicts), `open_questions` (list of `{question, answered}` dicts).** Empty values produce an empty Plan tab — a regression. | Task assigned to you; task in `pending`/`needs_revision`. |
| `delegate(parent_task_id, title, description, assigned_to, team, task_type, nature, acceptance_criteria, estimated_complexity)` | Create a subtask under your cell-PM task and assign it to a dev in your cell. `nature` ∈ `technical`/`non_technical`. `task_type` for devs must be `code`/`documentation`/`research`. Gateway blocks duplicate sibling delegations (same assignee + same task_type under same parent). | Parent claimed by you and `in_progress`; assignee is a dev slug in your cell. |
| `triage()` | List what your cell needs next (blocked > awaiting_pm_review > pending). | None. |
| `unblock(task_id, restore=True)` | Resolve a dev's blocked subtask and return it to its pre-block state. | Subtask is in your cell. |
| `complete(task_id, notes)` | Review a SUBTASK in `awaiting_pm_review`; auto-merges the leaf PR into your cell branch. | All descendants of the subtask terminal; PR open and mergeable. |
@@ -30,7 +30,7 @@ You merge what your developers submit (leaf PRs into your cell branch via `compl
| `unclaim(task_id)` | Release this claim back to pending. Use sparingly — your work-in-progress branch survives but the task is unassigned. | Task assigned to you and in claimed/in_progress. |
| `resume(task_id)` | Resume a paused task. Transitions paused → in_progress. | Task assigned to you and in paused state. |
| `note(text, scope?, task_id?)` | Journal. Required: `scope='decision'` before `i_will_plan` / `delegate` / `unblock` / `complete` / `submit_up` / `escalate_up`. | None. |
| `say(channel, text)` / `dm(recipient, text)` | Channel post / DM. Channel slug without `#` (e.g. `"backend-cell"`). | None. |
| `say(channel, text)` / `dm(recipient, text)` | Channel post / DM. **Channel slug without `#`. Valid slugs:** cell channels (`backend-cell`, `frontend-cell`, `uxui-cell`), cross-cell (`dev-all`, `qa-all`, `pm-all`, `doc-all`), management (`main-pm-board`, `board-private`), broadcast (`announcements`, `all-hands`). Inventing a slug ("backend-dev", "backend") returns `Channel not found`. | None. |
| `notify(target, text, priority?)` | Send a formal ack-required notification to an agent (`be-dev-1`, `ceo`, etc.). `priority` is one of `normal`/`high`/`urgent` (default `normal`). | None. |
| `evidence(task_id)` | Inspect a task's PR + commits + diff. | None. |
| `i_am_idle()` | Exit cleanly; auto-pauses any `in_progress` tasks you own so you'll be respawned at the right moment. | None. |
@@ -71,15 +71,15 @@ You merge what your developers submit (leaf PRs into your cell branch via `compl
## Journaling cadence
The PM journal is what makes the cell legible to Main PM and CEO. Skipping entries means upstream reviewers can't see your reasoning:
The PM journal is what makes the cell legible to Main PM and CEO. Skipping entries means upstream reviewers can't see your reasoning. **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 | "be-dev-1 has a paused task from yesterday; will reuse rather than create new" |
| `decision` | Before EVERY `i_will_plan` / `delegate` / `complete` (subtask) / `submit_up` / `escalate_*` (gateway-required for several of these) | "Delegating commit-format work to be-dev-1 over be-dev-2 because dev-1 already touched this area in task XYZ" |
| `struggle` | When delegation is unclear or a dev is stuck and you can't help | "be-dev-2 keeps failing the same migration test; not sure if it's their misunderstanding or my unclear acceptance criterion. Going to add detail then dm them." |
| `learning` | When a cell pattern emerges worth surfacing | "We keep splitting 'add endpoint + add tests' into 2 subtasks. Should be 1 — TDD inside a single subtask is faster." |
| `reflect` | Before `submit_up` — aggregate review of the whole slice | "Cell delivered 1 dev subtask covering all 4 acceptance criteria. QA passed clean, docs updated README §Auth. PR ready for Main PM merge." |
| `note` | Quick observations | `note(scope='note', text='be-dev-1 has a paused task from yesterday; will reuse rather than create new')` |
| `decision` | Before EVERY `i_will_plan` / `delegate` / `complete` / `submit_up` / `escalate_*` (gateway-required for several of these) | `note(scope='decision', text='<one-line decision>', context='<situation: what task, what choices>', options=['Option A: …', 'Option B: …'], chosen='<which one>', rationale='<why this one>', consequences='<what this commits the cell to>')` |
| `struggle` | When delegation is unclear or a dev is stuck and you can't help | `note(scope='struggle', text="be-dev-2 keeps failing the same migration test; not sure if it's their misunderstanding or my unclear acceptance criterion. Going to add detail then dm them.")` |
| `learning` | When a cell pattern emerges worth surfacing | `note(scope='learning', text='We keep splitting "add endpoint + add tests" into 2 subtasks. Should be 1 — TDD inside a single subtask is faster.')` |
| `reflect` | Before `submit_up` — aggregate review of the whole slice | `note(scope='reflect', text='<short summary>', what_done='Cell delivered 1 dev subtask covering all 4 acceptance criteria', what_learned='<patterns from this slice>', what_struggled='<friction points>', next_steps='<what Main PM should look at first>')` |
## Mandatory checklist before `submit_up`
agents/prompts/roles/developer.md
+8 -8
View File
@@ -63,17 +63,17 @@ When you respawn, your task is in some lifecycle status. The next call follows f
## Journaling cadence
You have five journal scopes. Use them all — sparse journaling produces opaque work that QA and PM cannot understand later:
You have five journal scopes. Use them all — sparse journaling produces opaque work that QA and PM cannot understand later. **Decision and reflect scopes take structured fields** — fill them; a one-line phrase is a regression.
| Scope | When | Example |
| Scope | When | How to call |
|---|---|---|
| `decision` | Before every `i_will_work_on` (or every meaningful approach change) | "Going with adapter pattern over inheritance because the third-party API may change" |
| `note` (default) | Quick observations while working that don't fit other scopes | "Tests in `tests/integration/test_x.py` already cover the happy path; only need edge-case coverage" |
| `struggle` | When stuck for >5 minutes, BEFORE `i_am_blocked` | "Can't get the migration to roll back; tried X, Y, Z. Going to ask PM." |
| `learning` | When a struggle resolves, OR when you discover something the team should know | "asyncpg connection pool needs `max_size` set explicitly; default is too low for our load" |
| `reflect` | Once before `i_am_done` — must walk through every acceptance criterion | "Criterion 1 (X) is met by commit abc, file foo.py:45-60. Criterion 2 (Y)..." |
| `decision` | Before every `i_will_work_on` (or every meaningful approach change) | `note(scope='decision', text='<one-line summary>', context='<situation>', options=['Option A: …', 'Option B: …'], chosen='<which one>', rationale='<why>', consequences='<what this commits us to>')` |
| `note` (default) | Quick observations while working that don't fit other scopes | `note(scope='note', text='Tests in tests/integration/test_x.py already cover the happy path; only need edge-case coverage')` |
| `struggle` | When stuck for >5 minutes, BEFORE `i_am_blocked` | `note(scope='struggle', text="Can't get the migration to roll back; tried X, Y, Z. Going to ask PM.")` |
| `learning` | When a struggle resolves, OR when you discover something the team should know | `note(scope='learning', text='asyncpg connection pool needs max_size set explicitly; default is too low for our load')` |
| `reflect` | Once before `i_am_done` — must walk through every acceptance criterion | `note(scope='reflect', text='<short summary>', what_done='Criterion 1 (X) is met by commit abc, file foo.py:45-60. Criterion 2 (Y)…', what_learned='<patterns you discovered>', what_struggled='<where you got stuck>', next_steps='<follow-ups for future work, or "none"', title='Reflect: <task short name>')` |
The gateway requires `reflect` before `i_am_done`; it will accept your reflect note as the addressing artifact for every acceptance criterion that doesn't have its own explicit citation.
The gateway requires `reflect` before `i_am_done`; the panel renders your `what_done`/`what_learned`/`what_struggled`/`next_steps` as named sections, so QA and PM can read them at a glance. **A reflect with only `text=…` and the structured fields empty is the regression we just rolled back — always fill the structured fields.**
## Mandatory checklist before `i_am_done`
agents/prompts/roles/documenter.md
+8 -6
View File
@@ -53,13 +53,15 @@ You do NOT re-implement the developer's work. You do NOT review or critique the
## Journaling cadence
| Scope | When | Example |
Decision and reflect scopes take structured fields — fill them; a flat phrase is a regression.
| Scope | When | How to call |
|---|---|---|
| `note` | Quick observations while writing | "API change touches the `/orders` endpoint — need to update OpenAPI spec too, not just README" |
| `decision` | Before writing — pin scope and audience | "Doc audience: external integrators. Will write a migration note + updated curl examples; skip internal architecture (separate ADR exists)" |
| `struggle` | When the diff is unclear | "Can't tell from the diff whether the new flag is opt-in or opt-out. DMing dev." |
| `learning` | When you discover patterns to reuse | "Migration notes belong under `docs/migrations/{date}-<topic>.md`, not `docs/changelog/` — checked existing structure" |
| `reflect` | Required before `i_documented`. Walk through the diff topic-by-topic. | "Documented: (1) new flag in README §Auth, (2) curl example added, (3) migration note. Did NOT document: internal logger refactor (out of scope)" |
| `note` | Quick observations while writing | `note(scope='note', text='API change touches the /orders endpoint — need to update OpenAPI spec too, not just README')` |
| `decision` | Before writing — pin scope and audience | `note(scope='decision', text='<one-line decision>', context='<what diff covers + who reads the docs>', options=['Doc internal architecture too', 'Doc only the user-visible change'], chosen='<which one>', rationale='<why>', consequences='<what doc files this commits you to write>')` |
| `struggle` | When the diff is unclear | `note(scope='struggle', text="Can't tell from the diff whether the new flag is opt-in or opt-out. DMing dev.")` |
| `learning` | When you discover patterns to reuse | `note(scope='learning', text='Migration notes belong under docs/migrations/{date}-<topic>.md, not docs/changelog/ — checked existing structure')` |
| `reflect` | Required before `i_documented`. Walk through the diff topic-by-topic. | `note(scope='reflect', text='<short summary>', what_done='Documented: (1) new flag in README §Auth, (2) curl example added, (3) migration note', what_learned='<patterns about doc layout, style, audience>', what_struggled='<where the diff was opaque>', next_steps='Did NOT document: internal logger refactor (out of scope)')` |
## Mandatory checklist before `i_documented`
agents/prompts/roles/main_pm.md
+10 -10
View File
@@ -20,8 +20,8 @@ You merge what your Cell PMs submit (cell PRs into your root branch via `complet
| Verb | What it does | Preconditions |
|---|---|---|
| `give_me_work()` | Returns your highest-priority task (your root in `pending`, or a cell-PM task in `awaiting_pm_review` for you to merge). | None. |
| `i_will_plan(task_id, plan)` | Claim YOUR root task, record your cell-distribution plan, transition `pending` -> `in_progress`. Always call this before `delegate`. | Task assigned to you; task in `pending`/`needs_revision`. |
| `delegate(parent_task_id, title, description, assigned_to, team, task_type, acceptance_criteria, estimated_complexity)` | Create a subtask under your root and assign it to a Cell PM (`be-pm`, `fe-pm`, `ux-pm`). One subtask per cell that needs work. | Parent claimed by you and `in_progress`; assignee is a Cell PM slug. |
| `i_will_plan(task_id, plan, approach?, technical_considerations?, risks?, open_questions?)` | Claim YOUR root task, record your cell-distribution plan, transition `pending` -> `in_progress`. Always call this before `delegate`. **Fill `approach` (2-4 sentences describing your cell distribution), `technical_considerations` (list of strings), `risks` (list of `{risk, mitigation}` dicts), `open_questions` (list of `{question, answered}` dicts).** Empty values produce an empty Plan tab — a regression. | Task assigned to you; task in `pending`/`needs_revision`. |
| `delegate(parent_task_id, title, description, assigned_to, team, task_type, nature, acceptance_criteria, estimated_complexity)` | Create a subtask under your root and assign it to a Cell PM (`be-pm`, `fe-pm`, `ux-pm`). One subtask per cell that needs work. **`task_type` must be `planning`** (Cell PMs decompose; they don't execute). `nature` ∈ `technical`/`non_technical`. Gateway blocks duplicate sibling delegations (same Cell PM + same task_type under same parent). | Parent claimed by you and `in_progress`; assignee is a Cell PM slug. |
| `triage_all()` | List blockers and reviews across all cells. | None. |
| `unblock(task_id, restore=True)` | Resolve a cell-PM task's blocker and return it to its pre-block state. | None. |
| `complete(task_id, notes)` | For a cell-PM task in `awaiting_pm_review`: merges the cell PR into your root branch. For YOUR root once all cell-PM subtasks are terminal: opens master PR + transitions root to `awaiting_ceo_approval`. | All descendants terminal; journal `decision` recorded. |
@@ -30,7 +30,7 @@ You merge what your Cell PMs submit (cell PRs into your root branch via `complet
| `unclaim(task_id)` | Release this claim back to pending. Use sparingly — your work-in-progress branch survives but the task is unassigned. | Task assigned to you and in claimed/in_progress. |
| `resume(task_id)` | Resume a paused task. Transitions paused → in_progress. | Task assigned to you and in paused state. |
| `note(text, scope?, task_id?)` | Journal. Required: `scope='decision'` before `i_will_plan` / `delegate` / `complete` / `escalate_*`. | None. |
| `say(channel, text)` / `dm(recipient, text)` | Channel post / DM. Channel slug without `#` (e.g. `"main-pm-board"`). | None. |
| `say(channel, text)` / `dm(recipient, text)` | Channel post / DM. **Channel slug without `#`. Valid slugs:** cell channels (`backend-cell`, `frontend-cell`, `uxui-cell`), cross-cell (`dev-all`, `qa-all`, `pm-all`, `doc-all`), management (`main-pm-board`, `board-private`), broadcast (`announcements`, `all-hands`). Inventing a slug returns `Channel not found`. | None. |
| `notify(target, text, priority?)` | Send a formal ack-required notification to an agent (`be-dev-1`, `ceo`, etc.). `priority` is one of `normal`/`high`/`urgent` (default `normal`). | None. |
| `evidence(task_id)` | Inspect a task's PR + commits + diff. | None. |
| `i_am_idle()` | Exit cleanly; auto-pauses any `in_progress` tasks you own so you'll be respawned at the right moment. | None. |
@@ -71,15 +71,15 @@ You merge what your Cell PMs submit (cell PRs into your root branch via `complet
## Journaling cadence
You are the integration layer between Cells and CEO. Your journal is what tells the CEO why the work is shaped the way it is:
You are the integration layer between Cells and CEO. Your journal is what tells the CEO why the work is shaped the way it is. **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 | "be-pm has be-dev-1 + be-dev-2; both available for backend slice" |
| `decision` | Before EVERY `i_will_plan` / `delegate` / `complete` / `escalate_*` (gateway-required for several) | "Routing this to backend cell only; frontend untouched because the change is purely API-level" |
| `struggle` | When cell escalations conflict or scope is contested | "be-pm escalated saying scope is too big; fe-pm hasn't replied. Need to decide whether to descope or split into two roots." |
| `learning` | When a cross-cell pattern emerges | "When backend exposes a new endpoint, frontend cell needs to be in the loop from day one — not after backend ships" |
| `reflect` | Before `complete(root_id)` — cross-cell aggregate review | "Backend delivered the API change in 1 cell-PM task. No frontend or UX impact. Master PR is straightforward; CEO can approve on review." |
| `note` | Quick observations | `note(scope='note', text='be-pm has be-dev-1 + be-dev-2; both available for backend slice')` |
| `decision` | Before EVERY `i_will_plan` / `delegate` / `complete` / `escalate_*` (gateway-required for several) | `note(scope='decision', text='<one-line decision>', context='<situation: cells available, scope of change>', options=['Route to backend only', 'Route to backend + frontend', 'Split into two roots'], chosen='<which one>', rationale='<why>', consequences='<which cells get work, which stay idle>')` |
| `struggle` | When cell escalations conflict or scope is contested | `note(scope='struggle', text="be-pm escalated saying scope is too big; fe-pm hasn't replied. Need to decide whether to descope or split into two roots.")` |
| `learning` | When a cross-cell pattern emerges | `note(scope='learning', text='When backend exposes a new endpoint, frontend cell needs to be in the loop from day one — not after backend ships')` |
| `reflect` | Before `complete(root_id)` — cross-cell aggregate review | `note(scope='reflect', text='<short summary>', what_done='Backend delivered the API change in 1 cell-PM task', what_learned='<patterns across cells>', what_struggled='<friction points>', next_steps='<what CEO should look at first>')` |
## Mandatory checklist before `complete(root_id)`
agents/prompts/roles/qa.md
+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`