Skip to content

Reporting

How to file a bug, a feature request or a question, and what happens next.

Pick the form

                     what do you have?
                             |
        +--------------------+--------------------+
        |                    |                    |
        v                    v                    v
+---------------+    +---------------+    +---------------+
| bug           |    | feature       |    | question      |
+---------------+    +---------------+    +---------------+
        |                    |                    |
        v                    v                    v
  title is the defect    the outcome you       Discussions
  repro steps            want, not the
  expected vs actual     change you would
  evidence               make, and why
        |                    |
        +---------+----------+
                  |
                  v
        +-------------------+
        | triage            |   `model:*`: approved, and which model runs it
        +-------------------+
                  |
                  v
        one branch, one PR, `Closes #N`

What goes in each

Form Title Body
Bug The defect, stated flat Repro, expected vs actual, evidence, ref or version
Feature The outcome you want Why; never the change you would make
Question — Discussions, not the tracker
  • No preamble, no restated brief, no closing summary.

A bug report that works:

Title: rules check passes on a repo with no AGENTS.md

Repro:    rm AGENTS.md && mutation-gate rules check; echo $?
Expected: non-zero, "AGENTS.md: missing"
Actual:   0
Ref:      v0.1.1

Triage

  • Triage adds a model:* label once the ticket is the plan. The label names who runs it and is itself the approval. Run sh <agent-sdlc checkout>/bin/sdlc-bootstrap first so the label exists; if creation is refused, triage without it and say so.
  • A raw idea with open questions goes through /grill: one question at a time, recommended answer first. /grill plan files a decision record plus one step ticket per unit of work.
  • A well-scoped ask skips straight to labelling.
  • /kata dispatches a labelled ticket: one branch, one PR, wait for review, squash-merge on LGTM. See SDLC.

Source: .github/ISSUE_TEMPLATE/, CONTRIBUTING.md, rules/tickets.md, rules/voice.md.