triage

name	triage
description	Triage VFloat markdown issues through the AFK workflow state machine. Use when evaluating .scratch issues, preparing ready-for-agent briefs, marking ready-for-human, needs-info, wontfix, or managing workflow status.

Triage

Move .scratch issues through the AFK workflow state machine. Triage decides whether an issue is clear enough for issue-worker, needs human input, or should not be actioned.

Every triage note written to an issue must start with:

> _This was generated by AI during triage._

Reference Docs

• .agents/workflows/afk-issue-loop.md - lifecycle and issue contract
• .agents/issue-tracker.md - local markdown tracker layout
• .agents/triage-labels.md - roles and operational statuses
• AGENT-BRIEF.md - durable brief format
• OUT-OF-SCOPE.md - rejected enhancement knowledge base

Roles And Statuses

Two category roles:

• bug - something is broken
• enhancement - new feature or improvement

Triage-owned state roles:

• needs-triage - maintainer or triage agent must evaluate
• needs-info - waiting on human input or reproduction detail
• ready-for-agent - fully specified for issue-worker
• ready-for-human - requires human judgment or implementation
• wontfix - will not be actioned

Operational statuses such as in-progress, ready-for-review, review-blocked, completed, and ready-to-commit are owned by the AFK workflow after triage.

Show What Needs Attention

Query .scratch/**/*.md and present buckets oldest first:

1. Missing Status.
2. needs-triage.
3. needs-info with new comments or changed context.
4. review-blocked items whose follow-up issues are complete.

Show counts and one-line summaries. Let the maintainer pick unless they already named an issue.

Triage A Specific Issue

1. Read the full issue, parent PRD, comments/logs, and blockers.
2. Explore relevant code/docs using VFloat domain language and ADRs.
3. For bugs, attempt reproduction before recommending ready-for-agent.
4. Check .out-of-scope/*.md for similar rejected enhancements.
5. Recommend category and status with concise reasoning.
6. Apply the chosen outcome by editing the issue metadata and appending notes.

Ready-For-Agent Requirements

Only set Status: ready-for-agent when the issue has:

• Category: bug or Category: enhancement
• Assignee: unassigned
• Branch/worktree: not-started
• Parent: pointing to the PRD when applicable
• Blocked by: with concrete issue paths or None
• clear What to build
• testable acceptance criteria
• a complete Agent Brief
• validation expectations
• Work Log, Validation Log, and Review Notes sections

If any requirement is missing, keep the issue needs-triage while adding the missing detail, or use needs-info if the missing detail requires a human.

Outcomes

• ready-for-agent - write or refresh the agent brief, normalize metadata, and leave the issue unassigned.
• ready-for-human - write the same style of brief, but explain why AFK agents cannot safely handle it.
• needs-info - append specific questions under ## Triage Notes.
• wontfix bug - explain why it will not be fixed.
• wontfix enhancement - update .out-of-scope/ and link the decision.
• needs-triage - record partial findings and what remains unresolved.

Needs-Info Template

> _This was generated by AI during triage._

## Triage Notes

**What we've established so far:**

- point 1

**What we still need:**

- specific question 1

Resuming Triage

Read prior triage notes and do not re-ask resolved questions. If the issue already has operational status (in-progress, ready-for-review, or completed), do not move it backward unless the maintainer asks or the issue contract is clearly invalid.