/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
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
  - Import this report from Discord
  - Import this report from email

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"

Output template

The selected template is required. Fill every required section before filing; mark non-applicable optional fields with a reason and remove template instructions.

Template selection

| Template | When to use | Path | |---|---|---| | `bug-report.md` | One concrete defect with a reproduction | @$AIWG_ROOT/agentic/code/addons/aiwg-utils/templates/issues/bug-report.md | | `feature-request.md` | A new capability or enhancement proposal | @$AIWG_ROOT/agentic/code/addons/aiwg-utils/templates/issues/feature-request.md | | `tester-report.md` | A single session that surfaced multiple findings | @$AIWG_ROOT/agentic/code/addons/aiwg-utils/templates/issues/tester-report.md | | `imported-report.md` | Mirroring an issue filed in a different tracker | @$AIWG_ROOT/agentic/code/addons/aiwg-utils/templates/issues/imported-report.md |

These bundle templates are canonical. The repository `.gitea/ISSUE_TEMPLATE/` and `.github/ISSUE_TEMPLATE/` files are derived copies maintained by `npm run package-plugins`.

Compose through `issue-create` with `--template <kind|path>` matching the selected template (default: `bug-report`). Missing required headings produce an advisory stderr warning; the composer remains headless-safe.

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`, `codex`, `copilot`, `cursor`, `factory`, `hermes`, `opencode`, `openclaw`, `openhuman`, `omp`, `pi`, `warp`, or `windsurf`.

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`

-