troykelly/feedback-triage

Feedback Triage

Overview

Process raw feedback into actionable, well-documented GitHub issues. Every feedback item is investigated before issue creation.

Core principle: Investigate first, issue second. Never create an issue without understanding what you're documenting.

Announce at start: "I'm using feedback-triage to investigate and create issues from this feedback."

When to Use This Skill

Use this skill when you receive:

| Trigger | Examples | |---------|----------| | UAT feedback | "We have bugs from UAT testing..." | | User testing results | "Users reported the following issues..." | | Bug reports | "Here are the errors we found..." | | Stakeholder feedback | "The client wants these changes..." | | QA findings | "QA discovered these problems..." | | Support escalations | "Support tickets about..." | | Production incidents | "These errors are occurring in prod..." | | Feature requests batch | "Users have requested..." | | UX review findings | "The UX review identified..." |

Key indicators:

• Multiple items in one message
• Raw feedback that needs investigation
• Error logs, curl commands, or screenshots
• Requests to "create issues" from feedback
• Phrases like "bugs to resolve", "issues from UAT", "feedback to triage"

The Triage Protocol

┌─────────────────────────────────────────────────────────────────────┐
│                      FEEDBACK RECEIVED                               │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│               STEP 0: PROJECT BOARD READINESS (GATE)                │
│  Verify GITHUB_PROJECT_NUM and GH_PROJECT_OWNER are set             │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    STEP 1: PARSE INTO ITEMS                         │
│  Identify distinct feedback items                                   │
│  Create TodoWrite entry for each item                               │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
                                  ▼
            ┌─────────────────────────────────────────┐
            │         FOR EACH FEEDBACK ITEM          │
            └─────────────────────┬───────────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        ▼                         ▼                         ▼
  ┌───────────┐           ┌─────────────┐           ┌─────────────┐
  │INVESTIGATE│           │  CLASSIFY   │           │   CREATE    │
  │           │──────────▶│             │──────────▶│   ISSUE     │
  │ Research  │           │ Type+Priority│          │ Best Practice│
  └───────────┘           └─────────────┘           └──────┬──────┘
                                                          │
                                                          ▼
                                                   ┌─────────────┐
                                                   │ ADD TO      │
                                                   │ PROJECT     │
                                                   │ BOARD       │
                                                   └─────────────┘

Step 0: Project Board Readiness (GATE)

Before any triage, verify project board infrastructure is ready.

# Derive defaults from GITHUB_PROJECT if provided
if [ -z "$GITHUB_PROJECT_NUM" ] && [ -n "$GITHUB_PROJECT" ]; then
  NUM_CANDIDATE=$(echo "$GITHUB_PROJECT" | sed -E 's#.*/projects/([0-9]+).*#\1#')
  if [ -n "$NUM_CANDIDATE" ] && [ "$NUM_CANDIDATE" != "$GITHUB_PROJECT" ]; then
    export GITHUB_PROJECT_NUM="$NUM_CANDIDATE"
    echo "Derived GITHUB_PROJECT_NUM=$GITHUB_PROJECT_NUM from GITHUB_PROJECT"
  fi
fi

if [ -z "$GH_PROJECT_OWNER" ] && [ -n "$GITHUB_OWNER" ]; then
  export GH_PROJECT_OWNER="$GITHUB_OWNER"
  echo "Derived GH_PROJECT_OWNER=$GH_PROJECT_OWNER from GITHUB_OWNER"
fi

if [ -z "$GH_PROJECT_OWNER" ] && [ -n "$GITHUB_PROJECT" ]; then
  OWNER_CANDIDATE=$(echo "$GITHUB_PROJECT" | sed -E 's#https://github.com/(orgs|users)/([^/]+)/projects/[0-9]+#\2#')
  if [ -n "$OWNER_CANDIDATE" ] && [ "$OWNER_CANDIDATE" != "$GITHUB_PROJECT" ]; then
    export GH_PROJECT_OWNER="$OWNER_CANDIDATE"
    echo "Derived GH_PROJECT_OWNER=$GH_PROJECT_OWNER from GITHUB_PROJECT"
  fi
fi

if [ -z "$GH_PROJECT_OWNER" ]; then
  REMOTE_URL=$(git remote get-url origin 2>/dev/null || true)
  OWNER_CANDIDATE=$(echo "$REMOTE_URL" | sed -E 's#(git@|https://)github.com[:/]+([^/]+)/[^/]+(\.git)?#\2#')
  if [ -n "$OWNER_CANDIDATE" ] && [ "$OWNER_CANDIDATE" != "$REMOTE_URL" ]; then
    export GH_PROJECT_OWNER="$OWNER_CANDIDATE"
    echo "Derived GH_PROJECT_OWNER=$GH_PROJECT_OWNER from git remote"
  fi
fi

# Verify environment variables
if [ -z "$GITHUB_PROJECT_NUM" ]; then
  echo "BLOCKED: GITHUB_PROJECT_NUM not set"
  exit 1
fi

if [ -z "$GH_PROJECT_OWNER" ]; then
  echo "BLOCKED: GH_PROJECT_OWNER not set"
  exit 1
fi

# Verify project is accessible
gh project view "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json > /dev/null 2>&1

Skill: project-board-enforcement

---

Step 1: Parse Feedback into Items

Identify Distinct Items

Read through the feedback and identify each distinct item. Look for:

• Separate headings or sections
• Numbered lists
• Different error messages or behaviors
• Distinct feature requests or changes

Create Tracking List

# Use TodoWrite to track each item
# Example: 3 items from UAT feedback
TodoWrite:
- [ ] Investigate: Family page error (API 500)
- [ ] Investigate: Terminology issue (Children vs Care Recipients)
- [ ] Investigate: Cannot add care recipient (API 500)

Item Summary Table

Create a summary table for the user:

## Feedback Items Identified

| # | Summary | Type (Preliminary) | Severity |
|---|---------|-------------------|----------|
| 1 | Family page error | Bug | High |
| 2 | Terminology needs review | UX/Research | Medium |
| 3 | Cannot add care recipient | Bug | High |

I will investigate each item before creating issues.

---

Step 2: Investigate Each Item

CRITICAL: Never create an issue without investigation. Understanding comes first.

Investigation Protocol by Item Type

For API Errors / Bugs

## Investigation: [Item Title]

### 1. Error Analysis
- Error code: [e.g., INTERNAL_ERROR, 500, 404]
- Error message: [exact message]
- Request endpoint: [URL]
- Request method: [GET/POST/etc.]

### 2. Reproduction
- Can reproduce: [Yes/No]
- Reproduction steps:
  1. [Step 1]
  2. [Step 2]

### 3. Code Investigation
- Relevant files: [paths]
- Likely cause: [hypothesis after code review]
- Related code: [functions/modules involved]

### 4. Impact Assessment
- Users affected: [All/Some/Specific conditions]
- Functionality blocked: [What can't users do?]
- Workaround exists: [Yes/No - describe if yes]

### 5. Classification
- Type: Bug
- Severity: [Critical/High/Medium/Low]
- Priority: [Critical/High/Medium/Low]

For UX/Feature Feedback

## Investigation: [Item Title]

### 1. Current Behavior
- What exists now: [description]
- Where it appears: [URLs/screens]
- Current implementation: [code locations]

### 2. Requested Change
- What's being asked for: [description]
- User impact: [how this affects users]
- Business context: [why this matters]

### 3. Scope Analysis
- Files affected: [list]
- Complexity: [Low/Medium/High]
- Dependencies: [other features/systems]

### 4. Design Considerations
- Options identified:
  1. [Option A] - [pros/cons]
  2. [Option B] - [pros/cons]
- Recommendation: [if clear]
- Needs: [Design input / Product decision / Research]

### 5. Classification
- Type: Feature / Research / UX Enhancement
- Priority: [Critical/High/Medium/Low]

For Production Incidents

## Investigation: [Item Title]

### 1. Incident Details
- First reported: [timestamp]
- Frequency: [One-time/Intermittent/Constant]
- Environment: [Production/Staging/etc.]

### 2. Error Analysis
- Error logs: [key log entries]
- Stack trace: [if available]
- Affected service: [component/service name]

### 3. Impact Assessment
- Users affected: [count/percentage]
- Revenue impact: [if applicable]
- SLA implications: [if applicable]

### 4. Root Cause Analysis
- Hypothesis: [likely cause]
- Evidence: [supporting data]
- Related changes: [recent deployments/changes]

### 5. Classification
- Type: Bug
- Severity: Critical / High
- Priority: Critical / High

Investigation Checklist

For each item, verify:

• [ ] Error/behavior understood
• [ ] Code reviewed (if applicable)
• [ ] Scope assessed
• [ ] Impact evaluated
• [ ] Type determined (Bug/Feature/Research/etc.)
• [ ] Priority determined
• [ ] Ready to create issue

---

Step 3: Classify Each Item

Type Classification

| Type | When to Use | Project Board Type | |------|-------------|-------------------| | Bug | Something broken, not working as designed | Bug | | Feature | New capability, clear requirements | Feature | | Research | Needs exploration, design thinking, options analysis | Research | | Spike | Time-boxed technical investigation | Spike | | Chore | Maintenance, cleanup, non-user-facing | Chore | | UX Enhancement | Improving existing user experience | Feature |

Priority Classification

| Priority | Criteria | Response | |----------|----------|----------| | Critical | Production down, data loss, security breach | Immediate | | High | Major feature broken, significant user impact, blocking | This sprint | | Medium | Feature degraded, workaround exists, important but not blocking | Next sprint | | Low | Minor issue, cosmetic, nice-to-have | Backlog |

Severity vs Priority

• Severity = How bad is the problem? (Technical assessment)
• Priority = How soon should we fix it? (Business decision)

A low-severity bug affecting a VIP customer may be high priority. A high-severity bug on a deprecated feature may be low priority.

---

Step 4: Create Well-Formed Issues

Issue Template: Bug

gh issue create \
  --title "[Bug] [Concise description of the problem]" \
  --body "## Summary

[One-sentence description of the bug]

## Environment

- **URL:** [affected URL]
- **Environment:** [Production/Staging/Local]
- **Browser/Client:** [if relevant]

## Steps to Reproduce

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Expected Behavior

[What should happen]

## Actual Behavior

[What actually happens]

## Error Details

\`\`\`
[Error message, status code, or log output]
\`\`\`

## Investigation Findings

### Code Analysis
- **Affected files:** [list of files]
- **Likely cause:** [hypothesis]
- **Related code:** [functions/modules]

### Impact
- **Users affected:** [scope]
- **Functionality blocked:** [what can't users do]
- **Workaround:** [if any]

## Acceptance Criteria

- [ ] Error no longer occurs
- [ ] [Specific behavior restored]
- [ ] Tests added to prevent regression

## Technical Notes

[Any additional technical context from investigation]

---
**Source:** UAT Feedback / User Report / Support Ticket
**Reported:** [DATE]"

Issue Template: Feature / UX Enhancement

gh issue create \
  --title "[Feature] [Clear description of the feature]" \
  --body "## Summary

[One-sentence description of what this feature does]

## Background

[Why this is needed - user feedback, business requirement, etc.]

## Current Behavior

[What exists today, if anything]

## Proposed Behavior

[What should happen after implementation]

## User Story

As a [type of user], I want [goal] so that [benefit].

## Investigation Findings

### Scope Analysis
- **Files affected:** [list]
- **Complexity:** [Low/Medium/High]
- **Dependencies:** [related features/systems]

### Design Considerations
[Options considered, recommendations, questions]

## Acceptance Criteria

- [ ] [Specific, verifiable criterion 1]
- [ ] [Specific, verifiable criterion 2]
- [ ] [Specific, verifiable criterion 3]

## Out of Scope

- [What this issue will NOT address]

## Technical Notes

[Implementation hints, patterns to follow, etc.]

---
**Source:** UAT Feedback / User Request / Stakeholder Input
**Requested:** [DATE]"

Issue Template: Research / Spike

gh issue create \
  --title "[Research] [What needs to be understood]" \
  --body "## Summary

[One-sentence description of what needs to be researched]

## Background

[Why this research is needed]

## Questions to Answer

1. [Question 1]
2. [Question 2]
3. [Question 3]

## Investigation Context

[What was discovered during initial triage that prompted this research]

## Scope

### In Scope
- [Topic 1]
- [Topic 2]

### Out of Scope
- [Not covering X]

## Deliverables

- [ ] Document with findings
- [ ] Recommendations for next steps
- [ ] [Specific output, e.g., design options, architecture diagram]

## Time Box

[Suggested time limit: e.g., 4 hours, 1 day]

## Acceptance Criteria

- [ ] All questions answered with evidence
- [ ] Recommendations documented
- [ ] Next steps identified (issues to create)

---
**Source:** UAT Feedback / Triage Investigation
**Created:** [DATE]"

---

Step 5: Add to Project Board (MANDATORY)

Every issue MUST be added to the project board with correct fields.

# After creating issue, add to project
ISSUE_URL=$(gh issue view [ISSUE_NUMBER] --json url -q '.url')
gh project item-add "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --url "$ISSUE_URL"

# Get item ID
ITEM_ID=$(gh project item-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r ".items[] | select(.content.number == [ISSUE_NUMBER]) | .id")

# Get field IDs
PROJECT_ID=$(gh project list --owner "$GH_PROJECT_OWNER" --format json | \
  jq -r ".projects[] | select(.number == $GITHUB_PROJECT_NUM) | .id")

STATUS_FIELD_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r '.fields[] | select(.name == "Status") | .id')

TYPE_FIELD_NAME="Type"
if ! gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json | jq -e '.fields[] | select(.name == "Type")' >/dev/null 2>&1; then
  if gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json | jq -e '.fields[] | select(.name == "Issue Type")' >/dev/null 2>&1; then
    TYPE_FIELD_NAME="Issue Type"
  fi
fi

TYPE_FIELD_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r --arg type_field "$TYPE_FIELD_NAME" '.fields[] | select(.name == $type_field) | .id')

PRIORITY_FIELD_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r '.fields[] | select(.name == "Priority") | .id')

# Set Status = Ready (or Backlog for lower priority)
READY_OPTION_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r '.fields[] | select(.name == "Status") | .options[] | select(.name == "Ready") | .id')

gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
  --field-id "$STATUS_FIELD_ID" --single-select-option-id "$READY_OPTION_ID"

# Set Type (Bug, Feature, Research, etc.)
TYPE_OPTION_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r --arg type_field "$TYPE_FIELD_NAME" --arg type_value "[TYPE]" '.fields[] | select(.name == $type_field) | .options[] | select(.name == $type_value) | .id')

gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
  --field-id "$TYPE_FIELD_ID" --single-select-option-id "$TYPE_OPTION_ID"

# Set Priority
PRIORITY_OPTION_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r ".fields[] | select(.name == \"Priority\") | .options[] | select(.name == \"[PRIORITY]\") | .id")

gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
  --field-id "$PRIORITY_FIELD_ID" --single-select-option-id "$PRIORITY_OPTION_ID"

# Verify
echo "Issue #[ISSUE_NUMBER] added to project with Status=Ready, Type=[TYPE], Priority=[PRIORITY]"

Skill: project-board-enforcement

---

Step 6: Summary Report

After all items are triaged, provide a summary:

## Triage Complete

### Issues Created

| # | Issue | Type | Priority | Status |
|---|-------|------|----------|--------|
| 1 | #123 - Family page API error | Bug | High | Ready |
| 2 | #124 - Kin Circle terminology research | Research | Medium | Ready |
| 3 | #125 - Cannot add care recipient | Bug | High | Ready |

### Project Board Status
All issues added to project board with correct fields.

### Recommended Order
1. **#123** - Blocking user access to family page
2. **#125** - Blocking care recipient management
3. **#124** - UX research can proceed in parallel

### Next Steps
- [ ] Assign issues to developers
- [ ] Begin work using `issue-driven-development`
- [ ] Or request immediate resolution

---

Example: Processing UAT Feedback

Input Received

We have some bugs to resolve from UAT.

## Family Page has error
`https://stage.kin.life/family`
Displays: Something went wrong on our end.
[curl command and error response]

## Family Page refers to "Children" - not Care Recipients
Need better terminology, research required.

## Family Page unable to add care recipient
[curl command and error response]

Triage Process

Step 1: Parse into items

• Item 1: Family page 500 error on load
• Item 2: Terminology issue (Children vs Care Recipients)
• Item 3: Cannot add care recipient (500 error)

Step 2: Investigate each

Item 1 Investigation:

• API endpoint: /api/v1/children?limit=50
• Error: INTERNAL_ERROR
• Code review: Check children service, database queries
• Impact: Users cannot view family page at all

Item 2 Investigation:

• Current: Hardcoded "Children" but button says "care recipient"
• Request: More inclusive language for diverse care relationships
• Scope: UI changes, possibly data model changes
• Needs: UX research, product decision

Item 3 Investigation:

• API endpoint: POST /api/v1/children
• Payload: Valid care recipient data
• Error: INTERNAL_ERROR
• Code review: Check creation endpoint, validation, database writes
• Impact: Users cannot add any care recipients

Step 3: Classify

| Item | Type | Priority | Reasoning | |------|------|----------|-----------| | 1 | Bug | High | Core functionality broken | | 2 | Research | Medium | UX improvement, not blocking | | 3 | Bug | High | Core functionality broken |

Step 4: Create issues (using templates above)

Step 5: Add to project board (with Type, Priority, Status)

Step 6: Summary report (as shown above)

---

Best Practices for Issue Quality

Title Conventions

| Type | Format | Example | |------|--------|---------| | Bug | [Bug] <What is broken> | [Bug] Family page returns 500 error | | Feature | [Feature] <What it does> | [Feature] Add person to Kin Circle | | Research | [Research] <What to investigate> | [Research] Inclusive terminology for care relationships | | Spike | [Spike] <Technical question> | [Spike] Evaluate API caching strategies |

Acceptance Criteria Quality

Good criteria are:

• Specific and verifiable
• Written as checkboxes
• Focused on behavior, not implementation
• Testable

Bad:

• [ ] Fix the bug
• [ ] Make it work

Good:

• [ ] GET /api/v1/children returns 200 with valid data
• [ ] Family page displays list of care recipients
• [ ] Error state shows user-friendly message with retry option

Investigation Documentation

Always document:

• What you found
• Where you looked
• What the likely cause is
• What the impact is

This saves time when implementation begins.

---

Handling Unclear Feedback

When Feedback is Vague

If feedback lacks detail:

1. Ask clarifying questions before creating issue
2. Create Research issue to gather more information
3. Document what IS known in the issue

Clarification Template

Before I create issues for this feedback, I need clarification:

1. **[Item 1]:** [Question about scope/expected behavior/reproduction]
2. **[Item 2]:** [Question about priority/business context]

Once clarified, I'll complete the investigation and create properly-formed issues.

When to Create Research Issues

Create a Research issue instead of Bug/Feature when:

• Requirements are unclear
• Multiple solutions exist
• Design decisions needed
• User research required
• Technical feasibility unknown

---

Integration with Other Skills

This skill flows TO:

| Skill | When | |-------|------| | issue-driven-development | After issues created, to begin resolution | | issue-decomposition | If a feedback item is too large for one issue | | epic-management | If feedback items should be grouped as epic |

This skill uses:

| Skill | For | |-------|-----| | project-board-enforcement | Adding issues to project board | | pre-work-research | Investigation patterns | | issue-prerequisite | Issue quality standards |

---

Memory Integration

Store triage sessions in knowledge graph:

mcp__memory__create_entities([{
  "name": "Triage-[DATE]-[SOURCE]",
  "entityType": "FeedbackTriage",
  "observations": [
    "Source: UAT / User Report / etc.",
    "Date: [DATE]",
    "Items received: [COUNT]",
    "Issues created: #X, #Y, #Z",
    "Types: [Bug: N, Feature: N, Research: N]",
    "High priority: [COUNT]"
  ]
}])

---

Checklist

Before Starting Triage

• [ ] Project board readiness verified (GITHUB_PROJECT_NUM, GH_PROJECT_OWNER)
• [ ] Feedback source identified
• [ ] All items parsed and listed

For Each Item

• [ ] Investigation complete (not skipped)
• [ ] Error/behavior understood
• [ ] Code reviewed (for bugs)
• [ ] Scope assessed
• [ ] Impact evaluated
• [ ] Type classified (Bug/Feature/Research/etc.)
• [ ] Priority assigned
• [ ] Issue created with full template
• [ ] Added to project board
• [ ] Status field set (Ready or Backlog)
• [ ] Type field set
• [ ] Priority field set

After All Items

• [ ] Summary report provided
• [ ] All issues in project board verified
• [ ] Recommended priority order given
• [ ] Memory updated
• [ ] Ready for resolution (if requested)

Gate: No issue is created without investigation. No issue is left outside the project board.

---

Proceeding to Resolution

If the user requests resolution after triage:

Issues have been created and prioritized.

**To resolve these issues:**

1. I will work through them using `issue-driven-development`
2. Starting with highest priority: #[N]
3. Each issue will follow the full development process

Shall I proceed with resolution, or should these be assigned for later work?

If proceeding, invoke issue-driven-development for each issue in priority order.