feat: bidirectional triage gates with AI-optimized templates

[snipcodeit]

BLUF

Add enforced triage quality gates, immediate GitHub feedback during /mgw:issue, AI-optimized issue/PR templates, and bidirectional stakeholder engagement loops to the MGW pipeline.

Problem / Motivation

MGW currently operates as a linear conveyor belt with six gaps:

1. No gates — validity=invalid and security=high are recorded in triage but never prevent execution. A clearly invalid issue sails through /mgw:run unchallenged.
2. No feedback during triage — Triage results aren't posted to GitHub until /mgw:run starts. Stakeholders filing issues via GitHub get zero feedback from /mgw:issue.
3. No discussion phase — Large-scope work (new-milestone route) starts planning immediately. There's no mechanism to post a scope proposal, gather stakeholder input, or confirm direction before committing resources.
4. Weak issue templates — Current templates collect narrative text (BLUF + description). They lack structured fields that the triage agent needs: acceptance criteria, scope estimates, security implications, affected files. The agent has to infer everything.
5. Weak PR template — The PR template has 3 generic sections. It doesn't capture milestone context, design decisions, security notes, breaking changes, or verification artifacts — all of which MGW's PR agent already generates but has no structured place to put.
6. No engagement loops — Once an issue is triaged, there's no mechanism to detect when a stakeholder's comment resolves a previously blocked gate, and no way to send a poorly-written issue back for improvement with specific feedback about what's missing.

Acceptance Criteria

Templates

• bug_report.yml has: acceptance criteria, scope estimate dropdown, security checkboxes, what's involved, related issues
• feature_request.yml has: acceptance criteria (required), scope estimate, priority dropdown, security checkboxes, what's involved, non-functional requirements, related issues
• New architecture_refactor.yml template exists with: current state, target state, migration strategy, risk areas, breaking changes
• PR template has: milestone context table, design decisions, security/performance notes, artifacts table, breaking changes, cross-references

Triage Gates (issue.md)

• Triage agent output is evaluated against gates: validity, security, detail sufficiency
• validity=invalid → pipeline_stage="needs-info", label "mgw:needs-info" applied, structured comment posted to GitHub listing what's missing
• security=high → pipeline_stage="needs-security-review", label "mgw:needs-security-review" applied, comment posted requesting security review
• Insufficient detail (body < 200 chars, no acceptance criteria on features) → "needs-info" gate blocks
• Triage comment posted to GitHub IMMEDIATELY during /mgw:issue (not deferred to /mgw:run)
• User can override blocked gates with explicit acknowledgment (override recorded in state)
• Gates passed → label "mgw:triaged" applied

Pipeline Validation (run.md)

• /mgw:run on a "needs-info" issue without --force → pipeline refuses to start
• /mgw:run on a "needs-security-review" issue without --security-ack → pipeline refuses
• --force and --security-ack flags override gates with logged warning
• new-milestone route triggers discussion phase: scope proposal comment posted, user confirms before planning
• Material comments with security keywords trigger re-triage prompt
• Blocking comments apply "mgw:blocked" label
• "mgw:in-progress" label applied during execution, removed at completion

State & Labels

• New pipeline stages in state.md: needs-info, needs-security-review, discussing, approved
• Triage schema extended with gate_result (passed, blockers, warnings, missing_fields)
• 7 new MGW pipeline labels defined in github.md and created by init.md
• Stage flow diagram documented in state.md

Comment Classification (review.md)

• New "resolution" classification: detects when a comment addresses previously blocked gates
• Resolution detected → offers re-triage prompt

Proposed Solution

See implementation plan below.

What's Involved

File	What Changes
.github/ISSUE_TEMPLATE/bug_report.yml	Add 5 new fields (acceptance criteria, scope, security, what's involved, related issues)
.github/ISSUE_TEMPLATE/feature_request.yml	Add 6 new fields (acceptance criteria required, scope, priority, security, what's involved, non-functional) + related issues
.github/ISSUE_TEMPLATE/architecture_refactor.yml	NEW FILE — 9 fields for structural changes
.github/PULL_REQUEST_TEMPLATE.md	Full redesign — 10 sections for AI-generated PRs
.github/labeler.yml	Add triage-pipeline label rule
commands/issue.md	Triage gates, immediate GitHub feedback, label management (~100 lines added)
commands/run.md	Validation gates, discussion phase, material re-triage, label lifecycle (~80 lines added)
commands/review.md	Resolution classification type (~20 lines added)
commands/init.md	New MGW labels in ensure_labels + updated inline templates
.claude/commands/mgw/workflows/state.md	New stages, extended triage schema, stage flow diagram
.claude/commands/mgw/workflows/github.md	Label operations, triage comment template, scope proposal template
Deployed copies in .claude/commands/mgw/	Synced from source commands/

Scope estimate: Large (12 files, 6 phases)
Security implications: None — this is pipeline infrastructure, not user-facing code.
Priority: High — unblocks quality control for all future issue processing.

Implementation Plan (6 phases)

Phase 1 — Foundation (state.md, github.md, init.md)

state.md changes

Extend pipeline_stage enum:

"pipeline_stage": "new|triaged|needs-info|needs-security-review|discussing|approved|planning|executing|verifying|pr-created|done"

Add gate_result to triage schema:

{
  "triage": {
    "scope": { "files": 0, "systems": [] },
    "validity": "pending|confirmed|invalid",
    "security_notes": "",
    "conflicts": [],
    "last_comment_count": 0,
    "last_comment_at": null,
    "gate_result": {
      "passed": false,
      "blockers": [],
      "warnings": [],
      "missing_fields": []
    }
  }
}

Add stage flow diagram:

new → triaged → approved → planning → executing → verifying → pr-created → done
         ↓                                                          ↑
    needs-info ──(resolved)──→ triaged                              │
         ↓                                                          │
    needs-security-review ──(ack)──→ triaged                        │
         ↓                                                          │
    discussing ──(confirmed)──→ approved ───────────────────────────→│
                                                                    │
    blocked ──(unblocked)──→ (previous stage) ──────────────────────┘

Update valid stages list:
Add needs-info, needs-security-review, discussing, approved to the Valid stages comment in the "Update Issue Pipeline Stage" section.

github.md changes

Add 7 new label definitions:

# MGW Pipeline Labels
gh label create "mgw:needs-info" --description "Issue needs more detail before triage can proceed" --color "e4e669" --force
gh label create "mgw:needs-security-review" --description "Issue touches security-sensitive areas — manual review required" --color "d93f0b" --force
gh label create "mgw:approved" --description "Issue triaged and approved for execution" --color "0e8a16" --force
gh label create "mgw:discussing" --description "Scope proposal posted — awaiting stakeholder confirmation" --color "c5def5" --force
gh label create "mgw:in-progress" --description "MGW pipeline actively executing" --color "1d76db" --force
gh label create "mgw:blocked" --description "Pipeline blocked by stakeholder comment" --color "b60205" --force
gh label create "mgw:triaged" --description "Issue has been triaged by MGW" --color "bfd4f2" --force

Add label lifecycle operations:

# Remove all MGW pipeline labels, then apply one — ensures clean state transitions
remove_mgw_labels_and_apply() {
  local ISSUE_NUMBER="$1"
  local NEW_LABEL="$2"
  
  # Remove existing MGW labels
  for LABEL in "mgw:needs-info" "mgw:needs-security-review" "mgw:approved" "mgw:discussing" "mgw:in-progress" "mgw:blocked" "mgw:triaged"; do
    gh issue edit "${ISSUE_NUMBER}" --remove-label "${LABEL}" 2>/dev/null || true
  done
  
  # Apply new label
  if [ -n "${NEW_LABEL}" ]; then
    gh issue edit "${ISSUE_NUMBER}" --add-label "${NEW_LABEL}"
  fi
}

Add triage gate comment template:

# Posted immediately during /mgw:issue when gates block
GATE_COMMENT=$(cat <<GATEEOF
> **MGW** · \`triage-gate\` · ${TIMESTAMP}

### Triage Gate: ${GATE_STATUS}

${GATE_ICON} **${GATE_TITLE}**

${GATE_DETAILS}

<details>
<summary>What's needed to proceed</summary>

${MISSING_ITEMS as checklist}

</details>

To proceed after addressing these items, run \`/mgw:issue ${ISSUE_NUMBER}\` to re-triage.
GATEEOF
)

Add scope proposal comment template:

# Posted during new-milestone discussion phase
SCOPE_COMMENT=$(cat <<SCOPEEOF
> **MGW** · \`scope-proposal\` · ${TIMESTAMP}

### Scope Proposal — #${ISSUE_NUMBER}

| | |
|---|---|
| **Route** | \`new-milestone\` |
| **Estimated phases** | ${PHASE_COUNT} |
| **Affected systems** | ${SYSTEMS} |
| **Security considerations** | ${SECURITY} |

#### Proposed Phases
${PHASE_LIST as numbered list}

#### Questions for Stakeholders
${QUESTIONS as numbered list}

---
React with 👍 to approve this scope, or comment with changes.
SCOPEEOF
)

init.md changes

Add new labels to ensure_labels step:
Add the 7 new mgw:* label creation commands after the existing bug and enhancement labels.

Phase 2 — GitHub Templates (.github/)

bug_report.yml

Add after existing fields:

  - type: textarea
    id: acceptance-criteria
    attributes:
      label: Acceptance Criteria
      description: How will we know this is fixed? List verifiable conditions.
      placeholder: |
        - [ ] User is returned to main branch after pipeline completes
        - [ ] No orphaned worktrees remain
    validations:
      required: false

  - type: dropdown
    id: scope-estimate
    attributes:
      label: Scope Estimate
      description: Rough estimate of how many files/systems are affected
      options:
        - Small (1-2 files)
        - Medium (3-8 files)
        - Large (9+ files or new system)
        - Unknown
    validations:
      required: false

  - type: checkboxes
    id: security
    attributes:
      label: Security Implications
      description: Check any that apply
      options:
        - label: Touches authentication/authorization
        - label: Handles user data or credentials
        - label: Involves external API calls
        - label: Affects input validation/sanitization
        - label: No security implications

  - type: textarea
    id: whats-involved
    attributes:
      label: What's Involved
      description: Files and systems that need changes (helps triage agent)
      placeholder: |
        - `commands/run.md` — worktree cleanup logic
        - `commands/issue.md` — state file write
    validations:
      required: false

  - type: textarea
    id: related-issues
    attributes:
      label: Related Issues
      description: Link any related issues or PRs
      placeholder: "Related to #42, blocks #43"
    validations:
      required: false

feature_request.yml

Add after existing fields:

  - type: textarea
    id: acceptance-criteria
    attributes:
      label: Acceptance Criteria
      description: List verifiable conditions that must be true when this feature is complete
      placeholder: |
        - [ ] /mgw:issue posts triage comment immediately
        - [ ] Invalid issues get "needs-info" label
    validations:
      required: true

  - type: dropdown
    id: scope-estimate
    attributes:
      label: Scope Estimate
      description: Rough estimate of implementation size
      options:
        - Small (1-2 files)
        - Medium (3-8 files)
        - Large (9+ files or new system)
        - Unknown
    validations:
      required: false

  - type: dropdown
    id: priority
    attributes:
      label: Priority
      description: How urgent is this?
      options:
        - Critical — blocks other work
        - High — needed soon
        - Medium — important but not urgent
        - Low — nice to have
    validations:
      required: false

  - type: checkboxes
    id: security
    attributes:
      label: Security Implications
      description: Check any that apply
      options:
        - label: Touches authentication/authorization
        - label: Handles user data or credentials
        - label: Involves external API calls
        - label: Affects input validation/sanitization
        - label: No security implications

  - type: textarea
    id: whats-involved
    attributes:
      label: What's Involved
      description: Files and systems that need changes
      placeholder: |
        - `commands/issue.md` — add gate evaluation step
        - `.claude/commands/mgw/workflows/state.md` — new pipeline stages
    validations:
      required: false

  - type: textarea
    id: non-functional
    attributes:
      label: Non-Functional Requirements
      description: Performance, compatibility, or operational constraints
      placeholder: |
        - Gate evaluation must not add >2s to triage time
        - Must work with existing .mgw/ state files (backwards compatible)
    validations:
      required: false

  - type: textarea
    id: related-issues
    attributes:
      label: Related Issues
      description: Link any related issues or PRs
      placeholder: "Related to #42, blocks #43"
    validations:
      required: false

architecture_refactor.yml (NEW FILE)

name: Architecture / Refactor
description: Propose a structural change, migration, or major refactor
labels: ["refactor"]
body:
  - type: textarea
    id: bluf
    attributes:
      label: BLUF
      description: Bottom Line Up Front — one sentence summary
    validations:
      required: true

  - type: textarea
    id: current-state
    attributes:
      label: Current State
      description: How the system works today and why it needs to change
    validations:
      required: true

  - type: textarea
    id: target-state
    attributes:
      label: Target State
      description: How the system should work after this change
    validations:
      required: true

  - type: textarea
    id: migration-strategy
    attributes:
      label: Migration Strategy
      description: How to get from current to target state. Include rollback plan if applicable.
    validations:
      required: true

  - type: textarea
    id: acceptance-criteria
    attributes:
      label: Acceptance Criteria
      description: Verifiable conditions for completion
    validations:
      required: true

  - type: dropdown
    id: scope-estimate
    attributes:
      label: Scope Estimate
      options:
        - Small (1-2 files)
        - Medium (3-8 files)
        - Large (9+ files or new system)
        - Unknown
    validations:
      required: false

  - type: checkboxes
    id: risk-areas
    attributes:
      label: Risk Areas
      description: Check all that apply
      options:
        - label: Breaking changes to existing behavior
        - label: Data migration required
        - label: Affects multiple systems/modules
        - label: Performance-sensitive code paths
        - label: Security-sensitive areas

  - type: textarea
    id: breaking-changes
    attributes:
      label: Breaking Changes
      description: List any breaking changes and migration path for consumers
    validations:
      required: false

  - type: textarea
    id: related-issues
    attributes:
      label: Related Issues
      description: Link any related issues or PRs
    validations:
      required: false

PULL_REQUEST_TEMPLATE.md (full redesign)

## Summary
<!-- 2-4 bullets: what was built and why -->

-

Closes #<!-- issue number -->

## Milestone Context
<!-- Skip this section if not part of a milestone -->

| | |
|---|---|
| **Milestone** | <!-- milestone name --> |
| **Phase** | <!-- phase number and name --> |
| **Dependencies** | <!-- blocked-by / unblocks --> |

## Changes
<!-- Group by system/module -->

### Commands
-

### Workflows
-

### Templates
-

## Design Decisions
<!-- Key architectural choices made during implementation -->

-

## Security & Performance
<!-- Note any security considerations or performance implications -->

- **Security:** <!-- none / details -->
- **Performance:** <!-- none / details -->

## Artifacts
<!-- GSD planning and verification artifacts -->

| Artifact | Path |
|----------|------|
| Plan | <!-- .planning/... --> |
| Summary | <!-- .planning/... --> |
| Verification | <!-- .planning/... --> |

## Breaking Changes
<!-- List any breaking changes. "None" if no breaking changes. -->

None

## Test Plan
<!-- How to verify these changes work -->

- [ ]

## Cross-References
<!-- Related issues, PRs, discussions -->

-

Phase 3 — Triage Gates (issue.md)

New step: evaluate_gates (between spawn_analysis and present_report)

Add a new step that evaluates triage gates against the analysis results:

• Parse VALIDITY (confirmed|questionable|invalid), SECURITY_RISK (none|low|medium|high), ISSUE_BODY_LENGTH, HAS_ACCEPTANCE_CRITERIA, IS_FEATURE from the analysis report and issue data
• Gate 1 (Validity): if VALIDITY == "invalid" → blocker
• Gate 2 (Security): if SECURITY_RISK == "high" → blocker
• Gate 3 (Detail): if ISSUE_BODY_LENGTH < 200 → missing_field
• Gate 4 (Acceptance criteria): if IS_FEATURE and no acceptance criteria → missing_field
• Warnings (non-blocking): questionable validity, medium security
• Store gate_result: { passed, blockers[], warnings[], missing_fields[] }

New step: post_triage_github (after evaluate_gates)

Posts triage results to GitHub immediately during /mgw:issue:

• If gates passed: apply "mgw:triaged" label, post triage-passed comment
• If gates blocked: determine blocking gate, apply appropriate label (mgw:needs-info or mgw:needs-security-review), post triage-gate comment listing what's needed

Modify present_report

Display gate results after triage report (passed with warnings, or blocked with blockers/missing fields list).

Modify user prompt

• If blocked: options are Override/Skip/Re-triage (instead of Accept/Override route/Reject)
• If passed: keep existing options

Modify write_state

• Use new pipeline_stage values based on gate_result
• Persist gate_result in triage section
• Record gate_override if user overrides

Modify offer_next

• If blocked + skip: direct user to update issue and re-triage
• If blocked + override: note override, offer /mgw:run

Phase 4 — Pipeline Validation (run.md)

Modify validate_and_load

• Check pipeline_stage for "needs-info" → refuse without --force
• Check pipeline_stage for "needs-security-review" → refuse without --security-ack
• Log overrides in state

New step: discussion_phase

• Only for new-milestone route when pipeline_stage != "approved"
• Post scope proposal comment to GitHub
• Apply "mgw:discussing" label, set pipeline_stage = "discussing"
• Ask user to confirm/wait/revise before proceeding

Modify preflight_comment_check

• Material comments: check for security keywords, offer re-triage, post acknowledgment comment
• Blocking comments: apply "mgw:blocked" label

Modify post_triage_update

• Change from triage comment to work-starting comment (triage comment now posted during issue.md)
• Apply "mgw:in-progress" label

Modify cleanup_and_complete

• Remove "mgw:in-progress" label at completion

Phase 5 — Comment Classification (review.md)

Add "resolution" classification

• Detects when a comment addresses a previously blocked gate
• Only activates when pipeline_stage is "needs-info" or "needs-security-review"
• Examples: 'Added acceptance criteria', 'Security review complete'

Add resolution handling

• Offer re-triage prompt when resolution detected
• Options: Re-triage / Acknowledge only / Ignore

Phase 6 — Labeler & Sync

labeler.yml

Add triage-pipeline rule for commands/issue.md, commands/run.md, commands/review.md, and workflow files.

init.md inline templates

Update inline bug and enhancement templates to match new structure.

Deployment sync

Sync commands/.md to .claude/commands/mgw/.md.

Testing Plan

Phase 1 — Foundation

• Verify state.md documents new pipeline stages
• Verify github.md has all 7 label definitions
• Verify init.md creates all 7 labels on gh label list

Phase 2 — Templates

• Verify bug_report.yml renders in GitHub issue creation form
• Verify feature_request.yml renders with required acceptance criteria field
• Verify architecture_refactor.yml appears as a new template option
• Verify PR template has all 10 sections

Phase 3 — Triage Gates

• Run /mgw:issue on an issue with validity=invalid → verify needs-info label applied
• Run /mgw:issue on an issue with security=high → verify needs-security-review label applied
• Run /mgw:issue on a feature with no acceptance criteria → verify needs-info gate
• Run /mgw:issue on a well-formed issue → verify mgw:triaged label applied
• Verify triage comment appears on GitHub immediately

Phase 4 — Pipeline Validation

• Run /mgw:run on needs-info issue → verify refusal
• Run /mgw:run on needs-info issue with --force → verify override works
• Run /mgw:run on needs-security-review issue → verify refusal
• Run /mgw:run on needs-security-review issue with --security-ack → verify override
• Verify mgw:in-progress label applied during execution
• Verify mgw:in-progress label removed at completion

Phase 5 — Comment Classification

• Post a resolution-type comment on a needs-info issue → verify detection
• Verify re-triage prompt offered on resolution

Phase 6 — Sync

• Verify labeler.yml creates triage-pipeline label on relevant PRs
• Verify deployed commands match source commands

[snipcodeit]

MGW · triage-complete · 2026-02-27T20:02:59Z

Triage Complete

Scope	large — 12 files across 10 systems
Validity	confirmed
Security	medium — adds security quality gates; touches pipeline execution flow
Route	gsd:quick --full — complete spec in issue body, all files are markdown/YAML
Conflicts	Deployed copies must sync; pipeline_stage consumers need updating

Work begins on branch issue/68-bidirectional-triage-gates.

Affected Files

• .github/ISSUE_TEMPLATE/bug_report.yml
• .github/ISSUE_TEMPLATE/feature_request.yml
• .github/ISSUE_TEMPLATE/architecture_refactor.yml (NEW)
• .github/PULL_REQUEST_TEMPLATE.md
• .github/labeler.yml
• commands/issue.md
• commands/run.md
• commands/review.md
• commands/init.md
• .claude/commands/mgw/workflows/state.md
• .claude/commands/mgw/workflows/github.md
• .claude/commands/mgw/ (deployed copies)

[snipcodeit]

MGW · execution-complete · 2026-02-27T20:50:00Z

Execution Complete

5 atomic commit(s) on branch issue/68-bidirectional-triage-gates.

Changes: 18 files changed, 2661 insertions(+), 72 deletions(-)

Verification: 15/15 must-haves passed

Preparing pull request.

[snipcodeit]

MGW · pr-ready · 2026-02-27T20:50:00Z

PR Ready

PR #69 — #69

Add enforced triage quality gates, immediate GitHub feedback, AI-optimized issue/PR templates, and bidirectional stakeholder engagement loops to the MGW pipeline.

Testing procedures posted on the PR.
This issue will auto-close when the PR is merged.

Pipeline Summary

Stage	Status
Triage	✓
Planning	✓
Plan Check	✓
Execution	✓
Verification	✓ (15/15)
PR Creation	✓