aiwg-issue

name	aiwg-issue
description	Guide for filing high-quality issues — template selection, environment capture, duplicate detection, and import flow for cross-tracker reports
platforms	["codex"]

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.

When this fires

Natural-language triggers:

• "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"

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 a report lands in a different tracker (GitHub mirror, Discord, email, vendor support), mirror to Gitea as imported-report.md:

1. Title: imported: <original title> (<source>#<number>)
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

aiwg run skill issue-create -- "<title>" --provider gitea --labels "bug"

Or use the tracker's web UI with the template. Both are valid.

For Gitea via MCP (if available):

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)