arcane-issue-pr-writing

name	arcane-issue-pr-writing
description	Structure GitHub issues, PRs, epics, and review comments for fast comprehension. Covers what sections to include, how long they should be, what level of detail goes where, and how to use collapsibles to keep top sections short. For markdown style and posting mechanics, use `arcane-github-formatting`.

Arcane Issue and PR Writing

How GitHub text is structured — what sections it has, what goes at the top, what goes in collapsibles, how long each part should be. The visual mechanics (markdown, icons, code snippets, posting safety) live in arcane-github-formatting.

Primary Goal

Optimize for the reader's first 20 seconds. They should know status, severity, and next action without scrolling.

Tone and Communication Priority

Write for shared understanding first, formality second.

• Prefer plain wording over heavy engineering language.
• Use project-local terms when they improve clarity.
• Keep the tone human and direct; avoid corporate-sounding filler.
• If a formal term is needed, pair it with a short plain-language gloss.

Default Density Rules

• Top section ≤ ~140 words. Anything longer goes in collapsibles.
• One idea per bullet. Lead with outcomes, not process.
• Concrete nouns and file/module names. "Convert unwraps in arcane-wire/src/lib.rs" beats "Improve error handling."
• Severity tags up front. Use 🚨 Critical / ⚠️ Required / 💡 Optional consistently (same as arcane-github-formatting).

Issue Template

## Quick Summary

- 🟢/🟡/🔴 **Status** + headline
- Key fact #1
- Key fact #2
- Key fact #3 (4–6 bullets max)

## Why This Matters

- One-line impact.

## Scope

- In: ...
- Out: ...

## Action Items

- [ ] ...
- [ ] ...

<details>
<summary>Technical details</summary>

Full rationale, metrics, traces, logs, alternatives, edge cases, fix sketches with code snippets.

</details>

## Reference

- Parent EPIC: #N
- Audit fingerprint (if from automated workflow): `<!-- audit-fingerprint: ... -->`

PR Template

## Quick Summary

- What changed (1 line)
- Why (1 line)
- 2–3 supporting bullets

## Change Type

- feature | fix | refactor | docs | infra | chore

## Impact

- User/developer impact:
- Risk level:

## Verification

- [ ] Build passes (`cargo build`)
- [ ] Tests pass (`cargo test`)
- [ ] Manual checks (if UI/UX): ...
- [ ] Formatter clean (`cargo fmt --all -- --check`)

<details>
<summary>Implementation notes</summary>

Walk-through of the diff, design decisions, alternatives considered, trade-offs.

</details>

## Reference

- Issue: closes #N
- Related: ...

Review Comment Template

For pointing out a finding in a PR review or commenting on an issue:

## 🚨 Critical: Short finding title

### Why this matters
- One-line impact.

### Evidence
\`\`\`rust
// Small relevant snippet
\`\`\`

<details>
<summary>Suggested fix</summary>

- Step 1
- Step 2
- Step 3

</details>

Severity prefix uses the icon set from arcane-github-formatting:

• 🚨 Critical (blocks merge)
• ⚠️ Required (must address)
• 💡 Optional / Nit (suggestion)

EPIC Template (long-lived oversight issues)

For permanent status-tracking issues (e.g., weekly health, security audit, etc.):

## Quick Summary

- 🟡 **Status** + score/headline
- Key axis status (3–5 bullets)
- 📌 **Permanent + pinned** — automated workflow rewrites body; do not close
- 📊 Link to full report file

## Scorecard (table)

| Axis | Score | Status |
|---|---:|---|

## Findings — by severity

### 🚨 Critical (N)
### ⚠️ Required (N)
### 💡 Optional / FYI

## Action Items

- [ ] #N — Title (Type, severity)

## KPI Baseline

| Metric | Today | Goal next run |
|---|---:|---:|

<details>
<summary>Full metrics + hotspots</summary>
</details>

<details>
<summary>How this EPIC is maintained</summary>
</details>

## Reference

- Master roll-up: ...
- Workflow source: ...

Required Sections by Artifact Type

Artifact	Required top sections
Bug	Quick Summary, Why This Matters, Steps to Reproduce, Expected vs Actual, Acceptance
Feature	Quick Summary, Motivation, Proposed Solution, Acceptance
Task	Quick Summary, Why This Matters, Suggested Fix, Acceptance
EPIC	Quick Summary, Scorecard, Findings, Action Items, How Maintained
PR	Quick Summary, Change Type, Verification
Review comment	Severity title, Why, Evidence, Fix

Writing Rules

• Lead with outcomes, not process.
• One idea per bullet, no double-clauses.
• Use concrete nouns and file/module names.
• When referencing an issue, include short context, not just #N.
  • Do: #62 — Improve runtime error handling in arcane-infra hotspots
  • Don't: Issue #62
• Acceptance criteria are checkable: [ ] items, not prose.

When to Apply

Every GitHub artifact you create or update from this terminal or via the cloud agent: issues, PRs, epics, review comments. For the visual mechanics — markdown, icons, code-snippet placement, posting safety, linking — see the partner skill arcane-github-formatting.