GH Body Audit

Two checks: a mechanical math scan (Unicode-math glyphs, the GitHub-unsupported macro \operatorname, inline math neutralized by an enclosing code span, and the $$ delimiter), and a cold-reader audit delegated to a fresh-context subagent.

Why a cold-reader subagent

The author has just drafted the text. They read what they meant, not what the text literally says. A fresh-context subagent with no access to the chat history, the plan, or the author's notes, and told not to browse the repo, is the reader gh-body-conventions § Exclusions' followability requirement is written for; reachability is settled in step 4, where the repo is in reach.

Procedure

1. Prepare the body and target metadata

Write the body to a temp file:

BODY_FILE=$(mktemp -t gh-body-audit-XXXXXX.md)
cat > "$BODY_FILE" <<'EOF'
<the drafted body, exactly as it will be filed>
EOF

Determine: artifact kind (issue / pr), target repo (e.g., owner/repo) and its default branch, target language (English / Japanese / matches-repo, per gh-body-conventions § Language), and for a PR body its head and the branch it merges into.

2. Math scan

${CLAUDE_SKILL_DIR}/body-math-scan.sh "$BODY_FILE"

Exit 0 = clean, 1 = hits found (printed as line:match), 2 = usage / environment error. It flags the raw Unicode math glyphs, the \operatorname macro, inline math $`...`$ neutralized by an enclosing code span, and the $$ delimiter. For a Unicode-glyph or \operatorname hit: a hit in the text its gh-body-conventions § Math rule prohibits it in → ⚠; any other hit → ⊘ N/A, judged by main-context inspection. For a code-span-neutralized inline-math hit, judge intent in main context: math a copied display form silently neutralized → ⚠ (fix); a legitimate literal $`...`$ shown as code or data → ⊘ N/A with a one-line justification. For a $$ hit, judge each $$ on the line: one that main-context inspection shows GitHub does not render as a math delimiter → ⊘ N/A; any other → ⚠. The $$ formed where one $`...`$ span closes directly before the next opens is not a math delimiter: GitHub renders the two spans as inline math.

3. Cold-reader audit (fresh-context subagent)

Invoke Agent with subagent_type: "general-purpose" and model: "sonnet". Pass only the body, the target repo name, and the artifact kind. Do NOT pass chat history, the plan, the author's prior messages, or any context about why the body is being filed.

Prompt template:

You are an external reader of <target-repo>. You know that repository
exists and what its name says, and you hold well-known external
standards (RFCs, language specs). You could open its README, its issues
and PRs, and its code, but you have opened none of them and will not.
You have no access to chat history, private notes, private workflows,
local files, or the author's mental model.

Read the following <issue|PR> body and report two kinds of hit:
- a sentence that points at what a text you have not read says instead
  of stating it — name what you would have to open to follow it. A
  sentence that states the substance is not a hit, even where you
  cannot check it from here;
- a token naming something you cannot reach, or cannot tell whether you
  can reach, a placeholder left where a value belongs among them. You
  have opened nothing, so every path, issue or PR number, URL, and
  published identifier is one of these; a standard you hold, or that
  repository's own name, is not.

For each hit, return the phrase or line verbatim and which of the two
it is. A span that is both is one hit carrying both kinds.

Out of scope: formatting, grammar, math notation, line width,
sub-clause line breaks.

Do NOT browse the repo or run tools. Judge from the body text alone.

--- body ---
<body content>
--- end body ---

4. Merge and gate

Combine the math-scan hit (if any) and the cold-reader report into a single status. Judge each cold-reader ⚠ in main context against gh-body-conventions § Exclusions, and take the finding-triage SSOT's actionable / false-positive split from that judgment. An actionable hit takes the edit finding-triage's response selection picks; where that is fix-in-place on a sentence that points at another text, the content is whichever of § Exclusions' two forms the claim at issue selects. A hit carrying both kinds is two findings here, one per kind, each taking its own disposition and fix.

Settle the second kind by checking that the referent is where an external reader, as § Exclusions defines one, would find it — not by reading the token. § Exclusions' exemption for a repo-relative path the body proposes to create applies first. Where the referent must be, by the token's form:

• a repo-relative path, any position it carries dropped: at the revision the body is about. For a PR body that is its head (the drafting checkout's HEAD until the PR is filed) or its base, present at either being enough; for an issue body, the default branch.
• an issue or PR number: in the repository it names, the target repo for a bare #N.
• a published identifier: at its resolver.
• a URL: at itself.

A token whose referent is there is a false-positive; one whose referent is not is actionable. A token of any other form — a bare name, a placeholder, a local path — is judged on § Exclusions' bar directly.

• True positive (actionable) — fix before proceeding.
• False positive due to missing context — record explicitly why (e.g., the token resolved, or it is a bare name the target repo holds). Where one rule disposes of several hits, record them together and name that rule once. Per finding-triage, false-positive classification is itself a triage step the user can challenge; do not silently override.

Any unresolved ⚠ blocks the caller's next step. Return the report; the caller revises the draft, re-discharges its evidence claims, and re-runs gh-body-audit. Iterate until clean, or each remaining ⚠ is closed, as finding-triage defines closed; a closed ⚠ does not block.

What this skill does NOT do

Does not draft or file the body (caller's job). Does not maintain the rule set (gh-body-conventions is SSOT — update it first, then add the corresponding check here if a new mechanical rule is needed). Does not discharge gh-body-conventions § Evidence claims: that rule compares the body against the drafting session's record of what ran, which is exactly the context this check's subagent is denied — the caller discharges it in main context before invoking this check. Does not check hard-wrap, sub-clause line endings, or reference anchoring (whether a citation is pinned to a fixed revision as gh-body-conventions § References requires — the drafter's to check).