Triage Issue

Triage Issue

Upstream: Adapted from mattpocock/skills/triage-issue. Adapted to use this repo's Explore agent, tdd/ skill, and cc-linear/gh integration.

Investigate a reported problem, find the root cause, and create a tracker issue with a TDD fix plan. This skill does NOT apply the fix — it produces a durable, grabbable issue that /si or another agent can pick up later.

Resolve the task with ../setup/references/task-context.md before investigation. Reuse the linked task or create the minimum record in the configured root; for diagnosis/body-only mode, return the proposed path without writing. Link the issue/body, root-cause evidence, current state, and one next action from that record. The explicit triage request remains the authorization for the selected tracker write.

The request to triage and file authorizes one issue write in the resolved tracker destination. If the user asks for diagnosis or a draft only, choose the "Skip — output the body only" path and do not create an issue. Resolve the tracker and repository/team before creating anything.

Process

1. Capture the problem

If the user has not described the issue, ask one question:

"What's the problem you're seeing?"

Do not ask follow-ups yet. Start investigating immediately.

2. Explore and diagnose

Use the Agent tool with subagent_type=Explore to investigate the codebase. Goal:

• Where the bug manifests (entry points, UI, API responses)
• What code path is involved (trace the flow)
• Why it fails (root cause, not symptom)
• What related code exists (similar patterns, tests, adjacent modules)

Look at:

• Related source files and their dependencies
• Existing tests (what's tested, what's missing)
• Recent changes to affected files (git log on relevant files)
• Error handling in the code path
• Similar patterns elsewhere in the codebase that work correctly

Load product-docs/UBIQUITOUS_LANGUAGE.md if it exists — use its terms in the issue body.

3. Identify the fix approach

Based on investigation, determine:

• The minimal change needed to fix the root cause
• Which modules/interfaces are affected (use .claude/skills/architecture-language/LANGUAGE.md vocabulary — module, interface, seam)
• What behaviors need to be verified via tests
• Whether this is a regression, missing feature, or design flaw

4. Design TDD fix plan

Create an ordered list of RED-GREEN cycles aligned with .claude/skills/tdd/SKILL.md. Each cycle is one vertical slice:

• RED: a specific test that captures the broken/missing behavior
• GREEN: the minimal code change to make that test pass

Rules:

• Tests verify behavior through public interfaces, not implementation details
• One test at a time, vertical slices (NOT all tests first, then all code)
• Each test should survive internal refactors
• Include a final refactor step if needed
• Durability: only suggest fixes that would survive radical codebase changes. Describe behaviors and contracts, not internal structure. Tests assert on observable outcomes (API responses, UI state, user-visible effects), not internal state. A good suggestion reads like a spec; a bad one reads like a diff.

5. Pick the tracker

If this repo uses Linear (look for cc-linear config / Linear references in recent issues / LINEAR_TEAM_ID in env), invoke /cc-linear to file the issue. Otherwise use gh issue create.

If unclear, ask once: AskUserQuestion: "File via Linear or GitHub Issues?" Options: "Linear" / "GitHub" / "Skip — output the body only". Keep that destination for the issue and do not silently switch trackers.

6. Create the issue

Use the template below. Do NOT ask the user to review before creating — file it and share the URL.

## Problem

A clear description of the bug or issue, including:
- What happens (actual behavior)
- What should happen (expected behavior)
- How to reproduce (if applicable)

## Root Cause Analysis

What you found during investigation:
- The code path involved
- Why the current code fails
- Any contributing factors

Do NOT include specific file paths, line numbers, or implementation details
that couple to current code layout. Describe modules, behaviors, and contracts
instead. The issue should remain useful even after major refactors.

## TDD Fix Plan

A numbered list of RED-GREEN cycles:

1. **RED**: Write a test that [describes expected behavior]
   **GREEN**: [Minimal change to make it pass]

2. **RED**: Write a test that [describes next behavior]
   **GREEN**: [Minimal change to make it pass]

...

**REFACTOR**: [Any cleanup needed after all tests pass]

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] All new tests pass
- [ ] Existing tests still pass

## Handoff

Pick up with `/si <this issue>` to implement.

After creating the issue, link its URL and the one-line root-cause summary from the selected task record, then print them.

Completion

The triage is complete when the root cause, behavior-level TDD plan, acceptance criteria, and handoff are present in the issue body and a URL is printed. In body-only mode, return the same complete body and label it unfiled. A diagnosis or proposed plan alone is not a created issue.

Scope boundaries

• Does NOT apply the fix (handoff to /si)
• Does NOT include file paths or line numbers in the issue body
• Does NOT ask follow-up questions during investigation — go to the code first
• Does NOT use this for interactive debugging — that's /dbg
• Does NOT use this for batch bug-reporting sessions — that's /qa

Distinction from sibling skills