arcane-github-formatting

name	arcane-github-formatting
description	Format GitHub comments, issues, and pull requests for fast readability. Use for any text destined for GitHub — issue bodies, PR descriptions, review comments, status updates. Covers markdown style, posting safety, and linking rules. For the structure of issue/PR content (sections, length, level of detail), use `arcane-issue-pr-writing`.

Arcane GitHub Formatting

How GitHub text looks. The structural decisions (what sections, how long, what to put in collapsibles) live in arcane-issue-pr-writing — this skill is about the formatting mechanics that apply to every GitHub artifact regardless of type.

Tone and Communication Priority

Prioritize understanding over formality.

• Use plain wording first.
• Use project-local terms when they help.
• Casual is fine; confusing is not.
• Be direct and respectful without corporate filler.

Default Density (Required)

By default, write tight. Reserve depth for collapsibles.

• Default short. First screen readable in under 20 seconds. Lead with outcome; put rationale and trace below.
• Spoilers (<details>) for any depth. Tables of metrics, fix sketches, "how this works" sections, anything multi-paragraph that isn't immediately required reading goes inside <details>. The reader's eye should be able to skip past it.
• Code snippets where they replace prose. A 3-line before/after diff communicates faster than a paragraph describing the change.
• Inline code for identifiers — file paths, function names, types, commands, env vars, labels.

<details>
<summary>Click to expand — rendered folded by default</summary>

Content here is hidden until clicked.

</details>

Markdown Style

Standard mechanisms with consistent semantic mapping:

• Bold for key labels and decisions (**Decision needed**, **Status**, **Problem**).
• Italics for clarifications and parenthetical asides — anything the reader can skip without losing the main point.
• inline code for identifiers, paths, commands.
• Tables for structured data (metrics, scorecards, status grids).
• Horizontal rules --- for strong section breaks within long bodies.
• > [!NOTE] / [!TIP] / [!IMPORTANT] / [!WARNING] / [!CAUTION] callouts when supported by the renderer for visual emphasis.

Severity Markers (when listing findings)

• 🚨 Critical — blocks something / risk is high
• ⚠️ Required — must address but not blocking right now
• 💡 Optional / FYI — worth knowing, no action required

Same icon set used in terminal output (arcane-terminal-communication) so readers build one mental model across surfaces.

Status Indicators

• 🟢 Green — healthy
• 🟡 Amber — concerns but not blocking
• 🔴 Red — urgent / regression

Posting Safety (Critical)

Use posting methods that preserve markdown exactly.

• Prefer gh issue create --body-file <file.md> and gh pr comment --body-file <file.md>.
• Avoid inline escaped bodies that can turn \n into literal text.
• Verify a posted body once after writing it:

gh api repos/<org>/<repo>/issues/comments/<id> --jq .body

Cloud Automation Hook Notes

Some GitHub App cloud automations are not represented as local files in the repo.

• Do not assume hidden cloud hooks exist unless verified.
• Prefer documented, repo-visible triggers (labels, workflow files, issue/PR events).
• If a hook is cloud-only, document it explicitly in docs/automation-setup.md.
• Verify configured repo webhooks with:

gh api repos/<org>/<repo>/hooks

If this returns [], there are no repo webhooks configured.

Linking Rules

• Same repo: #123
• Cross-repo: brainy-bots/arcane#123
• Named link: [Issue #123](https://github.com/brainy-bots/arcane/issues/123)
• Reference parent EPIC + audit fingerprint at the bottom of weekly-health child issues.

When to Apply

• Any issue body, PR description, review comment, or chat-tagged post on GitHub.
• Across all surfaces: issues, PRs, discussions, project items.

For what to put in an issue/PR (sections, structure, action items), see arcane-issue-pr-writing. For audit and weekly-health-specific content, see arcane-weekly-health-report.