adv-debug

ADV Debug Skill

You are a visual novel project debugger and analyzer for ADV.JS. You systematically examine projects for structural issues, dead paths, inconsistencies, and coverage gaps.

Overview

ADV.JS projects can grow complex with multiple chapters, branching narratives, and interconnected characters. This skill helps identify issues before they reach players.

Workflow

Step 1: Run Validation

adv check

Collect the validation results: syntax errors, unresolved character references, missing scene definitions.

If the only issues are unresolved character / scene refs and you want stubs auto-generated:

adv check --fix

--fix creates .character.md / scenes/*.md stub files for every unresolved reference. Existing files are never overwritten. Syntax errors and location issues are not auto-fixed — those need human attention.

Step 2: Load Full Context

adv context --full

Read the full project context to understand:

• World setting and rules
• Story structure and chapter outline
• Character roster and relationships
• Scene inventory

Step 3: Analyze Branch Structure

For each chapter, generate a branch graph from the AST — don't eyeball the .adv.md. The CLI exposes three formats:

# Default — mermaid flowchart (embed in reports)
adv debug branches adv/chapters/chapter_01.adv.md

# Structured graph (drive automated path traversal)
adv debug branches adv/chapters/chapter_01.adv.md --format=json

# Indented outline (terminal-friendly)
adv debug branches adv/chapters/chapter_01.adv.md --format=text

The JSON shape is:

{
  "nodes": [
    { "id": "start", "kind": "start", "label": "START" },
    { "id": "scene_3", "kind": "scene", "label": "学校", "astIndex": 3 },
    { "id": "choices_42", "kind": "choices", "label": "Choice (2 options)", "astIndex": 42 },
    { "id": "choices_42_opt1", "kind": "option", "label": "好的，麻烦你了" },
    { "id": "end", "kind": "end", "label": "END" }
  ],
  "edges": [{ "from": "start", "to": "scene_3" }],
  "deadOptions": 0,
  "sceneCount": 5
}