--- name: first-tree-file-bug description: File a GitHub issue about a defect in First Tree itself — the CLI, agent runtime, chat, web app, GitHub integration, GitLab integration, or Context Tree tooling — onto First Tree's own GitHub-hosted public tracker (agent-team-foundation/first-tree). Use only when the user reports that First Tree the platform is broken, errored, crashed, or misbehaving and wants it reported (e.g. "First Tree has a bug", "chat send keeps failing", "the CLI crashed", "给 First Tree 开个 issue 反馈这个 bug"). The skill gathers reproduction steps, the First Tree client/CLI version, the chat ID, the reporting user's ID, OS, and error output, then opens the issue with the user's `gh` CLI. NOT for filing an issue into the user's own or bound source repo — that is an ordinary source-repo issue using the target forge CLI (`gh` for GitHub, `glab` for GitLab), not this skill — and not for bugs in the user's project code or third-party tools. --- # 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 ` for GitHub, or `glab issue create --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. | Field | How to get it | |---|---| | **What happened** | From the user: what they were doing, the expected result, and the actual result. Turn this into numbered reproduction steps. | | **Error output / logs** | Paste from the user's message or from recent command output in this session. Scrub secrets first (see Guardrails). | | **Client / CLI version** | Run the First Tree CLI with `--version` (e.g. `first-tree --version` — substitute your channel binary; see **CLI binary** below). | | **Runtime / provider** | Your agent runtime kind (e.g. `claude-code`, `codex`), if relevant to the bug. | | **Chat ID** | From the injected **Current Chat Context** block — the `Chat ID:` line, or the `chatId` field of the `first-tree-current-chat-context` JSON payload. | | **Reporting user ID** | The human participant in this chat: their handle from the Current Chat Context participants list (`type=human`), which is also the `` in the `[From: …]` header of their message. | | **Operating system** | `uname -srm` (or `sw_vers` on macOS). | 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: ```bash gh issue list --repo agent-team-foundation/first-tree --search "" --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] `. Body: ```markdown ## Summary ## Surface Area ## Environment - version: - runtime: - operating system: ## Reproduction 1. … 2. … 3. … ## Expected Behavior ## Actual Behavior ## First Tree Context - Chat ID: - Reported by (user): - Agent: ## Additional Context ``` 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: ```bash gh issue create \ --repo agent-team-foundation/first-tree \ --title "[Bug] " \ --label bug \ --body-file ``` `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**: ```bash # 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 \ --topic "Bug: " \ --description "Tracking First Tree bug: — " \ -f markdown \ "Filed a First Tree bug issue: . 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 --chat "$new_chat" else first-tree github follow # fallback: current chat fi ``` - `--to ` 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 `) 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.