---

description: "Convert an audit report's findings into GitHub issues with completeness checks" argument-hint: "<path-to-audit-report>"

Audit → GitHub Issues Publisher

Turn a finished audit report (docs/audits/AUDIT_<TYPE>_<DATE>.md) into one GitHub issue per actionable finding, with dedup, label reconciliation, and a completeness gate so nothing silently slips through.

Shared protocol (read, do not restate): .claude/commands/_audit-common.md — the Base Per-Finding Format (the exact field set this skill parses) and the Deduplication (MANDATORY) flow. Severity scale: .claude/commands/_audit-severity.md.

This skill is the only place issues are created. Audit skills stop at writing the report; they never call gh issue create.

Process

1. Load + parse the report

Read $ARGUMENTS (e.g. docs/audits/AUDIT_RENDERER_2026-04-04.md). Each finding block follows _audit-common's Base Per-Finding Format: ### <ID>: <Title> then Severity, Dimension, Location, Status, Description, Evidence, Impact, Related, Suggested Fix. Extract those fields per finding; ID + Severity + Location + Status are required, the rest carry into the issue body.

2. Path-validation gate (run first, before judging any finding)

.claude/commands/_audit-validate.sh        # exit 1 on any STALE backticked path

This is the #1114 / TD7-050 gate. It fails fast when a report was written against pre-split paths — a Location: pointing at a file that is now a directory. Common splits to expect (old single file → current dir; the old paths are deliberately un-backticked since they no longer exist): archive.rs → crates/bsa/src/archive/, render.rs → byroredux/src/render/, import/walk.rs → crates/nif/src/import/walk/, blocks/collision.rs → crates/nif/src/blocks/collision/, blocks/tri_shape.rs → crates/nif/src/blocks/tri_shape/. byroredux/src/systems.rs and byroredux/src/cell_loader.rs survive as thin re-export shims beside their systems/ and cell_loader/ dirs — re-point a Location there to the owning submodule (e.g. byroredux/src/systems/particle.rs).

3. Filter by status

Process only findings with status NEW. Existing: #NNN and Regression of #NNN are already tracked upstream — record them in the summary, do not re-file.

4. Validate each NEW finding against current code

• Read the referenced file at the symbol (not the line — line numbers drift; trust grep -rn <fn/struct>).
• Re-map before judging. If the Location: file no longer exists but the code does (a split, not a fix), resolve to the current submodule and update the finding's path before filing. Do NOT mark a path move as STALE. Examples: material logic lives at byroredux/src/material_translate.rs (translate_material) + crates/core/src/ecs/components/material.rs (Material::resolve_pbr); the per-frame particle system is byroredux/src/systems/particle.rs (apply_emitter_params), fed by crates/nif/src/import/walk/emitter.rs (extract_emitter_params / extract_emitter_rate).
• Classify: CONFIRMED (bug still present) → file it; STALE (already fixed) → skip, record in summary; UNVERIFIABLE (cannot confirm against code) → skip, record in summary.

5. Deduplicate against open issues

Follow _audit-common's Deduplication flow:

mkdir -p /tmp/audit
gh issue list --repo matiaszanolli/ByroRedux --limit 400 --json number,title,state,labels \
  > /tmp/audit/issues.json

Match each CONFIRMED finding's keywords against existing open issue titles. On a match, skip and record Existing #NNN in the summary. The list above is open-only (gh issue list defaults to --state open), so check closed issues per finding with gh issue list --repo matiaszanolli/ByroRedux --state closed --search "<keywords>" --json number,title; if a closed issue matches and the bug is back, file it but title/note it as a regression of #NNN.

6. Reconcile labels against the live repo (do this once, before any create)

The set of labels that exist in the repo is authoritative — gh issue create rejects an unknown label. Pull the live set first:

gh label list --repo matiaszanolli/ByroRedux --limit 200 --json name --jq '.[].name' \
  > /tmp/audit/labels.txt

Every label this skill applies MUST appear in that file. The four axes are defined in _audit-common's Issue Labels section — do not restate them; the summary below is the publish-time mapping only.

Severity (always exactly one): critical · high · medium · low · info.

Type (always exactly one): bug · enhancement · documentation. There is no maintenance label — tech-debt findings use the tech-debt domain label plus bug; doc-rot findings use documentation + doc-rot.

Domain (one or more) — as of 2026-08-21 nearly every audited subsystem has its own label. Map the finding's subsystem directly:

| Finding subsystem | Domain label(s) | |-------------------|-----------------| | NIF parser / block dispatch | nif-parser (primary) + nif (format tag) | | NIFAL canonical translation | nifal + the subsystem it lands in (nif-parser / renderer) | | ESM / CELL / WRLD / plugin loading | esm-plugin | | BSA / BA2 / CSG archive readers | import-pipeline (no bsa label — flag the gap) | | Vulkan renderer / RT / denoiser | renderer (+ vulkan / pipeline / memory) | | GLSL / SPIR-V sources, shader contract | shaders (+ renderer) | | Water — WATAL translation, buoyancy, waterline | water | | Terrain / LOD / sky / weather / ground cover / worldspace (EXAL, SKYAL) | terrain-exterior (+ renderer / shaders for the GPU half) | | Inventory / containers / loot / consumables / combat / AI packages / locomotion | gameplay + the narrower tag (inventory / combat / ai / quests / dialogue) | | BGSM / CDB / HKX / FaceGen / MenuXml / game-detect readers | import-pipeline (no own label — flag the gap) | | SDK, debug server / protocol / byro-dbg, launcher, settings-io | tech-debt (no own label — flag the gap) | | Physics — Havok→Rapier, colliders, ragdoll (PHYSAL) | physics | | SpeedTree (.spt) | speedtree | | Character rulesets — ActorValues, perks, leveling (CHARAL) | character | | Audio (M44) | audio | | Scaleform / SWF UI (R4 + M48) | ui | | Save/load (M45) | save-load | | Papyrus / ObScript / scripting runtime | scripting | | ECS storage / queries / scheduler | ecs | | Animation runtime / KF import / clip sampling | animation (+ ecs / nif-parser for the side it lands in) | | Cargo dependency drift, pins, MSRV | dependencies (+ tech-debt) | | GPU sync (semaphores, fences, barriers) | sync | | CPU lock ordering / races / access declarations | concurrency | | Platform / windowing, audit infrastructure | tech-debt (no own label — flag the gap) |

Game (zero or more) — apply whenever the finding is specific to a title, in addition to the domain label. A per-game audit report labels every finding with its game; a cross-cutting audit labels only the findings that name a specific title's data: game:fnv · game:fo3 · game:fo4 · game:fo76 · game:skyrim · game:oblivion · game:starfield.

Cross-cutting kind tags (zero or more, alongside the domain):

• doc-rot — the defect is documentation drifted from code (stale ROADMAP row, SKILL doc naming a deleted symbol, a comment describing removed behaviour). Pair with documentation as the type.
• test-gap — the defect is missing/vacuous/non-asserting coverage. Pair with the domain of the code left untested.
• tech-debt — dead code, duplication, stale markers, magic numbers, oversized files.

If a finding genuinely has no reasonable existing label, file it with severity + bug only and flag the missing-label gap in the summary. Do not gh label create ad hoc — new labels are a deliberate repo decision, not a per-publish side effect.

Report-family defaults — the AUDIT_<TYPE>_<DATE>.md filename selects a default domain/type; a per-finding Dimension/domain always overrides it:

| Report (AUDIT_<TYPE>_*.md) | Default domain | Type | Extra | |------------------------------|----------------|------|-------| | AUDIT_RENDERER_* | renderer | bug | — | | AUDIT_ECS_* | ecs | bug | — | | AUDIT_CONCURRENCY_* | concurrency | bug | sync on GPU-side findings | | AUDIT_NIF_* | nif-parser | bug | nif | | AUDIT_NIFAL_* | nifal | bug | + the landing subsystem | | AUDIT_ESM_* | esm-plugin | bug | — | | AUDIT_PHYSICS_* | physics | bug | water on the WATAL buoyancy sink | | AUDIT_CHARACTER_* | character | bug | — | | AUDIT_UI_* | ui | bug | — | | AUDIT_SAVE_* | save-load | bug | — | | AUDIT_AUDIO_* | audio | bug | — | | AUDIT_SPEEDTREE_* | speedtree | bug | terrain-exterior | | AUDIT_SCRIPTING_* | scripting | bug | — | | AUDIT_PAPYRUS_* | scripting | bug | — | | AUDIT_PERFORMANCE_* | performance | bug | + the landing subsystem | | AUDIT_SAFETY_* | safety | bug | + the landing subsystem | | AUDIT_RUNTIME_* | (per finding) | bug | performance on fps/draw-call drift | | AUDIT_EXTERIOR_* | terrain-exterior | bug | water / shaders / renderer per finding | | AUDIT_GAMEPLAY_* | gameplay | bug | inventory / combat / ai / quests / dialogue per finding | | AUDIT_PARSERS_* | import-pipeline | bug | game:* where title-specific | | AUDIT_TOOLING_* | tech-debt | bug | — | | AUDIT_FNV_* / AUDIT_FO3_* / AUDIT_FO4_* / AUDIT_SKYRIM_* / AUDIT_OBLIVION_* / AUDIT_STARFIELD_* | (per finding) | bug | the matching game:* on every finding + legacy-compat | | AUDIT_LEGACY_COMPAT_* | legacy-compat | bug | game:* where title-specific | | AUDIT_TECH_DEBT_* | (per finding) | bug | tech-debt | | AUDIT_INCREMENTAL_* / AUDIT_REGRESSION_* | (per finding) | bug | — |

For AUDIT_TECH_DEBT_* the final set is <severity>,<domain?>,tech-debt,bug. Doc-rot findings — in any report family — swap bug → documentation and add doc-rot; coverage findings add test-gap. For everything else: <severity>,<domain>,bug, plus game:<title> whenever the finding is specific to one game's data.

7. Build the completeness checklist (per CONFIRMED finding)

Append to each issue body. Drop rows that can't apply (e.g. omit FFI if the fix is NIF-only):

## Completeness Checks
- [ ] **UNSAFE**: If the fix adds `unsafe`, a safety comment states the upheld invariant
- [ ] **SIBLING**: Same pattern checked in related files (other shader types, other block parsers)
- [ ] **DROP**: If Vulkan objects change, the Drop impl is still reverse-order correct
- [ ] **LOCK_ORDER**: If a RwLock scope changes, TypeId-sorted acquisition is preserved
- [ ] **FFI**: If the cxx bridge is touched, pointer lifetimes across the boundary are sound
- [ ] **CANONICAL-BOUNDARY**: If the fix touches `byroredux/src/material_translate.rs` (`translate_material`), `Material::resolve_pbr` (`crates/core/src/ecs/components/material.rs`), or the emitter params in `crates/nif/src/import/walk/emitter.rs` (`extract_emitter_params` / `extract_emitter_rate`), per-game logic stays at the NIFAL parser→`Material` boundary — never pushed into shaders/renderer, never re-derived at render time. See `/audit-nifal`.
- [ ] **TESTS**: A regression test pins this specific fix

8. Create the issue

gh issue create --repo matiaszanolli/ByroRedux \
  --title "<ID>: <title>" \
  --body  "<description + evidence + impact + suggested fix + completeness checks>" \
  --label "<severity>,<domain>,<type>"

--label takes a comma-separated list. Every token must be in /tmp/audit/labels.txt (step 6). If gh rejects a label, the reconciliation missed one — fix the mapping, do not drop the finding silently.

9. Snapshot to local tracking

mkdir -p .claude/issues/<NUMBER>

Write .claude/issues/<NUMBER>/ISSUE.md with the finding details.

Immutable-snapshot convention (TD10-001 / #1156): this file is the issue as filed, not a live mirror. GitHub is authoritative for current state — query gh issue view <N> --json state when live state is needed. Do not write a State:/Status: field. The convention applies symmetrically to INVESTIGATION.md and any sibling created by /fix-issue.

10. Completeness summary (the gate)

Every NEW finding must reach a terminal action — created, skipped-as-duplicate, or skipped-with-reason. Print the table and assert the count matches: NEW findings parsed == (Created + Skipped). A NEW finding that is neither created nor consciously skipped is a publish bug.

| Finding | Action | Reason | |---------|--------|--------| | REN-001 | Created #42 | NEW, CONFIRMED | | REN-002 | Skipped | Existing #38 | | REN-003 | Skipped | STALE (fixed in composite.rs) | | BSA-004 | Created #43 | NEW, CONFIRMED — labeled import-pipeline (no bsa label) |

Flag any subsystem-without-a-label mappings (step 6) here so the gap is visible.

11. Suggest next step

For each created issue:

Fix with: /fix-issue <number>