--- namespace: aiwg name: aiwg-issue platforms: [all] kernel: true description: AIWG project issue filing only — templates, environment capture, duplicate detection, and import flow for AIWG tracker reports; not for general issue audits or address-issues processing --- # Filing AIWG Issues You are helping a user (or yourself, as an autonomous agent) file a high-quality issue. The bar is set by the recent tester-report import sweep (Gitea #1264–#1269): environment captured, exact commands, error text in code blocks, suggested fix paths. This is an **AIWG-specific kernel capability**. Use it for filing, importing, or triaging the quality of issue reports about AIWG itself. Do **not** use this skill for general backlog processing: - Use `issue-audit` / `audit-issues` when the user asks to audit open issues, triage a backlog, find duplicates, review stale issues, or rank work. - Use `address-issues` when the user asks to fix, process, or work through issues. - Treat `aiwg-*` skill names as AIWG product/workspace capabilities, not as the generic issue-processing surface. ## When this fires Natural-language triggers: - "file an AIWG issue" - "report an AIWG bug" - "import this AIWG issue from GitHub" - "I want to file an issue" - "How do I report a bug?" - "Help me write up a bug report" - "What template should I use?" - "Should I file a new issue or comment on an existing one?" - "Import this report from GitHub" / "from Discord" / "from email" Non-triggers: - "audit open issues" - "triage the issue backlog" - "review stale issues" - "address issues" - "process open issues" ## Template selection | Template | When to use | Path | |---|---|---| | `bug-report.md` | One concrete defect with a reproduction | `.gitea/ISSUE_TEMPLATE/bug-report.md` | | `feature-request.md` | A new capability or enhancement proposal | `.gitea/ISSUE_TEMPLATE/feature-request.md` | | `tester-report.md` | A single session that surfaced multiple findings | `.gitea/ISSUE_TEMPLATE/tester-report.md` | | `imported-report.md` | Mirroring an issue filed in a different tracker | `.gitea/ISSUE_TEMPLATE/imported-report.md` | Templates exist in both `.gitea/ISSUE_TEMPLATE/` (for Gitea) and `.github/ISSUE_TEMPLATE/` (for the GitHub mirror). Pick the one matching the target tracker; the content is identical. ## The walkthrough ### 1. Triage first Ask: is this one bug, or multiple findings from a single session? - **One issue** → `bug-report.md` or `feature-request.md` - **Multiple findings** → `tester-report.md`, split into discrete bugs during follow-up triage - **Already filed elsewhere** → `imported-report.md` **One bug per issue.** If three things broke, file three issues (or one tester-report and split). Don't bundle. ### 2. Duplicate detection (BEFORE filing) Always check for duplicates first. Cheaper to comment on an existing thread than file again. Use: ```bash aiwg discover "" ``` Then search the tracker for matching titles. The `steward-prep-delivery` skill bundles both lookups into one command: ```bash aiwg run skill steward-prep-delivery -- "" ``` If a likely duplicate exists, comment on it rather than filing fresh. ### 3. Environment capture (REQUIRED — three non-negotiable fields) Bug reports without **AIWG version + operating system + provider** are bounced before triage. Collect ALL of these: ```bash aiwg version # → AIWG version + channel (REQUIRED) uname -a # → operating system + kernel (REQUIRED) node --version # → Node version aiwg doctor # workspace health snapshot (helpful) ``` And — also required — the **provider** (the AIWG harness in use): one of `claude-code`, `hermes`, `codex`, `copilot`, `cursor`, `warp`, `factory`, `opencode`, `windsurf`, `openclaw`. When you (the agent) draft a bug report on behalf of a user, **ask explicitly for each of the three required fields** if they aren't already in the conversation. Don't infer. The May-2026 jmagly→roctinam import sweep needed a correction round because the original GitHub report cited "Claude Code 2.1.137" but the actual harness in use was hermes — same bug, different behavior, wasted half a round-trip to clarify. Don't repeat that. The bug-report template has a checklist that enforces this; surface it before the operator submits. ### 4. Reproducible repro Paste **exact** commands (copy-paste-ready, no ``s without explicit substitution instructions) and **exact** error text in fenced code blocks. Paraphrased errors lose detail. Bad: > "When I run the steward command it errors out" Good: > ``` > $ aiwg steward capabilities --provider claude-code > ERROR ENOENT: no such file or directory, open '/home/linuxbrew/.linuxbrew/lib/node_modules/aiwg/dist/agentic/code/providers/capability-matrix.yaml' > ``` ### 5. Title format `type(scope): one-line summary`. Examples: - `bug(steward): AIWG_ROOT path resolution lands at dist/ instead of package root` - `feat(contributing): consistent PR + Issue templates` - `regression: Skill Seekers implementation lost` - `imported: (#)` for imports Vague titles ("doesn't work", "broken") get bumped back. Insist on the typed form. ### 6. Suggested fix (if you've investigated) If you've already traced the bug, point at the file or line. "I think this is in `src/cli/handlers/steward.ts:26`" is faster than a round-trip. This is optional but valued — the recent #1261/#1262/#1263 imports landed faster because the original reporter included file-line pointers. ### 7. Acceptance criteria Bug reports should include checkable acceptance: ```markdown - [ ] Repro from "Steps to reproduce" no longer fails - [ ] Regression test added (if the bug bypassed existing tests) - [ ] Related docs updated (if behavior was documented incorrectly) ``` Feature requests need concrete, checkable conditions — not "works well" or "feels right". ## Import flow (cross-tracker reports) When a report lands in a different tracker (GitHub mirror, Discord, email, vendor support), mirror to Gitea as `imported-report.md`: 1. Title: `imported: (#)` 2. Link the source URL 3. Preserve the **original reporter handle** and **platform/environment** (correct it if the source got it wrong) 4. Add a "Status against current main" table 5. Cross-reference any local issues that duplicate or overlap 6. If already fixed: note the resolving commit and close as duplicate 7. **Thank the original reporter** in a closing comment when the work lands Example: jmagly#108–#112 → roctinam #1264–#1268 sweep (May 2026). ## Filing ```bash aiwg run skill issue-create -- "" --provider gitea --labels "bug" ``` Or use the tracker's web UI with the template. Both are valid. For Gitea via MCP (if available): ```yaml mcp__git-gitea__issue_write: method: create owner: roctinam repo: aiwg title: '<title>' body: '<full body following bug-report.md template>' ``` ## After filing - Add labels (priority, area, type) per the `ops-issue-tracking` rule conventions - Link related issues with `Refs #N` / `Blocked-by: #N` / `Blocks: #N` in the body - Watch the thread for triage comments and answer promptly ## Anti-patterns to flag - **"While I'm at it"** — adding unrelated changes to a bug report. Split into separate issues. - **Bundling fixes into the report** — if you have a fix, file the issue first, then submit the PR with `Closes #N`. Don't mix. - **Re-filing duplicates** — always run duplicate detection first. - **Vague titles** — `type(scope): subject` form is required. - **Missing environment** — bug reports without OS/version/platform get clarified before action. ## Related - Skills: `aiwg-pr` (filing PRs), `steward-prep-delivery` (interactive walkthrough), `issue-create` (low-level filing), `issue-auto-sync` (commit↔issue linking) - Templates: `.gitea/ISSUE_TEMPLATE/`, `.github/ISSUE_TEMPLATE/` - Docs: `CONTRIBUTING.md` (full contributor guide) - Rules: `delivery-policy`, `no-attribution`, `ops-issue-tracking` - Origin: #1269 (templates), #1264–#1268 (tester report sweep that motivated this)