Cursor Skill

ai-issue-report

Reports reproducible faults as a local, allow-listed draft scanned for machine paths, PII, and secrets; shows exact bytes and SHA-256 before confirmation. Trigger: "report this bug", "file an issue", "send this upstream", or "write the incident report". Diagnose own-code failures

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download arcasilesgroup-ai-engineering-skills_ai-issue-report-46b6569.zip · 2 KB

Install

skills CLI npx skills add https://github.com/arcasilesgroup/ai-engineering/tree/main/skills/ai-issue-report
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install arcasilesgroup-ai-engineering@llmmart
Git git clone https://github.com/arcasilesgroup/ai-engineering.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole arcasilesgroup/ai-engineering collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

ai-issue-report — report the fault, collect nothing on the way

What it produces

A local draft (gitignored) plus the exact bytes that would leave, previewed with their SHA-256 — and nothing sent by anybody but the user.

The non-negotiable: what must never leave the machine

The payload is closed to allow-listed fields. Everything else is rejected at the gate, before the draft exists:

  • Machine paths — home directories and absolute paths on any OS: they leak the username and the project layout. The scan names the field and the match (ACCEPTANCE_MACHINE_PATH_*); the fix is to describe the same thing without the path.
  • Personal data (PII) — emails, names, phone numbers, account ids, tokens in URLs. ACCEPTANCE_PII_* names what was found; rewrite the sentence, not around the value.
  • Secrets — keys, passwords, session cookies, anything gitleaks would flag. ACCEPTANCE_GITLEAKS_SECRET is a hard refusal: no draft is written at all.
  • Logs, diffs, tracebacks, full command lines — there is no field for them, by design. A pasted command carries the path it ran from and often the arguments it ran with. Write the four fields in your own words instead: title, what happened, what you expected, one step per reproduction step.

A vulnerability (--kind security) NEVER becomes a public issue: the refusal prints the private disclosure route (SECURITY.md, the maintainer's security contact) and declines the public one before asking anything.

Steps

  1. Reproduce it first. A report of something that happened once is a report the person reading it cannot act on; the steps field is what makes the difference.
  2. Decide the kind before writing. Security → private route, always.
  3. Write the four fields in your own words. Never paste logs, diffs or tracebacks.
  4. Run the gate. Read the refusal if you get one: each code names what was found and in which field. Rewrite that field in words that do not carry the value — do not work around the scan.
  5. Read the previewed bytes and their SHA-256. They are exactly what would leave. If anything in there is not yours to publish, stop.
  6. Sending is separate and manual. Nothing is transmitted automatically: take the previewed bytes to the route your organisation or the upstream project uses (GitHub issue for bugs, SECURITY.md contact for vulnerabilities, your incident channel for incidents).

Writing the prose

The write-up follows the framework's single writing standard — read it before writing the fields: ai-write › references/documentation-writer.md. One idea per sentence, one meaning per word, nothing the environment already says. When the report is long (an incident post-mortem rather than a bug), hand the prose to /ai-write and keep this skill's gate as the last step before publishing.

The ai-engineering seam

  1. The governed post-mortem lives at .ai-engineering/reports/NNN-{slug}.html — readable without session context; the NNN numbering is never rewritten. It is styled by the artifact design system — ai-brainstorm › references/artifact-design.md — never by a stylesheet invented for the report.
  2. It is immune while DECISIONS.md cites it; uncited, it expires to gc (§21.3) — history is not rewritten, it is archived in git.
  3. The gate (paths/PII/secrets) runs on ANY text destined to leave a governed repo — it is the same discipline the git floor's gitleaks stage enforces at commit time, applied one step earlier, to prose.

Routing

In scope: reproducible faults bound for a team, an upstream project, or an incident review. Not for: undiagnosed faults (/ai-debug), internal findings worth remembering (/ai-note), decisions (/ai-brainstorm), the docs themselves (/ai-write).

Lifecycle

Lane: any Writes: .ai-engineering/reports/NNN-.html Read by: the team, humans without session context Dies: immune while a permanent governor cites it; doctor --gc after older_than when nothing cites it Next: none

Source: ai-engineering (own), Apache-2.0.

Files (ai-engineering)
  • SKILL.md 4.5 KB
    ---
    name: ai-issue-report
    description: >-
      Reports reproducible faults as a local, allow-listed draft scanned for machine paths, PII,
      and secrets; shows exact bytes and SHA-256 before confirmation. Trigger: "report this bug",
      "file an issue", "send this upstream", or "write the incident report". Diagnose own-code
      failures first (/ai-debug); vulnerabilities require private disclosure.
    license: Apache-2.0
    ---
    
    # ai-issue-report — report the fault, collect nothing on the way
    
    ## What it produces
    
    A local draft (gitignored) plus the exact bytes that would leave, previewed with their
    SHA-256 — and nothing sent by anybody but the user.
    
    ## The non-negotiable: what must never leave the machine
    
    The payload is closed to allow-listed fields. Everything else is rejected at the gate,
    before the draft exists:
    
    - **Machine paths** — home directories and absolute paths on any OS: they leak the
      username and the project layout. The scan names the field and the match
      (`ACCEPTANCE_MACHINE_PATH_*`); the fix is to describe the same thing without the path.
    - **Personal data (PII)** — emails, names, phone numbers, account ids, tokens in URLs.
      `ACCEPTANCE_PII_*` names what was found; rewrite the sentence, not around the value.
    - **Secrets** — keys, passwords, session cookies, anything gitleaks would flag.
      `ACCEPTANCE_GITLEAKS_SECRET` is a hard refusal: no draft is written at all.
    - **Logs, diffs, tracebacks, full command lines** — there is no field for them, by design.
      A pasted command carries the path it ran from and often the arguments it ran with. Write
      the four fields in your own words instead: title, what happened, what you expected, one
      step per reproduction step.
    
    A vulnerability (`--kind security`) NEVER becomes a public issue: the refusal prints the
    private disclosure route (SECURITY.md, the maintainer's security contact) and declines the
    public one before asking anything.
    
    ## Steps
    
    1. Reproduce it first. A report of something that happened once is a report the person
       reading it cannot act on; the steps field is what makes the difference.
    2. Decide the kind before writing. Security → private route, always.
    3. Write the four fields in your own words. Never paste logs, diffs or tracebacks.
    4. Run the gate. Read the refusal if you get one: each code names what was found and in
       which field. Rewrite that field in words that do not carry the value — do not work
       around the scan.
    5. Read the previewed bytes and their SHA-256. They are exactly what would leave. If
       anything in there is not yours to publish, stop.
    6. Sending is separate and manual. Nothing is transmitted automatically: take the previewed
       bytes to the route your organisation or the upstream project uses (GitHub issue for
       bugs, SECURITY.md contact for vulnerabilities, your incident channel for incidents).
    
    ## Writing the prose
    
    The write-up follows the framework's single writing standard — read it before writing the
    fields: [ai-write › references/documentation-writer.md](../ai-write/references/documentation-writer.md).
    One idea per sentence, one meaning per word, nothing the environment already says. When the
    report is long (an incident post-mortem rather than a bug), hand the prose to /ai-write and
    keep this skill's gate as the last step before publishing.
    
    ## The ai-engineering seam
    
    1. The governed post-mortem lives at `.ai-engineering/reports/NNN-{slug}.html` — readable
       without session context; the NNN numbering is never rewritten. It is styled by the
       artifact design system — [ai-brainstorm › references/artifact-design.md](../ai-brainstorm/references/artifact-design.md) — never by a
       stylesheet invented for the report.
    2. It is immune while DECISIONS.md cites it; uncited, it expires to gc (§21.3) — history is
       not rewritten, it is archived in git.
    3. The gate (paths/PII/secrets) runs on ANY text destined to leave a governed repo — it is
       the same discipline the git floor's gitleaks stage enforces at commit time, applied one
       step earlier, to prose.
    
    ## Routing
    
    In scope: reproducible faults bound for a team, an upstream project, or an incident review.
    Not for: undiagnosed faults (/ai-debug), internal findings worth remembering (/ai-note),
    decisions (/ai-brainstorm), the docs themselves (/ai-write).
    
    ## Lifecycle
    
    Lane: any
    Writes: .ai-engineering/reports/NNN-{slug}.html
    Read by: the team, humans without session context
    Dies: immune while a permanent governor cites it; doctor --gc after older_than when nothing cites it
    Next: none
    
    Source: ai-engineering (own), Apache-2.0.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.