first-tree-file-bug

First Tree File Bug

Purpose

Turn a user's informal bug report about First Tree itself into a well-formed GitHub issue on agent-team-foundation/first-tree, filed with the user's authenticated gh CLI. The value is that the user only has to say "First Tree has a bug" — this skill does the collection, drafting, and filing, opens a dedicated chat that follows the issue for tracking, and reports the issue URL back.

The target repo is public. Filing publishes whatever you include, so gather deliberately, confirm with the user before creating, and never post secrets (see Guardrails).

When to use

• The defect is in First Tree — the CLI (first-tree …), the agent runtime / client, chat delivery, the web app, notifications, GitHub integration, GitLab integration, or Context Tree tooling.
• The user wants it reported / filed / logged, not just diagnosed.

When NOT to use

• The bug is in the user's own project code, a dependency, or a third-party tool — that is normal debugging, not a First Tree issue.
• The user only wants help understanding or working around the problem and has not asked to file anything. Fix or explain first; offer to file only if it is a genuine First Tree defect.
• It is a security vulnerability — do not open a public issue; point the user to the repo's SECURITY.md reporting path instead.

Workflow

1. Confirm the scope

State briefly what you understand the bug to be and that it looks like a First Tree defect worth filing. If it is ambiguous whether the fault is in First Tree or the user's own setup, resolve that first — do not file an issue against First Tree for something outside it. If the report is really about the user's own project or their bound source repo, this is not the skill: file it into that repo with the target repository's forge CLI (gh issue create --repo <their repo> for GitHub, or glab issue create --repo <their repo> for GitLab) instead of here. If that CLI is not authenticated, recover with gh auth login for GitHub or glab auth login for GitLab.

2. Gather the bug context

Collect what the maintainers need to reproduce and triage. Get what you can yourself; ask the user only for what you genuinely cannot infer (typically the repro steps and the observed error). Do not over-interrogate.

If the user already pasted a stack trace or exact error, capture it verbatim — it is the highest-signal part of the report.

3. Check for an existing issue

Do a quick duplicate scan so you do not file a repeat:

gh issue list --repo agent-team-foundation/first-tree --search "<key error phrase>" --state all --limit 10

If a clear match exists, show it to the user and ask whether to comment on it instead of opening a new one.

4. Draft the issue

Follow the repo's bug-report template. Title as [Bug] <concise summary>. Body:

## Summary

<one or two sentences>

## Surface Area

<which part of First Tree: CLI / runtime / chat / web / GitHub integration / GitLab integration / Context Tree>

## Environment

- version: <first-tree --version output>
- runtime: <claude-code | codex | …>
- operating system: <uname / sw_vers>

## Reproduction

1. …
2. …
3. …

## Expected Behavior

<what should have happened>

## Actual Behavior

<what actually happened; include the verbatim error / stack trace>

## First Tree Context

- Chat ID: <chatId>
- Reported by (user): <human participant handle>
- Agent: <your agent id / name>

## Additional Context

<logs, screenshots, related links — secrets scrubbed>

Keep it tight and factual. The First Tree Context block is what lets maintainers correlate the report with server-side logs — these are opaque identifiers, not credentials.

5. Confirm before filing

Filing is outward-facing and publishes to a public tracker, so show the user the drafted title and body and state the destination explicitly — this files into agent-team-foundation/first-tree (First Tree's own public tracker), not the user's own repo — then get an explicit go-ahead before creating the issue. Incorporate any correction they make.

6. File the issue

Write the body to a file so markdown reaches GitHub verbatim, then create:

gh issue create \
  --repo agent-team-foundation/first-tree \
  --title "[Bug] <summary>" \
  --label bug \
  --body-file <path-to-body.md>

gh uses the user's own authentication on this host — that is the intended "file with the user's gh CLI" path. This is GitHub-only because First Tree's public issue tracker is GitHub-hosted.

7. Open a tracking chat and follow the issue

Prefer a dedicated chat over the current one: open a new chat for this bug and route the issue's webhook events there, so its lifecycle (comments, labels, close) is tracked in its own thread instead of cluttering the chat where the bug was reported. Fall back to the current chat only if the dedicated chat cannot be opened (the else branch below).

Create the chat with the reporting user as the recipient, capture the new chat's ID from the JSON response, then follow the issue into that chat:

# 1. Open the tracking chat; capture the full JSON response (don't pipe
#    straight into a parser that might not be installed — see below).
resp=$(first-tree chat create \
  --to <reporting-user-handle> \
  --topic "Bug: <concise summary>" \
  --description "Tracking First Tree bug: <concise summary> — <issue-url>" \
  -f markdown \
  "Filed a First Tree bug issue: <issue-url>. This chat tracks its progress.")

# 2. Take the new chat's id from the response's data.chatId
#    (shape: {"ok":true,"data":{"chatId":"…"}}). Read it directly, or:
new_chat=$(printf '%s' "$resp" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["chatId"])')

# 3. Follow the issue into the NEW chat — but ONLY with a non-empty id.
#    `--chat ""` does NOT fall back; it fails with NO_CHAT_CONTEXT. So if the
#    chat could not be created or its id not parsed, follow into the current
#    chat instead so the issue is never left unfollowed.
if [ -n "$new_chat" ]; then
  first-tree github follow <issue-url> --chat "$new_chat"
else
  first-tree github follow <issue-url>          # fallback: current chat
fi

• --to <reporting-user-handle> is the human who reported the bug (the handle from step 2), so they get the tracking chat and are woken on it.
• Take the chat id from the data.chatId field of the create response. Extraction above uses python3; jq -r '.data.chatId' works too — but do not hard-depend on a parser you cannot confirm is installed. When in doubt, read data.chatId straight from the JSON yourself.
• Set an explicit stable --topic yourself — an agent-declared github follow --chat does not auto-rewrite the tracking chat's topic from the issue, so without it the chat keeps a low-signal auto-derived label (--description is set at create time regardless, so the chat still self-describes).
• chat create is not idempotent — create the chat exactly once; if the result is uncertain, check chat list before retrying rather than re-running blindly.
• Fallback (the example's else branch, not optional): github follow --chat "" fails with NO_CHAT_CONTEXT — it does not fall back on its own. So when chat create fails (e.g. the --to handle will not resolve) or the id cannot be parsed, follow the issue into the current chat (first-tree github follow <issue-url>) and tell the user the dedicated tracking chat could not be opened. Never leave the issue unfollowed.
• Write the first message and description in the session's working language (the examples above are English).

Finally, in the current chat, report the issue URL back to the user and say where it is being tracked: the dedicated chat if one was opened, or (on the fallback) this chat.

Guardrails

• Never publish secrets. Scrub tokens, API keys, cookies, passwords, auth headers, and private URLs from any logs or error output before it goes into a public issue. When unsure, redact.
• Public repo. Chat ID and user ID are opaque identifiers that help triage; they are safe to include, but the confirmation step (5) is where the user gets to veto anything they would rather not post.
• Security issues do not go here — route to SECURITY.md, not a public issue.
• If gh is missing or unauthenticated, do not treat it as a First Tree platform gap. Present the fully drafted issue (title + body) to the user so they can file it manually, and offer the gh install / gh auth login path; this recovery is GitHub-specific because the First Tree tracker is on GitHub.

CLI binary

Examples use the canonical first-tree binary. Substitute the channel-correct binary named in your briefing (first-tree on prod, first-tree-staging on staging, first-tree-dev on dev) — it is the same binary you use for chat send. gh is the host GitHub CLI and is not channel-specific.