Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 32 additions & 22 deletions skills/bug-triage/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,18 @@ one), never a bare PATH lookup.
## 1. Pre-flight

- **Pull latest code:** `git pull origin main`. Stale code = bad triage.
- **Target repo:** Always file on **`aoagents/ReverbCode`** (the product repo, not
a fork). ReverbCode is the product, not a thin fork of upstream.
- **Resolve the target repo** and use `$REPO` for every `gh` call in this skill:

```bash
REPO="${AO_TRIAGE_REPO:-$(gh repo view --json nameWithOwner -q .nameWithOwner)}"
```

Derived from the checkout, so duplicate search and issue filing hit the repo
you are actually triaging in. Set `AO_TRIAGE_REPO` only when issues belong on
a different repo than the checkout (e.g. `AO_TRIAGE_REPO=aoagents/ReverbCode`
to file on the product repo from a fork), or when triaging without a local
clone (Appendix B), where `gh repo view` has no checkout to read.

- **Verify your binary:** confirm `ao status` shows port **3001** (see warning above).
- **Record source:** chat URL, reporter name, attachments.

Expand All @@ -63,7 +73,7 @@ one), never a bare PATH lookup.
| Source | How to gather |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Discord/Slack thread** | Read full thread. Extract: reporter name, original description (the thread starter, not whoever tagged you), screenshots, follow-ups |
| **GitHub issue** | `gh issue view <number> --repo aoagents/ReverbCode --json body,comments` |
| **GitHub issue** | `gh issue view <number> --repo "$REPO" --json body,comments` |
| **Live observation** | Pull live state via the daemon: `ao status`, `ao session ls`, `ao session get <id>` |

### 2b. Minimum viable report gate
Expand Down Expand Up @@ -177,16 +187,16 @@ Stop and ask for more info if:
Search with multiple strategies, always using `--state all` (closed bugs regress):

```bash
gh issue list --repo aoagents/ReverbCode --state all --search "<symptom>"
gh issue list --repo aoagents/ReverbCode --state all --search "<component-name>"
gh issue list --repo aoagents/ReverbCode --state all --search "<error-message>"
gh pr list --repo aoagents/ReverbCode --state all --search "<keywords>"
gh issue list --repo "$REPO" --state all --search "<symptom>"
gh issue list --repo "$REPO" --state all --search "<component-name>"
gh issue list --repo "$REPO" --state all --search "<error-message>"
gh pr list --repo "$REPO" --state all --search "<keywords>"
```

### Duplicate found → comment on existing issue

```bash
gh issue comment <number> --repo aoagents/ReverbCode --body "$(cat <<'EOF'
gh issue comment <number> --repo "$REPO" --body "$(cat <<'EOF'
## New Report
**Reported by:** @<reporter> in [chat](<url>)
**Date:** <YYYY-MM-DD> | **Checkout:** `<commit-hash>`
Expand Down Expand Up @@ -217,23 +227,23 @@ EOF
```bash
SLUG="descriptive-slug"
# Create asset branch
gh api -X POST repos/aoagents/ReverbCode/git/refs \
gh api -X POST "repos/$REPO/git/refs" \
-f ref="refs/heads/issue-assets-${SLUG}" \
-f sha=$(git rev-parse origin/main)

# Upload (portable base64)
IMG_B64=$(base64 < /path/to/screenshot.png | tr -d '\n')
gh api -X PUT "repos/aoagents/ReverbCode/contents/.issue-assets/${SLUG}/name.png" \
gh api -X PUT "repos/$REPO/contents/.issue-assets/${SLUG}/name.png" \
-f message="chore: upload screenshot" \
-f content="$IMG_B64" \
-f branch="issue-assets-${SLUG}"
# Use: ![screenshot](https://raw.githubusercontent.com/aoagents/ReverbCode/issue-assets-<slug>/.issue-assets/<file>)
# Use: ![screenshot](https://raw.githubusercontent.com/$REPO/issue-assets-<slug>/.issue-assets/<file>)
```

### 5c. Create the issue

```bash
gh issue create --repo aoagents/ReverbCode --title "<title>" --body "$(cat <<'EOF'
gh issue create --repo "$REPO" --title "<title>" --body "$(cat <<'EOF'
## Bug
<summary>

Expand All @@ -260,8 +270,8 @@ EOF
**Check which labels actually exist first**, then apply only those:

```bash
gh label list --repo aoagents/ReverbCode # source of truth — apply only these
gh issue edit <number> --repo aoagents/ReverbCode --add-label "bug"
gh label list --repo "$REPO" # source of truth — apply only these
gh issue edit <number> --repo "$REPO" --add-label "bug"
```

The repo currently carries `bug`, `enhancement`, `priority: critical/high/medium/low`,
Expand Down Expand Up @@ -312,7 +322,7 @@ There is no remote-patch script.

Fixes #<n>"
git push -u origin fix/<slug>
gh pr create --repo aoagents/ReverbCode --fill \
gh pr create --repo "$REPO" --fill \
--title "fix(<scope>): <summary>" \
--body "Fixes #<n>

Expand All @@ -330,7 +340,7 @@ There is no remote-patch script.
```bash
ao spawn --project reverbcode --prompt "Fix #<n>: <one-line problem statement>. \
Root cause: <file:line + mechanism>. Suggested approach: <approach>. \
Build with 'cd backend && go build ./... && go test ./...' before opening a PR against aoagents/ReverbCode."
Build with 'cd backend && go build ./... && go test ./...' before opening a PR against $REPO."
```

Note the issue with which path you took (PR or spawned worker).
Expand Down Expand Up @@ -372,10 +382,10 @@ any priority/confidence stated in the body), root cause summary.
### B. Remote Code Inspection (no local clone)

```bash
gh api repos/aoagents/ReverbCode/git/trees/main?recursive=1 --jq '.tree[].path' # list files
gh api repos/aoagents/ReverbCode/contents/{path} --jq '.content' | python3 -c "import base64,sys; sys.stdout.buffer.write(base64.b64decode(sys.stdin.read()))" # read file
gh search code "term" --repo aoagents/ReverbCode --json path --jq '.[].path' # search code
gh api "repos/aoagents/ReverbCode/commits?path={path}&per_page=10" --jq '.[] | "\(.sha[0:8]) \(.commit.message | split("\n")[0])"' # file history
gh api "repos/$REPO/git/trees/main?recursive=1" --jq '.tree[].path' # list files
gh api "repos/$REPO/contents/{path}" --jq '.content' | python3 -c "import base64,sys; sys.stdout.buffer.write(base64.b64decode(sys.stdin.read()))" # read file
gh search code "term" --repo "$REPO" --json path --jq '.[].path' # search code
gh api "repos/$REPO/commits?path={path}&per_page=10" --jq '.[] | "\(.sha[0:8]) \(.commit.message | split("\n")[0])"' # file history
```

### C. Build / Version Diagnostics
Expand All @@ -401,7 +411,7 @@ git checkout - ; git stash pop

## Formatting Rules

- **Linkify all issue/PR refs:** `[#123](https://github.com/aoagents/ReverbCode/issues/123)`, `[PR #456](url)`. Never bare `#123`.
- **Linkify all issue/PR refs:** `[#123](https://github.com/$REPO/issues/123)`, `[PR #456](url)`. Never bare `#123`.

## Pitfalls

Expand All @@ -412,7 +422,7 @@ git checkout - ; git stash pop
- **Reporter ≠ person who tagged you.** Always attribute to the original reporter.
- **Record the commit hash** you analyzed — code changes fast.
- **GitHub issue is mandatory** — every triaged bug gets one, even if fix is trivial.
- **Only apply labels that exist** (`gh label list --repo aoagents/ReverbCode`).
- **Only apply labels that exist** (`gh label list --repo "$REPO"`).
State priority/confidence in the body when no matching label exists.
- **Build before you push.** `cd backend && go build ./... && go test ./...` must
pass; never open a PR with an unverified Go change.
Expand Down
Loading