Filing Issues

Filing Issues

Related: filing pull requests, the import flow, AIWG-specific kernel skill `aiwg-issue` (run `aiwg show skill aiwg-issue`)

A high-quality issue is scoped, reproducible, and captures environment. The bar is set by the May-2026 tester-report sweep — five issues filed by `sebuh-infsol` on the GitHub mirror that mirrored cleanly into Gitea (#1264–#1268) and resolved in days because each one had exact commands, exact error text, and a hypothesis.

This guide makes that the default, not the exception.

Pick the right template

Templates live in `.gitea/ISSUE_TEMPLATE/` and are mirrored to `.github/ISSUE_TEMPLATE/`. Same content, different tracker.

TemplateWhen to use
`bug-report.md`One concrete defect with a reproduction
`feature-request.md`A new capability or enhancement proposal
`tester-report.md`A single session that surfaced multiple findings — split during triage
`imported-report.md`Mirroring an issue filed in a different tracker

One bug per issue. If you found three things, file three issues (or one tester-report and split). Don't bundle.

Before you file: duplicate detection

Always check for duplicates first. Commenting on an existing thread is cheaper than filing fresh.

# Search the AIWG capability index (skills, agents, rules, commands)
aiwg discover "<keywords from the proposed title>"

# Search the AIWG capability index + Gitea issues in one shot
aiwg run skill steward-prep-delivery -- "<search terms>"

The `steward-prep-delivery` skill bundles both lookups and gracefully degrades when no Gitea token is configured (it just skips the live issue search).

Required content

Every bug report must include:

Environment (REQUIRED — three fields are non-negotiable)

Every bug report must include these three, copy-pasted verbatim, not paraphrased:

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 you were running): one of `claude-code`, `hermes`, `codex`, `copilot`, `cursor`, `warp`, `factory`, `opencode`, `windsurf`, `openclaw`.

Why these three (AIWG version + OS + provider) are non-negotiable:

- AIWG version: a bug you're hitting may already be fixed in `main` but not yet in the version you installed. Without the version, the first triage step is asking you for it.

- Operating system: the same bug behaves differently across Linux kernel versions, macOS, and Windows. Path resolution, permission semantics, shell behavior all diverge.

- Provider: Claude Code's slash-command path is not Hermes's is not Codex's. The May-2026 tester-report 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 — the slash-command churn behavior the tester observed only happens on hermes (Claude Code's deployed command stubs route to the deterministic CLI). Get this right the first time.

Bug reports missing any of these three will be returned for clarification before any triage work begins. The bug-report template checklist enforces this.

Reproducible repro

Paste exact commands (no `<placeholder>`s without explicit substitution instructions) and exact error text in fenced code blocks.

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'

```

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.

Acceptance criteria

Concrete, checkable conditions. Not "works well" or "feels right".

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

Suggested fix (optional but valued)

If you've already investigated, point at the file or line. `src/cli/handlers/steward.ts:26` is faster than a round-trip. The recent #1261/#1262/#1263 imports landed in one day because the original reporter included file-line pointers.

Import flow (cross-tracker reports)

When a report lands in a different tracker (GitHub mirror, Discord, email, vendor support), mirror it into Gitea using the `imported-report.md` template. The process:

1. Title: `imported: <original title> (<source>#<number>)` 2. Preserve the original reporter handle (e.g., `@sebuh-infsol`) 3. Correct the platform/environment if the source got it wrong (verify which AIWG harness was actually in use) 4. Add a "Status against current main" table: which sub-bugs are already fixed, which are open, which need to be split 5. Cross-reference any local issues that duplicate or overlap 6. Thank the original reporter in a closing comment on the source tracker when the work lands

Example sweep: jmagly#108–#112 → roctinam #1264–#1268 (May 2026). Closed #1265 immediately as duplicate of already-fixed work; closed the others after the fix commits landed; posted thank-you comments on all five GitHub issues citing the resolving commits.

Filing

Three paths, all valid:

# 1. Via the issue-create skill (handles Gitea, GitHub, Jira, Linear, local files)
aiwg run skill issue-create -- "<title>" --provider gitea --labels "bug"

# 2. Via the Gitea MCP server (when available)
mcp__git-gitea__issue_write method=create owner=roctinam repo=aiwg title='<title>' body='<full body>'

# 3. Via the tracker's web UI with the template pre-loaded

After filing

  • Add the right labels (priority, area, type). The `ops-issue-tracking` rule covers conventions when the issue lives in the ops repos; for AIWG, match labels used on adjacent issues.
  • 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 avoid

  • "While I'm at it" — adding unrelated changes to a bug report. Split.
  • Bundling fixes into the report — 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` is required.
  • Missing environment — bug reports without OS/version/platform get clarified before action.

Quick reference

Need toRun
Find existing skills/issues for a topic`aiwg discover "<keywords>"`
Bundle discover + tracker search`aiwg run skill steward-prep-delivery -- "<terms>"`
Fetch a skill body`aiwg show skill aiwg-issue`
File a new issue (skill-mediated)`aiwg run skill issue-create -- "<title>"`
Read the full kernel skill`aiwg show skill aiwg-issue`
  • In-context kernel skill: `aiwg-issue` (always loaded for AIWG issue filing/import hygiene; same content as this doc, accessible to agents without reading docs/)

For general issue backlog processing, use `issue-audit` / `audit-issues` for read-only audit and triage, or `address-issues` for implementation loops. `aiwg-*` capabilities are AIWG product/workspace capabilities, not the generic issue-processing surface.