triaging-agent-armory-issues

name	triaging-agent-armory-issues
description	Use when triaging, bulk triaging, auditing, or preparing GitHub Issues for nisavid/agent-armory, especially requests mentioning Agent Armory, Issue Tracker Ops, Efficient Coherence, triage depth, label axes, audit-labels, or Armory issue readiness.

Triaging Agent Armory Issues

Armory issue triage extends the generic triage skill. Use triage for the base category/state machine and required AI disclaimer, then apply this Armory-specific label-axis and depth policy.

Core rule: preserve underlying intent, match rigor to unresolved uncertainty, and minimize spend inside that quality boundary.

Required Context

When in the Agent Armory repo, read or verify these surfaces before making tracker writes that depend on current policy:

• AGENTS.md
• docs/agents/issue-tracker.md
• docs/agents/triage-labels.md
• relevant issue body, labels, comments, and linked first-order references when the selected triage depth requires them

If those docs are unavailable, state the context gap and avoid irreversible tracker decisions.

Baseline Axes

Use GitHub Issues labels for the current baseline. Do not switch to GitHub Projects custom fields yet.

Axis	Labels
Category	exactly one of bug, enhancement
State	exactly one of needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix
Depth	at most one of depth:L0, depth:L1, depth:L2, depth:L3
Work kind	prefer one kind:*; use multiple only for deliberate mixed-work issues
Engagement	at most one mode:*
Brief	at most one brief:* when brief state matters
Dependency	at most one dependency:* when dependency state has been checked

Run the baseline audit before bulk dogfooding or when label drift is suspected:

python3.14 tools/issue_tracker_ops.py audit-labels --repo nisavid/agent-armory
python3.14 tools/issue_tracker_ops.py audit-labels --repo nisavid/agent-armory --execute

Depth Policy

Choose the shallowest depth that preserves intent.

• depth:L0: semantic hygiene only. Use for obvious label cleanup or simple tracker normalization without reflective issue analysis.
• depth:L1: critically read the issue body and comments. Brainstorm missing domains, cases, concerns, layers, related work, and intent/spec mismatches.
• depth:L2: include first-order linked issues, docs, PRs, dependencies, or source references.
• depth:L3: focused one-issue session with repo scouting, reproduction, design facilitation, and review as needed.

Bulk triage is normally L0/L1 only. Process issues one at a time, but do not pull deep context into a bulk pass. If an issue needs linked context, code scouting, reproduction, or design facilitation, label the reached depth and route the next engagement with mode:linked-context-triage or mode:deep-session.

Outcome Rules

• Do not mark ready-for-agent merely because the written specification is satisfiable. Confirm the underlying intent is coherent enough for delegation.
• Use needs-info only when waiting on a specific answer, artifact, confirmation, or decision from a reporter or operator.
• Use needs-triage when the next decision depends on unresolved context that is not specifically waiting on a reporter.
• Use ready-for-human when judgment, authority, access, or subjective design choice must happen before implementation.
• Use brief:needed when an issue is otherwise close to delegation but lacks a safe handoff brief.

Triage Record

Every tracker comment posted during triage starts with:

> *This was generated by AI during triage.*

Use a concise triage record when labels, readiness, unresolved factors, or the delegation path would not be obvious from the issue alone:

> *This was generated by AI during triage.*

## Triage Record

**Outcome:** `enhancement` / `ready-for-agent`
**Depth:** `depth:L1`
**Work kind:** `kind:documentation`
**Engagement mode:** `mode:afk-implementation`
**Brief status:** `brief:not-needed`
**Dependency disposition:** `dependency:unblocked`

**Evidence boundary:** issue body and comments.

**Reasoning:** short rationale.

**Unresolved factors:** none, or specific unsettled factors.

**Next action:** concrete next step and owner shape.

Common Mistakes

Mistake	Fix
Treating category/state as complete triage	Set or route the other Armory axes when they matter
Doing L2/L3 work inside a bulk L1 pass	Stop, record the boundary, and route deeper work
Marking poor specs ready because they are implementable	Reconcile the spec with underlying intent first
Asking vague questions	Ask for specific missing evidence or decisions
Posting triage comments without the disclaimer	Add the disclaimer as the first line
Using Projects fields now	Dogfood the GitHub Issues label baseline until Issue Ops adopts richer adapters