issue

# Issue Filing > **Process reference:** `.claude/process.md` defines the label taxonomy, workflow states, > and conventions that this skill must follow. File a GitHub issue from an in-conversation observation. The user types something like `bug: default WSS URL is missing /ssh` and expects it handled without derailing current work. ## Execution Model Spawn a `general-purpose` agent with the prompt from `.claude/agents/issue-manager.md`. Use `model: "sonnet"`, `run_in_background: true`. Custom subagent_types are broken in file-based discovery (see `.claude/rules/agents.md`). Background agents auto-deny permissions not pre-approved in `settings.json`. If the agent fails on permissions, run it in foreground instead or file directly in the main conversation. ## Step 1: Parse the trigger Extract from the user's message. Apply exactly one **Type** label per `.claude/process.md`: | Prefix | Type label | Title prefix | |---|---|---| | bug: | `bug` | bug: | | fix: | `bug` | fix: | | feature: | `feature` | feature: | | feat: | `feature` | feat: | | chore: | `chore` | chore: | | issue: | (classify from description) | (classify from description) | If the prefix is `issue:` or `/issue`, read the description and pick the best type label. Add **Domain** labels if the description matches keywords: | Keywords | Label | |---|---| | touch, gesture, swipe, pinch, scroll | `touch` | | ios, safari, webkit, iphone, ipad | `ios` | | security, vault, credential, encrypt | `security` | | ux, ui, layout, mobile, keyboard, panel | `ux` | | image, sixel, kitty, iterm | `image` | Add **Shape** labels when applicable: | Condition | Label | |---|---| | Issue needs research before code can be written | `spike` | | Issue needs emulator/device validation | `device` | | Issue is too large for one bot pass | `composite` | Do NOT apply delegation labels (`bot`, `divergence`) -- those are managed by `/delegate` and `/integrate` respectively. ## Step 2: Gather context Build a concise issue body. No filler. - **Context line**: one sentence on what was being worked on (branch, feature, test). Pull from the conversation state. - **Description**: expand the user's observation into a clear problem statement or feature request. Add technical details you know (file paths, function names, config values). - **Reproduction**: for bugs, describe how to reproduce if apparent. For features, describe the user need. - **Version snapshot**: capture both the code state and what the user is actually seeing. The user often tests on a running server while code changes happen in parallel, so these may differ. ```bash scripts/gh-ops.sh version ``` This outputs `Code: abc1234 | Server: 0.1.0:def5678` (or `server not running`). If they differ, flag it as `(STALE -- server hasn't been restarted)`. ## Step 3: Check for recent test artifacts Check for recent test artifacts in either test results directory. If the report JSON was modified within 30 minutes (`stat -c %Y` vs `date +%s`), include relevant evidence: **Appium tests** (primary): 1. **test-results-appium/results.json**: parse for pass/fail summary, failed test names 2. **test-history/appium/**: archived recordings and results per run **Legacy CDP emulator tests**: 1. **test-results/emulator/report.json**: pass/fail summary, failed test names and errors 2. **test-results/emulator/frames/**: frame filenames that relate to the issue 3. **test-results/emulator/recording.mp4**: existence and timestamp **Both paths**: 4. **Per-test screenshots**: check `test-results/*-android-emulator/` for relevant PNGs If a recording exists but no frames have been extracted (no `frames/` directory or it's empty), run `scripts/review-recording.sh` to generate uniform frame samples. This is useful when the issue relates to visual behavior that screenshots alone don't capture. Only include artifacts clearly connected to the issue. If nothing is recent or relevant, skip this section entirely. ## Step 4: Add @claude bot task (optional) If the issue is actionable (bug with clear reproduction, feature with clear scope), append: ``` @claude <Specific instruction for what to investigate or implement. Reference relevant files, test commands, or prior issues.> ``` Do NOT add `@claude` for research issues (`spike`), things needing real-device validation (`device`), or vague requests that need scoping. The `/delegate` skill handles enriching issues with full delegation context and applying the `bot` label -- this step is just a lightweight hint for obviously bot-ready issues. ## Step 5: Duplicate check and file Before filing, check for existing issues: ```bash scripts/gh-ops.sh search "<key phrase from title>" ``` If a match exists, warn the user and ask whether to file or comment on the existing one. Write the body to a temp file, then file using the wrapper script. Body template: ``` Filed while working on <context> (<branch>). <Problem statement or feature description with technical details.> ## Reproduction <Steps to reproduce, or user need for features.> ## Version <output from `scripts/gh-ops.sh version`> <If mismatched: "(STALE -- server hasn't been restarted)"> ## Test Evidence <Only if recent artifacts exist (Step 3). Otherwise omit this section entirely.> - Run: <pass/fail summary from report.json> - Failed: <test names and error snippets> - Frames: <relevant filenames from frames/ or review/> - Recording: test-results/emulator/recording.mp4 (<timestamp>) @claude <Specific bot instructions, if actionable (Step 4).> ``` Write the composed body to a temp file, then file: ```bash # Write body to temp file (use the Write tool, not a heredoc) # Then file: scripts/gh-file-issue.sh --title "<prefix>: <title>" --label "<type>" --label "<domain>" --body-file /tmp/issue-body.md ``` **Important:** Use the Write tool to create `/tmp/issue-body.md`, then call the script. Do NOT use heredocs or `$(cat <<EOF)` in the bash command -- that's what causes per-command approval prompts. One Write + one `scripts/gh-file-issue.sh` call. Only include `--label` flags for labels that apply. Type is always one. Domain and shape are zero or more. See `.claude/process.md` for the full label taxonomy. ## Step 6: Report back Output: `Filed: <issue-url>` If filing failed, report the error. Do not retry silently. ## Edge Cases - Bare prefix with no description (e.g. just `bug:`) -- ask for at least a one-phrase description - `gh` not authenticated -- report error immediately - Only use labels defined in `.claude/process.md` -- all are pre-created on the repo