/aiwg-issue

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:

aiwg discover "<keywords from the proposed title>"

Then search the tracker for matching titles. The `steward-prep-delivery` skill bundles both lookups into one command:

aiwg run skill steward-prep-delivery -- "<search terms>"

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:

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 `<placeholder>`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: <original title> (<source>#<number>)` 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:

- [ ] 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