Triage

Triage

Analyze requirements for completeness. Explore code + docs, surface gaps, ask clarifying questions, write a report.

Tracker-agnostic and storage-agnostic: fetching a ticket and choosing where the report lands are both pluggable (see references/sources.md).

Arguments

$ARGUMENTS is a space-separated string. Parse optional flags first, then treat the remainder as the input.

Wrappers may pre-pin any of these — user-passed flags WIN.

Input Detection

After flags are stripped, the remainder selects the requirement source:

Ambiguous → ask. Do NOT guess.

Workflow

1. Resolve input

empty

Prompt: "Paste requirements / spec text, or give a ticket id, URL, or .md path."

.md path

Read file. Use content as input. Title from H1 or filename.

pasted text

Use as-is. Derive title from first line / sentence.

tracker ticket

Read references/sources.md and use the first available fetch path. Never invent a CLI or an API call — if nothing is available, ask the user to paste the ticket text.

Normalize whatever comes back to: title, description, acceptance criteria, state, type, assignee, area/labels, linked items. HTML descriptions → readable text.

2. Explore codebase + docs

Codebase (Explore agent)

• Project structure / architecture
• Existing code that would be modified
• Patterns and conventions
• Related features
• Test coverage patterns

Local docs

docs/, documentation/, wiki/, README.md, CONTRIBUTING.md, ARCHITECTURE.md, OpenAPI specs, ADRs, inline code comments.

External docs (optional)

If a docs search tool is connected (see references/sources.md), search it for related material: by title keywords, by feature / area name, by domain terms from the description, plus any terms in $ARGUMENTS. Look for technical specs, ADRs, related-feature docs, business rules, prior decisions.

No such tool → skip silently, note it in the report only if a gap seems doc-shaped.

3. Assess completeness

Rate: Ready / Mostly Ready / Needs Clarification / Underspecified.

4. Generate questions

Categories:

1. Blockers — must answer before any work
2. Scope clarification — boundaries
3. Technical decisions — implementation
4. Nice to know — non-blocking

5. Ask interactively

Ask the user interactively. 1–4 questions per batch, 2–4 suggested options each. Record answers. Unanswered → output file.

6. Write output

{date} = YYYY-MM-DD. {slug} = with ticket: <ticket-id>-<slugified-title>, else <slugified-title>. Slugify: lowercase, spaces→hyphens, strip special chars, max 40 chars.

Destination, in order:

1. --print set → print markdown to stdout. Done.
2. --out <path> set → write there.
3. Project has an artifact convention (a protocol skill covers it, or an existing folder of reports makes it obvious) → follow it. See references/sources.md.
4. Otherwise ask the user:
   1. Print only (no save) — default
   2. Save to /tmp/triage-{slug}.md
   3. Other path

Output Format

# Triage: [Short title]

**Source**: [Ticket id/URL, file path, or "Manual input"]
**Date**: [YYYY-MM-DD]
**Completeness**: [Ready | Mostly Ready | Needs Clarification | Underspecified]

## Summary

[1-sentence summary]

### Understanding

[2-3 sentences from codebase exploration]

### What's Clear

- ...

### Implicit Requirements (from docs)

- [Reqs found in docs that the requirement assumes but doesn't state]

### Gaps Identified

- ...

### Questions

#### Blockers

1. [Question] — [Why it blocks]

#### Scope Clarification

1. ...

#### Technical Decisions

1. ...

#### Nice to Know

1. ...

Only unanswered questions go in output.

7. Summary to user

• Destination (path, or "printed")
• Completeness rating
• Blocker count

Tips

• Don't ask what code/docs already answer — explore first
• Surface implicit requirements from docs — tickets assume documented knowledge
• 3 critical questions > 10 nice-to-haves
• Frame to unblock decisions, not gather trivia
• Docs contradict ticket → blocker question

Notes

• Read-only against the tracker. Never updates ticket state — that's dev-azdo:ticket (if the dev-azdo plugin is installed) or the platform CLI.
• Tracker and docs recipes live in references/sources.md — load only when the input is a ticket or a docs search is wanted.
• Division of labor with aiwork-protocol: aiwork-protocol decides where the artifact lands; triage decides what goes in it. Both trigger on "triage" — if the user wants a report written, that's this skill.