Agent ops triage

Triage

Use a focused file-based todo triage workflow that sits between finding generation and implementation. Preserve the imported compound-engineering todo-approval flow, but keep routing narrow so generic issue triage, review, and execution stay with their correct owners.

Table of Contents

• Standards snapshot
• When to use
• When not to use
• Required inputs
• Deliverables
• Workflow
• Decision outcomes
• Routing map
• Upstream preservation
• Validation
• Constraints
• Examples
• Remember
• Gotchas
• Failure mode

Standards snapshot

• Treat todos/ artifacts as the source of truth for this workflow.
• Triage is a decision stage, not an implementation stage. Do not code fixes here.
• Default review-created findings start pending; triage decides whether they become ready, get skipped, or need light edits before approval.
• Keep one item in focus at a time unless the user explicitly wants a batch summary.
• Preserve exact status transitions in both filename and frontmatter so downstream execution can trust the backlog.

Philosophy

• Keep triage narrow and decision-centric.
• Prefer explicit, reversible state transitions over implicit backlog edits.
• Promote only items with enough evidence to be executable.
• Preserve queue quality over queue volume.

When to use

• The repo already has file-based todos/ items and the user wants pending findings triaged before work begins.
• The user wants review findings approved, skipped, or lightly adjusted before they enter the execution queue.
• A review or audit produced findings that should be converted into actionable todo state without implementing them yet.
• The user wants the missing approval bridge between he-code-review findings and he-work execution.

When not to use

• Do not use for generic product or issue-tracker triage. Use gh-workflow.
• Do not use to create findings from a review. Use he-code-review.
• Do not use to execute approved todo work. Use he-work.
• Do not use when the repo has no todos/ workflow and the user is asking for generic prioritization advice.

Required inputs

• A repo with a todos/ directory or a supplied findings list that should enter that workflow.
• Optional selector:
  • all pending todos
  • specific todo IDs
  • specific finding list
• Any preference for:
  • prompt-per-item interactive triage
  • bulk summary first
  • default skip behavior when evidence is weak

Deliverables

• A discovered set of candidate findings or pending todo items.
• Per-item triage outcomes:
  • ready
  • skipped
  • customized
  • blocked
• Renamed todo files and updated frontmatter for approved items.
• Deleted or intentionally preserved skipped items, depending on the repo workflow and user intent.
• A final summary with counts, affected files, and the next recommended workflow step.
• If requested, a structured status report matching Infrastructure/references/contract.yaml with schema_version: 1.

Workflow

1. Discover the triage source.
   • Prefer existing todos/*-pending-*.md items when the repo already uses the file-based workflow.
   • If the user supplied a findings list instead, use it to create or update pending todo entries before approval.
2. Read each candidate item fully before deciding.
   • Capture status, priority, issue ID, dependencies, findings, proposed solutions, and acceptance criteria.
3. Present one item at a time unless the user explicitly asks for a bulk review.
   • Include title, severity, category, location, problem scenario, proposed solution, and effort.
   • Offer the triage decision set: yes, next, or custom.
4. Apply the decision without coding.
   • yes: promote pending to ready and update the filename/frontmatter.
   • next: skip the item and remove it from the pending queue according to the local file-todo workflow.
   • custom: adjust priority, description, or details, then confirm again before promotion.
5. Continue until all items are processed.
6. Return a final summary and route cleanly to the next stage.
   • Approved work -> he-work
   • New findings needed -> he-code-review
   • Tracker-level triage -> linear

Decision outcomes

• yes
  • Rename {id}-pending-{priority}-{desc}.md to {id}-ready-{priority}-{desc}.md.
  • Update frontmatter status: pending -> status: ready.
  • Add or update the work-log entry that records triage approval.
• next
  • Remove the item from the active triage queue.
  • When the repo uses the CE file-todo lifecycle, delete the skipped pending file rather than leaving stale backlog noise.
• custom
  • Adjust the minimum needed details such as priority, short description, tags, or recommended action.
  • Re-present the revised item before promoting it to ready.
• blocked
  • Keep the item pending when user intent, evidence, or dependencies are not strong enough for approval.

Routing map

• Read Infrastructure/references/overlap-matrix.md before widening this skill's trigger wording.
• Use he-code-review to generate findings and initial pending todo artifacts.
• Use he-work once approved items are ready.
• Use gh-workflow for team tracker triage and issue updates.

Upstream preservation

• The imported compound-engineering source is preserved in Infrastructure/references/upstream-triage.md.
• The local install keeps the core upstream flow:
  • present findings one by one
  • decide yes | next | custom
  • update todo state without coding
  • summarize approved and skipped work
• The local adaptation narrows the routing to file-based todos/, aligns the lifecycle with he-code-review and he-work, and removes legacy tool/runtime assumptions like /model Haiku.

Validation

• Verify the repo actually has a todos/ workflow before using this skill as the primary lane.
• Verify each approved item updates both filename and frontmatter status consistently.
• Verify no code implementation happened during triage.
• Verify skipped items were handled according to the repo's file-todo lifecycle instead of being left as silent backlog drift.
• Verify the final summary names the correct next workflow stage.
• Fail fast at the first broken gate.

Constraints

• Do not implement fixes or code changes during triage.
• Do not silently convert generic tracker triage into file-based todo mutations.
• Do not promote an item to ready without enough evidence to make it actionable.
• Do not leave filename/frontmatter drift after a status change.
• Redact secrets, credentials, and sensitive data from todo artifacts and summaries.

Anti-patterns

• Approving items because they sound plausible without checking the source artifact.
• Editing code while in triage to "quickly resolve" an item.
• Bulk-promoting todos without confirming status/priority metadata integrity.
• Leaving skipped items in place when local lifecycle requires deletion.

Examples

• "Triage the pending todo findings in this repo and tell me which ones are ready for work."
• "Go through these review findings one by one and approve the ones that should enter the todo queue."
• "Review all todos/*-pending-*.md items, let me skip weak ones, and move the good ones to ready."
• "Use triage after code review, but do not implement anything yet."

Remember

• Triage is a decision checkpoint, not a coding checkpoint.
• The whole point is to leave the backlog cleaner and more executable than it was before.

Gotchas

• The upstream skill name is broader than the actual workflow. Locally, treat it as file-based todo triage, not universal issue triage.
• This repo routes execution through he-work, so triage should stop after approval rather than drifting into execution.
• If the repo has no todos/ directory, this skill should usually route elsewhere instead of inventing a file-based workflow.

Failure mode

• If there is no usable todos/ workflow or findings source, stop and name the smallest missing input.
• If the request is really tracker triage, review generation, or execution, route to the correct skill instead of stretching this one.
• If candidate items are too underspecified to approve safely, keep them pending and say exactly what is missing.

See Also

Skill	When to use
[[ce-work]]	Execute the approved work once triage decisions are made
[[he-work]]	Execute approved todo items after triage decisions are finalized
[[he-fix-bugs]]	Diagnose unclear or flaky findings before deciding whether they belong in the queue

Topic map: [[agent-ops]]