Angelicismo01/isaackdb

Isaac modding workflow

Never invent a Binding of Isaac API because its name sounds plausible. A plausible name is not evidence. Search; if it remains absent, say UNVERIFIED.

Route the task

1. Inspect the user's mod before editing: metadata.xml, main.lua, content XML, includes, dependency copies, and target/version notes.
2. Identify the target build and whether REPENTOGON/libraries are available. If unspecified, use the repository pin as a research baseline only. Do not claim the user's installed runtime matches that pin or is future-compatible.
3. Translate the request into scope, ownership, lifetime, co-op, resources, dependencies, compatibility, performance, and testing requirements. For a boss/character/stage or large system, write a short specification first. If visuals change, inventory the required assets and read graphics production rules. Create art only when needed; define the sheet/animation contract before final PNG/ANM2 work.
4. Search indexes/tasks.json, aliases, then exact symbols. Read knowledge/INDEX.md and the generated source-linked record only for the relevant domain.
5. Search both vanilla and REPENTOGON records when REPENTOGON is enabled; its explicit modification record wins for that target.
6. Check callback semantics, version precision, conflicts/issues, feasibility, local co-op, state lifetime, XML/resources, performance, and compatibility.
7. Choose a dependency-labelled pattern. Distinguish a scaffold from a golden static reference; runtime_tested: false never means gameplay-verified.
8. Implement the smallest architecture-compatible change. Reuse existing modules, IDs, callbacks, helpers, and style. Do not create a replacement main.lua before understanding the project.
9. Run python scripts/validate_kb.py --project <mod-folder> --ecosystem <vanilla|repentogon> and the relevant audits under prompts/.
10. Report dependencies, exact evidence used, validation limits, and targeted in-game tests.

When retrieval needs precision:

• Search indexes/symbols.json for exact APIs/enums/XML.
• Search indexes/callbacks.json for arguments, filters, returns, and REPENTOGON modifications.
• Search indexes/aliases.json for natural-language terms.
• Search indexes/errors.json for symptom-driven routing.
• Use knowledge/feasibility.md before unusual work.
• For exact semantics, read the record's source_path under the ignored .cache/upstreams/<source>/ checkout after checking its HEAD against the registry pin. On drift, read the pinned file with git show <pin>:<path>; do not treat the newer checkout as pinned evidence. If absent, run the curated-safe update workflow and review source drift before accepting a new pin.

Do not reimplement a stage, custom-health, minimap, configuration, achievement, or completion system until current native REPENTOGON and maintained-library options have been compared. Do not mix IsaacScript/TypeScript or a library into ordinary Lua unless the project already uses it or the user accepts it.

Non-negotiable checks

• Confirm callback arguments, filter, return type, cancellation/replacement behavior, and whether REPENTOGON modifies the vanilla callback.
• Confirm class member spelling and version badge in a normalized record.
• Confirm entity type/variant/subtype and XML attributes from current records or extracted local resources. Never guess numeric IDs or resource paths.
• Use cache callbacks for player stats and familiar counts. Use explicit callback filters where documented. Avoid full room scans in per-frame/render callbacks unless measured and narrowly filtered.
• Keep player ownership and local co-op explicit. Do not assume player index 0.
• Keep save data JSON-safe; load only after a run starts and save at documented lifecycle points. Preserve defaults when decoding old or partial saves.
• Do not copy or modify installed game assets. Derived path notes are allowed.
• Treat graphics as game assets: match actual PNG crops, ANM2, Lua/XML and animation events. Placeholders are developmental, never final. Without an observed in-game visual test, record visual_runtime_tested: false.

Read only what the task needs

• API/callback question: generated catalogs plus knowledge/callbacks/critical-callbacks.md.
• XML/resource/animation/room work: the matching guide under knowledge/ and vendored schemas under schemas/.
• New sprites, costumes, reskins or animation work: graphics production, contract template, and visual QA. Run scripts/gfx_audit.py <mod-folder>; use --release for the final-asset/readiness gate.
• Implementation: patterns/INDEX.md and the matching pattern family.
• Debugging: knowledge/debugging/decision-tree.md.
• Libraries: knowledge/libraries/index.md; read the library's current public docs/code before calling it.

When trusted references do not contain a requested API, say that it is unverified or nonexistent in the indexed revisions. Do not fabricate a fallback.