From 439d502162e5230a5c44c1fb528a0e033b8e13f1 Mon Sep 17 00:00:00 2001 From: Hally Maschine Date: Wed, 1 Apr 2026 12:51:10 -0700 Subject: [PATCH] cmd/sgai/skel: relay retrospective questions literally --- cmd/sgai/skel/.sgai/agent/coordinator.md | 54 +++++++++++++++++----- cmd/sgai/skel/.sgai/agent/retrospective.md | 18 +++++++- 2 files changed, 58 insertions(+), 14 deletions(-) diff --git a/cmd/sgai/skel/.sgai/agent/coordinator.md b/cmd/sgai/skel/.sgai/agent/coordinator.md index 62ccdbc..72a43bc 100644 --- a/cmd/sgai/skel/.sgai/agent/coordinator.md +++ b/cmd/sgai/skel/.sgai/agent/coordinator.md @@ -298,6 +298,7 @@ The master plan has these steps (if any of these files don't exist, YOU MUST CAL If the returned response authorizes work to proceed, hand-over control to specialized agents and continue the factory flow without repeating brainstorming or work-gate. If the returned response says more clarification is needed, return to the BRAINSTORMING step to gather more requirements. + If the returned response includes a retrospective skip override, preserve that note in @.sgai/PROJECT_MANAGEMENT.md so the retrospective step can honor it later. IF YOU FIND YOURSELF WRITING CHANGES TO SOURCE CODE, THAT'S AN AUTOMATIC FAILURE - UNDO and return control to the next agent in the flow. @@ -322,24 +323,53 @@ The master plan has these steps (if any of these files don't exist, YOU MUST CAL ## IRON LAW: RETRO_QUESTION Relay -When you receive a message from the retrospective agent with "RETRO_QUESTION:" prefix, you MUST follow this exact procedure: +When you receive a message from the retrospective agent with a `RETRO_QUESTION ...:` prefix, you MUST follow this exact procedure: -1. Extract the question content from the RETRO_QUESTION message -2. Call `sgai_ask_user_question` to relay it to the human partner — this is MANDATORY -3. Wait for the human's actual response -4. Send the human's ACTUAL response back to the retrospective agent -5. Set status to "agent-done" to yield control +1. Strip only the `RETRO_QUESTION ...:` prefix. The prefix starts with `RETRO_QUESTION`, may include bracketed mode hints such as `[MULTI-SELECT]`, and ends at the first colon. +2. Copy everything after that prefix verbatim into the `question` field. Do not paraphrase, summarize, reorder, clean up, or rewrite any of that text. +3. Parse the retrospective selection list into `choices` by collecting each selectable bullet item exactly as written after the bullet marker. +4. If the prefix contains `[MULTI-SELECT]`, set `multiSelect=true`. Otherwise set `multiSelect=false`. +5. Call `sgai_ask_user_question` to relay it to the human partner — this is MANDATORY +6. Wait for the human's actual response +7. Send the human's ACTUAL response back to the retrospective agent +8. Set status to "agent-done" to yield control **The pattern is ALWAYS:** ``` -// Step 1: Relay to human (MANDATORY - cannot skip) -sgai_ask_user_question({questions: [{question: "[content from RETRO_QUESTION message]", choices: [...], multiSelect: false}]}) -// Step 2: After receiving human's answer, send it back +// Given this message from retrospective: +// RETRO_QUESTION [MULTI-SELECT]: **Skills Changes** (2 proposals) +// +// ### 1. Add SQL formatting section to go-code-review +// Evidence: Reviewer flagged SQL formatting 3 times in session +// ... +// +// Select which to approve (multi-select): +// - 1. Add SQL formatting section to go-code-review +// - 2. Create db-migration-testing skill + +sgai_ask_user_question({ + questions: [{ + question: "**Skills Changes** (2 proposals)\n\n### 1. Add SQL formatting section to go-code-review\nEvidence: Reviewer flagged SQL formatting 3 times in session\n...\n\nSelect which to approve (multi-select):\n- 1. Add SQL formatting section to go-code-review\n- 2. Create db-migration-testing skill", + choices: [ + "1. Add SQL formatting section to go-code-review", + "2. Create db-migration-testing skill" + ], + multiSelect: true + }] +}) + sgai_send_message({toAgent: "retrospective", body: "Human partner's answer: [ACTUAL answer received from sgai_ask_user_question]"}) -// Step 3: Yield control + sgai_update_workflow_state({status: "agent-done"}) ``` +### ANTI-PATTERN: Rewriting Retrospective Questions +- NEVER paraphrase, summarize, reorder, or otherwise rewrite the post-prefix text +- NEVER strip anything except the `RETRO_QUESTION ...:` prefix +- NEVER infer `multiSelect` from the body text; only `[MULTI-SELECT]` in the prefix can flip it to `true` +- NEVER invent or rewrite choices; parse the selection list exactly as written +- If the retrospective message is malformed, do NOT "fix" it by paraphrasing. Ask the retrospective agent to resend a correctly formatted `RETRO_QUESTION` message. + ### ANTI-PATTERN: Fabricating Human Answers - NEVER assume what the human would answer - NEVER claim you "already relayed" the question in a previous turn without verifiable evidence of an `sgai_ask_user_question` call and response @@ -357,11 +387,11 @@ sgai_update_workflow_state({status: "agent-done"}) ``` sgai_send_message({ toAgent: "retrospective", - body: "Please start the post-completion retrospective analysis. Analyze session artifacts and send me structured questions for the human partner using RETRO_QUESTION: prefix. When done, send RETRO_COMPLETE: with a summary." + body: "Please start the post-completion retrospective analysis. Analyze session artifacts and send me structured questions for the human partner using the RETRO_QUESTION [MULTI-SELECT]: contract, where everything after the prefix is final human-facing text and the selection bullet list is the source for choices. When done, send RETRO_COMPLETE: with a summary." }) ``` 5. Set status to "agent-done" to hand control to the retrospective agent - 6. When the retrospective agent sends you messages with "RETRO_QUESTION:" prefix, follow the IRON LAW: RETRO_QUESTION Relay procedure above — you MUST call `sgai_ask_user_question` to relay the question to the human partner + 6. When the retrospective agent sends you messages with a `RETRO_QUESTION ...:` prefix, follow the IRON LAW: RETRO_QUESTION Relay procedure above — you MUST call `sgai_ask_user_question` to relay the question to the human partner 7. When the retrospective agent sends "RETRO_COMPLETE:", proceed to MARK-COMPLETE - Step Name: CLEAN-UP-TMUX-AFTER diff --git a/cmd/sgai/skel/.sgai/agent/retrospective.md b/cmd/sgai/skel/.sgai/agent/retrospective.md index 3a6696b..ed57c90 100644 --- a/cmd/sgai/skel/.sgai/agent/retrospective.md +++ b/cmd/sgai/skel/.sgai/agent/retrospective.md @@ -84,6 +84,20 @@ If you find zero actionable suggestions, send a `RETRO_COMPLETE:` message and ex You do NOT call `ask_user_question` directly. Instead, send structured messages to the coordinator with all proposals for a category in a single message. +**The coordinator relay is literal and prompt-native:** +- The coordinator strips only the `RETRO_QUESTION ...:` prefix. +- Everything after that prefix is copied verbatim into the human-facing `question` field. +- The coordinator parses your selection list into `choices` by reading the selectable bullet items. +- If the prefix contains `[MULTI-SELECT]`, the coordinator sets `multiSelect=true`; otherwise it defaults to `false`. +- There is NO paraphrasing fallback. + +**Therefore every `RETRO_QUESTION` message you send MUST:** +1. Put every human-visible word after the prefix exactly as the human should read it. +2. Use `RETRO_QUESTION [MULTI-SELECT]:` when more than one choice may be approved; otherwise use `RETRO_QUESTION:`. +3. Keep the question body self-contained, because the coordinator will not add context, rewrite it, or clean it up for you. +4. End with a selection list that contains one selectable item per bullet line using `- `. +5. Keep each bullet item's text stable and explicit, because those bullet lines become the `choices` entries. + **For each non-empty category, send ONE message:** ``` @@ -93,7 +107,7 @@ sgai_send_message({ }) ``` -Then set status to `agent-done` to yield control. The coordinator will relay the multi-select question to the human and send you the answer indicating which numbered items were approved. When all categories have been presented and responses received, apply approved changes and send: +Then set status to `agent-done` to yield control. The coordinator will relay the exact post-prefix body to the human, parse the bullet list into `choices`, and send you the answer indicating which numbered items were approved. When all categories have been presented and responses received, apply approved changes and send: ``` sgai_send_message({ @@ -172,7 +186,7 @@ If you cannot produce observations for all 4 categories, you MUST re-read the ar You have access to: -- **`send_message`** / **`check_inbox`** / **`check_outbox`** — Your primary interaction tools. Send category-grouped proposals to coordinator (RETRO_QUESTION [MULTI-SELECT]:), receive human selections, send completion (RETRO_COMPLETE:). +- **`send_message`** / **`check_inbox`** / **`check_outbox`** — Your primary interaction tools. Send category-grouped proposals to coordinator (`RETRO_QUESTION [MULTI-SELECT]:`), receive human selections, send completion (`RETRO_COMPLETE:`). - **`find_skills`** / **`skill`** — Load skills, including the retrospective skill you must use. - **`update_workflow_state`** — Signal progress and yield control (`agent-done`). - **File read/write tools** — Read artifacts, write approved changes to `sgai/` overlay, `AGENTS.md`, and `.sgai/SGAI_NOTES.md`.