| name | esir-recipe-icon-style |
| description | Ingest the local recipe-icons-improvement-for-esir companion mod, audit ESIR recipe icon and visibility drift, and generate non-mutating batch review reports plus patch-ready planning data for icon, sorting, hiding, and signal cleanup work. |
ESIR Recipe Icon Style
Use this skill when work touches ESIR recipe icon readability, subgroup or order drift, Factoriopedia visibility, player-crafting visibility, recipe signal cleanup, or batch review of companion-style changes outside the game.
This skill treats the locally installed recipe-icons-improvement-for-esir companion mod as the primary baseline and keeps the workflow non-mutating by default.
Source Order
Read the sources in this order unless the user explicitly wants something else:
- Latest local companion zip or unpacked folder accepted by the probe, typically under
%APPDATA%\Factorio\mods\recipe-icons-improvement-for-esir*.zip
- Local QC runtime evidence:
.factorio-qc/dump-run-data-2/script-output/data-raw-dump.json
- ESIR repo source under
exotic-space-industries-remembrance/
- Mod Portal screenshots or changelog only as secondary confirmation
Do not treat Mod Portal screenshots as the primary spec when the local companion mod is available.
Default Workflow
1. Probe The Companion Baseline
Run the probe first so the skill starts from local truth instead of memory.
python .codex/skills/esir-recipe-icon-style/scripts/companion_mod_probe.py `
--output .codex/skills/esir-recipe-icon-style/output/companion-baseline.json
When you need drift detection against an older snapshot:
python .codex/skills/esir-recipe-icon-style/scripts/companion_mod_probe.py `
--compare .codex/skills/esir-recipe-icon-style/output/companion-baseline.json `
--diff-output .codex/skills/esir-recipe-icon-style/output/baseline-diff.json
The probe is expected to summarize:
- startup settings
- config gates from
0-config.lua
- loader order from
data-final-fixes.lua
- icon helper semantics
- sorting and hiding helper semantics
- rule-family coverage from
esir-21* through esir-43*
- overlay and background asset families
- feature candidates the skill may not model yet
2. Audit ESIR Prototypes
Use the audit script to build a best-effort static inventory before planning changes.
python .codex/skills/esir-recipe-icon-style/scripts/recipe_icon_audit.py `
--repo-root . `
--probe .codex/skills/esir-recipe-icon-style/output/companion-baseline.json `
--output .codex/skills/esir-recipe-icon-style/output/recipe-audit.json
The audit should stay conservative. If a prototype cannot be classified confidently, prefer manual-review-needed over guessing.
For direct companion icon-helper hits, the audit now tries to synthesize concrete proposed.icon_layers from the local companion rule expressions. If a helper expression stays dynamic or ambiguous, keep it strategy-only instead of fabricating layers.
By default, the audit keeps the report limited to ESIR-owned recipes plus recipes that resolve back to ESIR's declared dependency and touchpoint universe from .codex/esir/dependency-catalog.json. Use the wider mode only when you explicitly want companion spillover from unrelated active mods.
Common variants:
- include non-ESIR recipes when you want a wider sanity pass:
python .codex/skills/esir-recipe-icon-style/scripts/recipe_icon_audit.py `
--repo-root . `
--probe .codex/skills/esir-recipe-icon-style/output/companion-baseline.json `
--scope all-candidates `
--output .codex/skills/esir-recipe-icon-style/output/recipe-audit.json
--include-non-esir still works as a compatibility alias, but prefer the explicit --scope modes:
esir-and-dependencies (default)esir-onlyall-candidates
3. Normalize A Batch Manifest
Use the batch normalizer when you want one manifest that can drive both review and patch planning.
python .codex/skills/esir-recipe-icon-style/scripts/recipe_icon_batch.py `
--audit .codex/skills/esir-recipe-icon-style/output/recipe-audit.json `
--output .codex/skills/esir-recipe-icon-style/output/recipe-batch.json
You can also merge explicit entries for prototypes that need manual notes, missing art, or stronger review tags.
Common variants:
- merge guided overrides or missing-art notes:
python .codex/skills/esir-recipe-icon-style/scripts/recipe_icon_batch.py `
--audit .codex/skills/esir-recipe-icon-style/output/recipe-audit.json `
--extra-manifest .codex/skills/esir-recipe-icon-style/assets/examples/recipe-icon-manifest.example.json `
--output .codex/skills/esir-recipe-icon-style/output/recipe-batch.json
- narrow review output to one status, family, or prototype slice:
python .codex/skills/esir-recipe-icon-style/scripts/recipe_icon_batch.py `
--audit .codex/skills/esir-recipe-icon-style/output/recipe-audit.json `
--status manual-review-needed `
--family isotope-overlay `
--prototype ei-bio-oil-synthesis `
--output .codex/skills/esir-recipe-icon-style/output/recipe-batch.json
4. Render The Out-Of-Game Review Surface
Generate the HTML report, machine-readable JSON, and PNG contact sheet from the batch manifest.
python .codex/skills/esir-recipe-icon-style/scripts/render_recipe_icon_report.py `
--manifest .codex/skills/esir-recipe-icon-style/output/recipe-batch.json `
--output-dir .codex/skills/esir-recipe-icon-style/output/report
The report is meant for sanity checking outside Factorio. It should always show before and after behavior data, not icon previews alone.
The renderer can resolve icon assets from:
- repo-local ESIR mod folders
- sibling ESIR graphics-pack folders in the repo
- local Factorio data roots such as
base, core, and space-age
- installed mod folders or zips under
%APPDATA%\Factorio\mods
If an icon still cannot be resolved after those sources are checked, keep the placeholder and call it out in notes instead of fabricating a preview.
Use preview.resolved_sources in report.json as the provenance trail when you need to confirm whether a preview came from repo-local art, Factorio data, or installed mod archives.
Working Rules
- Keep the skill non-mutating by default. Analyze, diff, preview, and emit patch-ready snippets or manifests before touching gameplay files.
- Treat helper semantics from the local companion mod as the baseline, but map them into ESIR-first presets from references/esir-preset-map.md.
- Prefer the overlay-driven readability language first. Background plates, purging, hiding, and sorting are part of the broader behavior surface, not a reason to skip icon analysis.
- If local companion logic and QC dump evidence disagree, read the relevant rule file before deciding which side is stale.
- If a batch cannot be flattened exactly, render a clearly labeled placeholder slot instead of inventing a fake icon.
- Keep newly discovered companion features visible through baseline diffs. Do not silently collapse them into existing buckets.
Monitoring Modes
Use milestone monitoring by default:
- after the first baseline probe
- after the report schema is stable
- after the first implementation pass of the probe script
- before final validation
Session-sidecar monitoring is also acceptable during long implementation sessions, but do not present it as an always-on watcher. This skill is meant to support bounded re-checks, not background daemon behavior.
References
Resources
scripts/companion_mod_probe.py: summarize the companion mod and emit baseline diffsscripts/recipe_icon_audit.py: statically inspect ESIR prototypes and classify driftscripts/recipe_icon_batch.py: normalize audit data plus manual entries into one manifestscripts/render_recipe_icon_report.py: build report.html, report.json, and report-sheet.pngassets/examples/recipe-icon-manifest.example.json: starter manifest for guided or batch review
