/supergraph:triage

Classify issues with a formal state machine. ready-for-agent is the handoff trigger to the supergraph pipeline.

Announce: "🗂️ /supergraph:triage — classifying issues..."

State Machine

needs-triage
    ├── enough info → [assign category] → ready-for-agent | ready-for-human
    └── missing info → needs-info → [info provided] → ready-for-agent | ready-for-human

ready-for-agent  → supergraph:plan pipeline
ready-for-human  → manual dev / architectural decision needed
wontfix          → closed with reason

Category Roles

Category	When
bug	Observed behavior differs from specified behavior
enhancement	New capability or improvement to existing behavior
question	Needs clarification before any action
spike	Research / proof-of-concept, no production code

State Roles

State	Meaning
needs-triage	Unreviewed — default for new issues
needs-info	Blocked on missing information from reporter
ready-for-agent	Fully specified — safe for /supergraph:plan to consume
ready-for-human	Needs human judgment (architecture, business decision, security)
wontfix	Will not be addressed — reason required

Triage Workflow

For each issue:

1. Read the issue completely.

2. Assign category — bug / enhancement / question / spike.

3. Check readiness for agent:

A bug is ready-for-agent when:

• Steps to reproduce are clear
• Expected vs actual behavior is stated
• Environment info is present (version, OS, config)
• No architectural decision required

An enhancement is ready-for-agent when:

• Acceptance criteria are defined
• Scope is bounded (not open-ended)
• No design decision blocking implementation

If NOT ready → set needs-info and list exactly what's missing (one question per response).

4. Assign state and apply labels via GitHub CLI:

gh issue edit <number> --add-label "bug,needs-info"
gh issue edit <number> --add-label "enhancement,ready-for-agent"
gh issue edit <number> --add-label "wontfix"
# Add comment explaining state change:
gh issue comment <number> --body "Triage: [reason for state]"

5. For ready-for-agent issues — summarize for plan intake:

Issue #N: [title]
Category: bug | enhancement
Acceptance: [1-3 criteria]
Constraints: [any known]
→ /supergraph:plan

Batch Triage

For a backlog of issues:

gh issue list --state open --label "needs-triage" --json number,title,body

Process each in order. Report counts at end:

Triaged: N issues
  ready-for-agent: N  ← entry point for /supergraph:plan
  needs-info: N
  ready-for-human: N
  wontfix: N

Rules

• Never mark ready-for-agent unless acceptance criteria are unambiguous
• ready-for-human for anything requiring architecture, security, or business decisions
• One question at a time for needs-info issues — don't dump all questions at once
• wontfix always requires a reason in the comment