[SDLC] Refine the SDLC human plan review workflow

action/build-sdlc-prompt.sh

@@ -160,15 +160,47 @@ In the refine phase:
 - You CANNOT push code (git push)
 - You CANNOT create PRs (gh pr create)
 
+## HITL Decisions
+
+For questions that require human input before proceeding:
+
+**Multiple-choice questions** (use formal HITL decisions):
+\`\`\`bash
+egg-contract add-decision --question "Which approach should we use?" \\
+  --options "Option A" "Option B" "Option C" --format markdown
+\`\`\`
+Copy the markdown output into your analysis comment. The human can check a checkbox
+to select an option. An "Other (explain in reply)" option is auto-appended.
+
+**Open-ended questions** (no predefined options):
+List these as plain text in your analysis. The human will respond via comment.
+
+## Phase Completion
+
+When your analysis is complete, post a completion comment with an approval section:
+
+\`\`\`markdown
+## Refine Phase Complete
+
+[Summary of analysis and recommendation]
+
+### Ready for Review
+
+<!-- egg-phase-approval -->
+- [ ] Approve and advance to plan phase
+
+---
+
+*Authored-by: egg*
+\`\`\`
+
 ## Next Steps
 
-When your analysis is complete:
 1. Write the analysis document to a file: \`/tmp/analysis.md\`
 2. Post via file to avoid shell escaping issues: \`gh issue comment ${issue_number} --body-file /tmp/analysis.md\`
-3. If you have open questions, use \`egg-contract add-decision --question "..."\`
-4. Wait for human approval to advance to the plan phase
+3. Wait for human approval (they check the approval checkbox)
 
-**IMPORTANT**: Always use \`--body-file\` instead of \`--body\` when posting analysis.
+**IMPORTANT**: Always use \`--body-file\` instead of \`--body\` when posting.
 Content containing \`\${{ }}\` expressions or other shell metacharacters will corrupt
 the comment if passed inline via \`--body\`.
 EOF
@@ -268,13 +300,41 @@ In the plan phase:
 - You CANNOT push code (git push)
 - You CANNOT create PRs (gh pr create)
 
+## HITL Decisions
+
+For questions that require human input before proceeding:
+
+**Multiple-choice questions** (use formal HITL decisions):
+\`\`\`bash
+egg-contract add-decision --question "Which architecture pattern?" \\
+  --options "Microservices" "Monolith" "Hybrid" --format markdown
+\`\`\`
+Copy the markdown output into your plan comment. The human can check a checkbox
+to select an option. An "Other (explain in reply)" option is auto-appended.
+
+**Open-ended questions** (no predefined options):
+List these as plain text. The human will respond via comment.
+
+## Phase Completion
+
+When your plan is complete, include an approval section at the end:
+
+\`\`\`markdown
+### Ready for Review
+
+<!-- egg-phase-approval -->
+- [ ] Approve and advance to implement phase
+
+---
+
+*Authored-by: egg*
+\`\`\`
+
 ## Next Steps
 
-When your plan is complete:
 1. Write the plan document to a file: \`/tmp/plan.md\`
 2. Post via file to avoid shell escaping issues: \`gh issue comment ${issue_number} --body-file /tmp/plan.md\`
-3. If you have open questions, use \`egg-contract add-decision --question "..."\`
-4. Wait for human approval to advance to the implement phase
+3. Wait for human approval (they check the approval checkbox)
 
 **IMPORTANT**: Always use \`--body-file\` instead of \`--body\` when posting the plan.
 Content containing \`\${{ }}\` expressions or other shell metacharacters will corrupt

docs/hitl-decisions.md

@@ -0,0 +1,137 @@
+# HITL (Human-In-The-Loop) Decision Workflow
+
+This document explains how human decisions are captured and processed in the SDLC pipeline.
+
+## Overview
+
+The SDLC pipeline includes phases where human input is required before proceeding:
+- **Refine phase**: Human approves the analysis before planning
+- **Plan phase**: Human approves the implementation plan before coding
+
+Two mechanisms exist for gathering human input:
+1. **Formal HITL decisions** — Multiple-choice questions with checkboxes
+2. **Phase approval** — Single checkbox to approve and advance to the next phase
+
+## Formal HITL Decisions
+
+Use formal decisions when you need the human to choose between predefined options.
+
+### Creating a Decision
+
+```bash
+egg-contract add-decision \
+  --question "Which caching strategy should we use?" \
+  --options "Redis" "In-memory LRU" "File-based" \
+  --format markdown
+```
+
+Output:
+```markdown
+<!-- egg-hitl-decision id=decision-1 -->
+
+**Which caching strategy should we use?**
+
+- [ ] Redis
+- [ ] In-memory LRU
+- [ ] File-based
+- [ ] Other (explain in reply)
+```
+
+### How It Works
+
+1. The agent includes this markdown in a GitHub comment
+2. The `<!-- egg-hitl-decision id=... -->` marker identifies the decision
+3. When the human checks a checkbox, GitHub triggers an `issue_comment.edited` event
+4. The `sdlc-hitl.yml` workflow detects the change and updates the contract
+5. If this was the last pending decision, the workflow advances to the next phase
+
+### Auto-appended "Other" Option
+
+When you provide `--options`, an "Other (explain in reply)" option is automatically
+appended. If the human selects this, they can explain their preference in a follow-up
+comment, which the agent will parse.
+
+### Open-ended Questions
+
+For questions without predefined options, don't use the `--options` flag:
+- Simply list the question as plain text in your comment
+- The human will respond via a new comment
+- No special workflow processing occurs; the agent reads the reply
+
+## Phase Approval
+
+Phase approval is a simpler mechanism for advancing the pipeline.
+
+### Format
+
+```markdown
+### Ready for Review
+
+<!-- egg-phase-approval -->
+- [ ] Approve and advance to plan phase
+
+---
+
+*Authored-by: egg*
+```
+
+### How It Works
+
+1. The agent includes this at the end of phase completion comments
+2. The `<!-- egg-phase-approval -->` marker identifies the approval section
+3. When the human checks the `[x] Approve` checkbox, GitHub triggers an edit event
+4. The `sdlc-hitl.yml` workflow's `handle-approval` job detects this
+5. The workflow updates the contract phase and triggers the next pipeline run
+
+### Key Differences from Decisions
+
+| Aspect | Formal Decisions | Phase Approval |
+|--------|-----------------|----------------|
+| Marker | `<!-- egg-hitl-decision id=... -->` | `<!-- egg-phase-approval -->` |
+| Purpose | Choose between options | Advance to next phase |
+| Multiple options | Yes (with "Other") | No (single checkbox) |
+| Workflow job | `handle-decision` | `handle-approval` |
+
+## Workflow Detection
+
+The `sdlc-hitl.yml` workflow triggers on `issue_comment.edited` events. It checks:
+
+1. **For decisions**: Comment contains `<!-- egg-hitl-decision` and a checkbox changed
+2. **For approvals**: Comment contains `<!-- egg-phase-approval` or `[x] Approve`
+
+### Security
+
+- Only authorized users (configured in the workflow) can trigger phase transitions
+- The bot cannot approve its own comments
+- Debounce logic prevents rapid-fire updates when multiple boxes are checked quickly
+
+## Best Practices
+
+1. **Keep decisions focused**: One question per decision, with 2-4 clear options
+2. **Always include "Other"**: The CLI does this automatically when using `--options`
+3. **Separate concerns**: Use one comment for analysis/plan, another for approval
+4. **Use descriptive questions**: Be specific about what you're asking
+
+## Troubleshooting
+
+### "Approval checkbox doesn't trigger workflow"
+
+Check that:
+- The `<!-- egg-phase-approval -->` marker is present
+- The marker is on the line immediately before the checkbox
+- The checkbox format is exactly `- [ ] Approve...` (spaces matter)
+- The comment was edited (not a new comment)
+
+### "Decision not detected"
+
+Check that:
+- The `<!-- egg-hitl-decision id=... -->` marker is present
+- The decision ID uses only lowercase letters, numbers, and hyphens
+- The checkbox format is standard markdown: `- [ ] Option` or `- [x] Option`
+
+## Related Files
+
+- `.github/workflows/sdlc-hitl.yml` — Workflow handling decisions and approvals
+- `sandbox/egg_lib/contract_cli.py` — CLI for creating decisions
+- `docs/templates/analysis.md` — Template showing decision usage
+- `docs/templates/phase-completion.md` — Template for approval format

docs/templates/analysis.md

@@ -48,8 +48,22 @@
 
 ## Open Questions
 
-- [ ] [Question 1 that needs human input]
-- [ ] [Question 2 that needs human input]
+For questions that require human input before proceeding, use formal HITL decisions.
+The agent will generate these using `egg-contract add-decision --format markdown`.
+
+**Multiple-choice questions** (when you need the human to pick from options):
+```
+egg-contract add-decision --question "Which caching strategy should we use?" \
+  --options "Redis" "In-memory LRU" "File-based" --format markdown
+```
+This outputs markdown with checkboxes that the human can interact with directly.
+
+**Open-ended questions** (when you need free-form input):
+Include these as plain text in your analysis. The human will respond via comment.
+
+Example open-ended questions:
+- What is the expected request volume for this feature?
+- Are there any constraints on third-party dependencies?
 
 ---
 

docs/templates/phase-completion.md

@@ -0,0 +1,58 @@
+# Phase Completion Comment Template
+
+Use this format when posting a phase completion comment to GitHub.
+The approval checkbox uses the `<!-- egg-phase-approval -->` marker
+which triggers the sdlc-hitl.yml workflow when edited.
+
+## Template
+
+```markdown
+## [Phase Name] Complete
+
+[Brief summary of what was accomplished in this phase]
+
+### Deliverables
+
+- [Deliverable 1]
+- [Deliverable 2]
+
+### Ready for Review
+
+<!-- egg-phase-approval -->
+- [ ] Approve and advance to next phase
+
+---
+
+*Authored-by: egg*
+```
+
+## Notes
+
+- The `<!-- egg-phase-approval -->` marker must appear on the line immediately before the approval checkbox
+- When the human checks the `[x] Approve` checkbox, the workflow detects the edit and advances to the next phase
+- Keep the approval checkbox as a single option to avoid confusion
+- The phase name in the heading should match the current SDLC phase (refine, plan, implement)
+
+## Example: Refine Phase Complete
+
+```markdown
+## Refine Phase Complete
+
+Analysis of issue #123 is complete. The recommended approach is to implement
+Option B (Redis caching) based on the constraints identified.
+
+### Deliverables
+
+- Problem statement and constraints documented
+- Three options analyzed with pros/cons
+- Recommendation provided with justification
+
+### Ready for Review
+
+<!-- egg-phase-approval -->
+- [ ] Approve and advance to plan phase
+
+---
+
+*Authored-by: egg*
+```

docs/templates/plan.md

@@ -90,4 +90,21 @@ phases:
 
 ---
 
+## Phase Approval
+
+When posting this plan as a GitHub comment, include an approval section at the end.
+Use the phase-completion template format with the `<!-- egg-phase-approval -->` marker:
+
+```markdown
+### Ready for Review
+
+<!-- egg-phase-approval -->
+- [ ] Approve and advance to implement phase
+```
+
+This allows the human to approve by checking the checkbox, which triggers the
+workflow to advance to the next phase.
+
+---
+
 *Authored-by: egg*