Hoi4 Review Debug

HOI4 review and debug

Set scope and choose one evidence lane

A request to review, explain, or diagnose authorizes read-only investigation, not edits. Enter the fix lane only when the user asks to change the mod. Treat balance, narrative, and visual taste as design choices unless project guidance defines an objective contract; obtain approval before changing them.

Choose the cheapest lane that can answer the request. Read only that lane's references; do not preload references from unrelated lanes. Lead review output with concrete findings ordered by impact and supported by file/line evidence; if no defect is established, say so and list the remaining test gaps.

For any lane that judges or changes an existing player-facing feature, also build the code-to-visible-meaning map in semantic-intent-audit.md. For a broad review or applied refactor, additionally use the base review-checklist.md.

• One symptom, parser/scope bug, or log triage: read the matching section of review-workflows.md, reproduce the symptom, and trace its first failing caller. Search field-tested-pitfalls.md only after the evidence identifies a matching failure class. CWTools squiggles are not evidence by themselves; see pdx-language.md.
• Existing-feature review, refactor, or fix: trace its caller, scope, player-visible promise, state lifecycle, AI path, and dependencies. Enter the edit loop only when the request authorizes a change.
• Whole-mod health or improvement: follow improve-existing-mod.md and read mod-doctor.md before running the baseline audit. Add gameplay-balance-ux-review.md only when player experience, balance, or design is in scope.
• Performance or lifecycle/save risk: read performance-debugging.md, then measure cadence, scope count, state creation, invalidation, cleanup, and save/reload behavior before proposing a change.
• Localisation or dynamic text: read localisation-deep-dive.md. Search the localisation sections of field-tested-pitfalls.md only for a reproduced consumer-specific failure or a bulk cleanup.
• GUI, GFX, or artwork: use the base GUI/localisation reference. Read icon-audit.md only for missing, default, mismatched, or dependency-bound artwork.
• Map/history or version update: use the matching section of review-workflows.md; for a game-version migration follow version-migration.md.
• Template audit: follow the builder's verify-template.md and verify the target build, placeholders, schema, current consumer, dependency chain, and runtime status separately.
• Media footprint or conversion: follow optimize-media.md.
• Native crash: ask for the exact pre-crash action timeline and governing jurisdiction, then read native-crash-reverse-engineering.md before native analysis. Never infer jurisdiction from language or broaden one authorization into tool installation, static decompilation, or live debugging.
• Runtime test: only after explicit consent, follow the builder's test-mod.md. Isolate the playset, test the smallest scenario, inspect fresh logs, and restore settings.

Establish evidence

Inspect target guidance, version, dependencies, playset, git status, changed files, definitions, callers, and the newest relevant log. Use installed schema and current vanilla/dependency consumers for unfamiliar tokens. Distinguish parser errors, semantic errors, runtime behavior, and optional-media warnings.

Before judging or optimizing a feature, read its names, descriptions, options, tooltips, scripted-localisation branches, GUI labels, and character text. Map each code ID to its visible meaning and player-facing promise. Never identify a character or mechanic by transliterating an internal token. Treat any code/localisation disagreement as a finding to resolve, not as permission to ignore the localisation.

Select only the cheapest matching read-only tool:

• scripts/audit-hoi4-mod.ps1: build a cross-file health baseline covering event and scripted-object graphs, strong localisation/GFX/resource links, duplicate/orphan definitions, periodic hot-path heuristics, and comment coverage. It can resolve the active playset, compare changed files or a prior baseline, apply expiring suppressions, audit media, and emit JSON, Markdown, or SARIF. When -GameRoot is supplied it also target-scans installed DLC interface trees and distinguishes same-basename texture extension mismatches. Treat lead findings as investigation targets, not edit authority.
• scripts/analyze-hoi4-log.ps1: prioritize and compare logs.
• scripts/audit-localisation.ps1: inspect BOMs, headers, suffixes, duplicate keys, colour markers, nested tokens, dynamic variables, and functions.
• ../hoi4-pdx-modding/scripts/audit-visible-flag-localisation.ps1: find has_country_flag requirements that would expose an unlocalised internal flag ID in generated check/cross tooltips; distinguish visible requirements, potential visibility paths, and hidden_trigger exclusions.
• scripts/audit-hoi4-map.ps1: check map IDs/colors and history membership.
• scripts/audit-vanilla-overrides.ps1: inventory overrides, replace_path, hashes, and migration gates.

Native crash tools and authorization stages are defined only in the native crash reference. Do not import that workflow into ordinary script or log diagnosis.

Fix the first parser failure in each file before cascades. For every finding, state the triggering path, failure mechanism, user-visible effect, and smallest remedy. Do not apply conventions from another mod or old version universally.

When reviewing generated content, search for MOD, sample tags, example IDs, placeholder text, copied asset paths, unresolved localisation, and conflict markers. Brace balance alone does not prove scopes, lifecycle, AI behavior, history IDs, or GUI/GFX wiring.

Verify and hand off

Follow the sibling hoi4-pdx-modding Validate proportionally lanes. Do not run the full validator, Mod Doctor, focused audits, or a fresh-log comparison because a small edit exists. User AI quota is not free. Inspect-only diffs are complete after a careful read.

When scripts are warranted, run the cheapest matching check on the edited paths. Broader audits and log comparison belong to whole-mod, rename, GUI/map, compatibility, release, or migration work. Non-trivial static work ends with a consent question: does the user want AI-assisted in-game testing? Never open Steam, change launch options, alter a playset, or start HOI4 without that consent. Do not offer a Steam prompt after inspect-only work unless the user asked.

For every applied fix or refactor, update the canonical mod technical document, current development handoff, and readable comments for affected contracts. Review their accuracy alongside code and localisation before completion.

For a whole-mod improvement, fill the bundled assets/templates/mod-improvement-report.md with the before/after baseline, approved scope, evidence, deferred design choices, and remaining risks. Never silently turn a balance preference or narrative taste into a defect.

For an approved test, use computer-use when available and follow the builder's runtime workflow. Enable only the target mod, plus exact required dependencies for a submod; use -debug; start a new game from the earliest available bookmark; exercise the changed content; read the logs; improve and retest; then restore any launch and playset settings changed for the test. Report confirmed results, reasoned risks, and any interactions still requiring the user.