neru-file-issue

File a Neru bug report or feature request that matches the repo's issue forms: duplicate check first, every required field filled with real diagnostics, correct labels. Use when asked to open, file, o

SKILL.md

GitHub

Filing an issue in Neru

Blank issues are disabled (.github/ISSUE_TEMPLATE/config.yml), so everything goes through a form, and an agent-filed issue must contain the same fields the form enforces. gh issue create bypasses form validation, so you are the validator.

Always, before filing

  1. Search for duplicates. The forms make humans attest to this, so do it for real: gh issue list --search "<keywords>" --state all, plus discussions for feature ideas. Found one? Comment there instead of filing.
  2. Route non-issues away. Questions and config help belong in Discussions, Linux porting talk belongs in discussion #559, and "is this supported yet" is answered by the Platform Support matrix in docs/reference/platform-support.md. Filing an issue for these is wrong even if the user asked for an issue. Say so and offer the right venue.

Bug report (--label bug)

Mirror bug_report.yml's fields as markdown sections, all of them:

  • Neru version: real output of neru --version, never guessed.
  • Operating system and OS version (sw_vers on macOS, distro and compositor on Linux, since behavior differs across X11/wlroots/KDE/GNOME).
  • Navigation mode: hints / grid / recursive grid / scroll / n.a.
  • What happened / What did you expect: observed vs expected, concrete.
  • Steps to reproduce: numbered, from neru launch, minimal.
  • Config (relevant sections): only the TOML sections involved, fenced as toml. Strip anything personal (macro contents, exec commands).
  • Screenshots / recordings and Additional context when they help. neru doctor output is the most useful evidence for capability/permission-shaped bugs.

Linux/Windows caveat from the form: many features are intentionally unimplemented there. If neru doctor reports the capability as stub, it is a roadmap item, not a bug. Check the matrix before filing.

Feature request (--label enhancement)

Mirror feature_request.yml:

  • Category: one of Navigation, Mouse actions, Configuration, CLI / IPC, UI / Overlays, Performance, Platform support (Linux / Windows), Other.
  • Target platform: All platforms / macOS / Linux / Windows.
  • Problem or use case: the need, not the mechanism. This is the section maintainers judge, so write it first and best.
  • Proposed solution, Alternatives considered, optional Screenshots / mockups.
  • Contribution: state whether a PR will follow.

Filing

Draft the body, show it to the user before creating (an issue posts publicly under their account), then:

gh issue create --title "<concise, user-facing summary>" --label bug --body-file <draft>

Title style matches the tracker: plain sentence, no conventional-commit prefix, no trailing period.

The forms apply bug / enhancement automatically. gh does not, so pass it yourself, and add the axes the forms never cover: platform: macOS / platform: linux / platform: windows or cross-platform, the matching area: * (overlays, event-tap, hotkeys, accessibility, cli, config, domain, ipc, ui, infra), and stub implementation when the ask is replacing a CodeNotSupported stub. gh label list is the authority.