bug-triage

Bug triage

Help the reporter describe what they observed and add useful evidence. A short human

observation is enough to report a bug; reproduction, logs, and a diagnosis are optional.

Use this skill for reports from chat, an existing issue, or a local user.

Clarify the observation

Read the available report, screenshots, and follow-ups first. Preserve the original

reporter's words and attribution, including when someone else relays their report.

Don't infer a GitHub username from a chat display name.

Ask only questions that would materially clarify the symptom, a few at a time. Don't

repeat questions already answered or turn these suggestions into required fields:

• What did you do, and what happened instead of what you expected?
• Where did it happen, and does it happen every time or only sometimes?
• For a visual problem, can you share a screenshot or short recording showing it?
• If relevant, which AO version and OS were you using, and did it start after a change?

If a screenshot is unavailable, accept a description. If the reporter cannot remember

steps or reproduce the problem, preserve that uncertainty and proceed with what is

known. Never invent steps or make the reporter diagnose the bug before accepting it.

Keep the report and investigation separate

Draft a specific symptom-based title and a short body, normally one paragraph or a few

bullets. Include only details supplied directly by the human: their observation,

expected behavior, steps, frequency, environment, and impact when they provided them.

Light editing for clarity is fine; preserve meaning and uncertainty. Omit empty

sections and unnecessary background. Do not add agent-inferred impact, root cause,

confidence scores, or proposed fixes to the report.

Example human report:

> After I switched projects, the terminal stayed blank. I expected to see the session

> prompt. It happened twice today on macOS; I don't know how to reproduce it reliably.

Keep agent-discovered information separate from the human report and label it

Agent-collected evidence, even when it confirms the report. Include only relevant

excerpts and:

• The command or read-only query used, collection time, and relevant AO version or

checkout commit, so another person can interpret the result.

• Observed output, screenshots, or reproduction results, with enough context to verify

the finding. Distinguish the reporter's environment from a separate test build.

• A brief explanation of what the evidence supports and its limits. Label hypotheses

explicitly; don't present a code-path guess as a confirmed cause.

If no useful evidence is available, deliver the human report alone. Never pad it with

speculation or claim a reproduction succeeded when it didn't.

Gather relevant evidence

Use diagnostics that fit the symptom, within the user's requested scope. Prefer

read-only checks against the affected installation. Don't restart sessions, upgrade

AO, change live data, or alter the user's checkout just to collect evidence.

AO uses a Go daemon and an Electron/React frontend. Read docs/architecture.md for

current boundaries and locate actual files with rg before citing code. Do not rely

on the old TypeScript implementation or assume which runtime backs a session.

Before trusting diagnostics, identify the AO executable and affected daemon. A PATH

lookup may resolve to a legacy install. Check the executable's version and status,

and the configured run file/data directory (AO_RUN_FILE / AO_DATA_DIR when set).

The primary daemon normally uses loopback port 3001; port alone does not establish

which version or installation is affected. Consult the installed CLI help for commands.

Collect only what helps explain this symptom:

| Symptom | Potential evidence |

| --- | --- |

| UI rendering or interaction | Screenshot/recording, relevant console errors, affected view |

| Session or terminal state | Affected session's daemon state, relevant log excerpt, runtime details |

| Daemon or CLI failure | Version/status, exact command and error, relevant daemon logs |

| Persisted state mismatch | Relevant rows and schema from a read-only SQLite query |

Use the daemon API/CLI for state first. If database evidence is needed, discover the

actual database location and schema, open it read-only, and select only relevant rows

and columns. Never attach an entire database or broad log dump. Redact tokens,

credentials, private prompts, and unrelated personal or repository data from every

artifact, including screenshots. Keep diagnostic artifacts under ~/.ao and out of

Git commits. Preserve evidentiary content when redacting, and verify that unrelated

content did not change. Share a useful excerpt rather than a wall of output.

Try a safe reproduction when practical, recording the build actually tested. Failure

to reproduce does not invalidate the human report. Code tracing or dependency research

is optional when it can add concrete evidence. Keep findings in the separate evidence.

Check for duplicates

Search open and closed issues and related PRs using the symptom or exact error:

gh issue list --repo Untrivial-ai/agent-orchestrator --state all --search '<symptom or error>'
gh pr list --repo Untrivial-ai/agent-orchestrator --state all --search '<symptom or error>'

Read likely matches before calling a report a duplicate. If one matches, give the

reporter its link and draft only their new observation for a comment, with evidence

attached separately. If a closed issue appears to have regressed, explain that to the

reporter rather than silently treating it as resolved. If search is unavailable,

state that briefly; it does not block preparing the report.

Preserve attribution and submission scope

A local coding agent may help draft and gather attachments. Existing authorization

still applies; triage alone is not permission to publish.

For an existing issue, preserve its human body and attribution. Add evidence separately

when authorized. Don't rewrite the report into an investigation narrative.

When authorized to publish, include useful collected evidence before finishing. Use a

clearly labeled comment or attachment, whichever fits the evidence. If evidence cannot

be published, state the exact blocker and provide its local path. Never invent

attachment URLs or create asset branches to host diagnostics. Keep the report body

limited to human details. Apply only existing, relevant labels; don't add

priority/confidence prose just to fill a template.

Finish with the concise draft (or issue link if submitted), any duplicate link, and

attachment paths/links. Do not automatically file an issue, implement a fix, push a

PR, or spawn a worker. Follow the user's requested scope and the repository's normal

contribution workflow if they separately ask for implementation.