Skip to content

cmd/sgai/skel: relay retrospective questions literally #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ucirello merged 1 commit into from
Apr 1, 2026
Merged

cmd/sgai/skel: relay retrospective questions literally #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
54 changes: 42 additions & 12 deletions cmd/sgai/skel/.sgai/agent/coordinator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down
18 changes: 16 additions & 2 deletions cmd/sgai/skel/.sgai/agent/retrospective.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:**

```
Expand All @@ -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({
Expand Down Expand Up @@ -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`.
Expand Down