| name | ai-report |
| description | Reports a reproducible fault in this framework through `ai-eng report issue`: a payload closed to nine allow-listed fields, scanned for machine paths, personal data and secrets, written as a local gitignored draft, and shown as the exact bytes with their SHA-256 before anybody confirms anything. Trigger for "report this bug", "file an issue about ai-engineering", "the framework is broken", "send this upstream". Not for a fault in your own code — use /ai-debug, which finds a cause at file:line. Not for a vulnerability sent anywhere public: that routes to private disclosure and this command refuses the other way. |
| license | Apache-2.0 |
| compatibility | needs ai-eng |
| disable-model-invocation | true |
Report the framework's own fault, and collect nothing on the way
What it produces
.ai/issue/draft.json — local, gitignored, previewed byte for byte, and sent by nobody
but you.
Steps
-
Reproduce it first. A report of something that happened once is a report the person
reading it cannot act on, and the steps field is what makes the difference.
-
Decide the kind before you write. --kind security never becomes a public issue: the
command refuses that route before it asks you anything, and prints the private one.
-
Write the four fields in your own words: the title, what happened, what you expected,
and one --step per step. Never paste a log, a diff, a traceback or a command line —
there is no field for any of them, and a pasted command carries the path it ran from.
-
Run it:
ai-eng report issue --kind bug --title "…" --what-happened "…" \
--expected "…" --step "…" --step "…"
-
Read the refusal if you get one. ACCEPTANCE_MACHINE_PATH_*, ACCEPTANCE_PII_* and
ACCEPTANCE_GITLEAKS_SECRET each name what was found, no draft is written, and the fix
is to say the same thing without the value it carried.
-
Read the bytes it prints. They are exactly what would leave, and the SHA-256 beside them
is of those bytes. If anything in there is not yours to publish, stop.
-
Sending is separate and manual. --submit asks for a phrase carrying that digest at your
keyboard, and then says there is nowhere to send: no destination is configured and this
package has no transport. Take the previewed bytes to the route your organisation uses.
What this is not
- "The fault is obvious, so the report needs no reproduction steps" — a report of something that happened once is a report the person reading it cannot act on, and the steps field is what makes the difference.
Done when
- Every field is a sentence you wrote, and nothing in the payload was collected.
- The scan came back clean, or you rewrote the field it named rather than working around it.
- A vulnerability went to private disclosure and no public issue exists for it.
