crab-love-stepwise-debug

name	crab-love-stepwise-debug
description	Use this skill when working on the Crab Love 8086 project or a similar emu8086/DOSBox linear galgame prototype that should be built through small standalone tests, validated step by step, and documented with walkthrough-style notes. It is especially useful when adding or fixing sprites, scenes, textbox rendering, text output, simple animation, linear page playback, or DOSBox runtime behavior.

Crab Love Stepwise Debug

Overview

This skill captures the proven workflow used to make steady progress on the Crab Love 8086 project:

• prefer tiny standalone tests over large integrated guesses
• validate first in emu8086 for compile/debug
• validate final runtime behavior in DOSBox
• freeze each success as a walkthrough before building on it

Use this skill when the task is part of the same project family:

• 8086 assembly
• Mode 13h
• emu8086
• DOSBox
• pixel sprites
• dialogue pages
• scene composition
• linear page-by-page playback

Core Workflow

Follow this order unless there is a very strong reason not to:

1. Identify the smallest unit under change.
2. Build or reuse a standalone test under tests/ for that exact unit.
3. Keep the first passing version minimal. Do not mix multiple new concerns.
4. Compile in emu8086.
5. Judge final visual/runtime quality in DOSBox whenever possible.
6. Only integrate into the formal runtime after the standalone test is stable.
7. After success, record the result in a new Step/walkthroughN.md.

Default Engineering Rules

• Prefer BIOS text output over custom font rendering if the goal is simply to show readable dialogue fast.
• Prefer A000 direct VRAM writing over BIOS single-pixel drawing when speed matters.
• For this project, treat DOSBox as the final presentation environment and emu8086 as the compile/debug environment.
• If an optimization increases instability in emu8086, revert to the last stable approach and document the failed branch.
• Keep new work decision-light: reuse working scene, textbox, actor, and animation paths instead of inventing parallel systems.
• When a visual bug appears in the integrated runtime, compare against the standalone test that already passed for that subsystem.

What to Build First

If multiple things are broken or unfinished, prioritize in this order:

1. compile stability
2. single-unit standalone test
3. DOSBox runtime validation
4. formal runtime integration
5. polish

For example:

• sprite issue: fix in a sprite-only or actor-only test first
• scene issue: fix in the scene test first
• textbox or text issue: fix in the textbox/text test first
• page issue: fix in the page mockup test first
• story issue: update text.md, then texts.inc, then pages.inc

References

• Read workflow.md for the project-specific lessons learned from the existing walkthroughs.
• Read text.md when changing story structure, page order, or dialogue.
• Read Step/walkthrough*.md when you need the original reasoning behind a stable solution.

Output Expectations

When using this skill:

• explain which small unit is being tested
• prefer creating or updating one focused test before broad integration
• state whether the result should be judged in emu8086, DOSBox, or both
• preserve the discipline of documenting passing milestones