/gaia-triage-findings

user-facing
Category:
Development
Lifecycle phase:
4 -- Implementation
Arguments:
[story-key?] [--all]

What it does

/gaia-triage-findings scans story files for development findings and triages each into a new backlog story, an existing story, or dismisses it. New stories are created with complete frontmatter and registered in the backlog. Source story findings tables are preserved for idempotent re-triage. After triage completes, the command runs a built-in tech-debt phase that classifies, scores, and ages the surviving debt items and writes a rolling dashboard.

By default the scan is scoped to the active sprint -- only the committed stories of the current sprint (resolved from sprint-status.yaml) are read. Pass --all for a full historical sweep across every story file.

This command is a mandatory sprint-close prerequisite: a sprint cannot be closed until triage has run for it. The close sequence is review → triage → retro → close.

When to use it

  • After implementing stories, findings may have accumulated in the Findings tables. This command triages them into actionable work.
  • At sprint close -- triage is a required step before the sprint can be closed.
  • You want a refreshed technical-debt dashboard. The tech-debt phase that builds it now runs as part of this command (it absorbed the former standalone tech-debt-review command).

Prerequisites

  • Story files with findings. At least some stories must have populated Findings tables.

How to invoke

/gaia-triage-findings

Scans the active sprint's committed stories only (the default). Or sweep every story file historically:

/gaia-triage-findings --all

Or target a single story by its key:

/gaia-triage-findings <story-key>

What it does step by step

  1. Resolve scope By default, reads the active sprint's committed story list from sprint-status.yaml and limits the scan to those stories. With --all, scans every story file instead.
  2. Scan for findings Uses a deterministic findings extractor that reads only story frontmatter and the Findings section -- never the full story body. This keeps the scan within a bounded token budget regardless of how large the stories are.
  3. Present findings Groups findings by severity (critical first) and shows type, severity, description, and suggested action.
  4. Triage each finding For each finding, recommends CREATE STORY, ADD TO EXISTING, or DISMISS. Requires a reproduction command for actionable findings. Protects done stories from mutation.
  5. Create backlog stories For CREATE STORY decisions, delegates to /gaia-create-story with provenance tracking.
  6. Mark findings Appends [TRIAGED] or [DISMISSED] markers to processed findings.
  7. Tech-debt phase After triage, runs the absorbed tech-debt review. Assigns stable TD-{N} identifiers; classifies each surviving debt item as DESIGN, CODE, TEST, or INFRASTRUCTURE; scores by Impact and Risk minus Effort; computes sprint aging; detects STALE TARGET, UNASSIGNED, and RESOLVED items; merges duplicates; and writes the rolling dashboard to .gaia/artifacts/implementation-artifacts/tech-debt-dashboard.md with a trend comparison against the previous run.
  8. Summary Reports triage totals and tech-debt dashboard metrics, and suggests next actions for urgent findings.

Inputs

InputSourceDescription
Story files.gaia/artifacts/implementation-artifacts/Frontmatter and Findings sections only (deterministic, token-budget-protected extractor).
Sprint trackingsprint-status.yamlActive sprint's committed story list (default scope) and current sprint ID for tech-debt aging.
Epics and stories.gaia/artifacts/planning-artifacts/epics-and-stories.mdFor determining epic context and next story keys.
Previous dashboardtech-debt-dashboard.mdPrior TD-{N} IDs and totals for the tech-debt phase's trend comparison.

Outputs

OutputLocationDescription
New backlog stories.gaia/artifacts/implementation-artifacts/Stories created from findings.
Updated source stories.gaia/artifacts/implementation-artifacts/Findings marked as triaged or dismissed.
Updated epics-and-stories.gaia/artifacts/planning-artifacts/epics-and-stories.mdNew stories appended under the correct epic.
Tech-debt dashboard.gaia/artifacts/implementation-artifacts/tech-debt-dashboard.mdRolling dashboard with scores, aging, and trend comparison, written by the tech-debt phase.

Example session

> /gaia-triage-findings

Scanning story files... 12 untriaged findings across 5 stories.

Finding 1 (CRITICAL, bug): E3-S7 -- Auth token not invalidated on logout.
  Reproduction: curl -X POST /logout; curl -H "Authorization: Bearer $TOKEN" /me  # expect 401, got 200
  Recommendation: CREATE STORY (NOW -- inject into current sprint)
  Confirm? yes
  Creating E3-S15 via /gaia-create-story...

Finding 2 (MEDIUM, tech-debt): E5-S12 -- Hardcoded retry delay.
  Recommendation: CREATE STORY (BACKLOG)
  Confirm? yes

Summary: 12 findings processed. 4 stories created, 3 added to existing, 5 dismissed.
2 stories marked as NOW -- run /gaia-correct-course to inject them.

What to run next

Troubleshooting

"No findings to triage"

No story files have untriaged entries in their Findings tables.

"reproduction required"

A finding cannot be promoted to a story without a runnable reproduction command. Supply one at the prompt or dismiss the finding.