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:

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.

# 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

Priority Classification

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_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r '.fields[] | select(.name == "Type") | .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 ".fields[] | select(.name == \"Type\") | .options[] | select(.name == \"[TYPE]\") | .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

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

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:

This skill uses:

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.