triage-issue

Triage Issue

Investigate a reported problem, find the root cause, and create a GitHub issue with a TDD fix plan. This is a mostly hands-off workflow — minimize questions to the user.

How this differs from nous:debug

• nous:debug (systematic-debugging) is the live root-cause loop in this session.
• triage-issue is the artifact-producing version: it ends with a durable, refactor-proof GitHub issue another agent (or human) can pick up later.

Workflow

1. Capture the problem

Get a brief description from the user. If they have not provided one, ask ONE question: "What's the problem you're seeing?"

Do NOT ask follow-up questions. Start investigating immediately.

2. Explore and diagnose

Use a fresh subagent (or the host's exploration primitive) to deeply investigate the codebase. Find:

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

Look at:

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

3. Identify the fix approach

• The minimal change that fixes the root cause
• Which modules / interfaces are affected
• What behaviors need to be verified by tests
• Whether this is a regression, missing feature, or design flaw

4. Design the TDD fix plan

Create a concrete, ordered list of RED-GREEN cycles. Each cycle is one vertical slice:

• RED — describe a specific test that captures the broken / missing behavior
• GREEN — describe the minimal code change that makes 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. Create the GitHub issue

Create with gh issue create. Do NOT ask the user to review before creating — file it and share the URL.

Issue template

## Problem

Clear description of the bug:
- 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 file paths, line numbers, or implementation details that couple to current code layout. Describe modules, behaviors, and contracts. The issue should remain useful even after major refactors.

## TDD Fix Plan

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

After creating the issue, print the URL and a one-line summary of the root cause.

Rules

• No file paths or line numbers in the issue body.
• Use project domain language (UBIQUITOUS_LANGUAGE.md / CONTEXT.md if present).
• Reproduction steps mandatory for bugs.