# Adv Debug

> Debug and analyze an ADV.JS project using deterministic checks. Use when validating scripts, resolving missing character or scene references, finding dead branches or orphan scenes, measuring route coverage, inspecting compiled project context, or replaying a failing narrative path.

- Skill: `yunyoujun/adv-debug` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yunyoujun/adv-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yunyoujun/adv-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yunyoujun (https://skillmd.com/u/yunyoujun)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yunyoujun/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

```bash
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:

```bash
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

```bash
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:

```bash
# 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:

```json
{
  "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
}
```

Note: `kind: "dead"` nodes appear for options that have no resolvable next node — those are dead paths to fix.

Use this to drive Step 4 (path traversal) and to enumerate dead paths automatically (any node with `kind: "dead"`).

For a quick aggregate instead of the full graph, use `coverage` — it runs the same static analysis and reports the headline numbers:

```bash
adv debug coverage adv/chapters/chapter_01.adv.md
# or machine-readable:
adv debug coverage adv/chapters/chapter_01.adv.md --format=json
```

**Project-wide mode**: omit the script to scan every chapter and get an
aggregate table in one call — this is the fastest way to produce the Step 6
coverage report:

```bash
adv debug coverage                 # all chapters under the game root
adv debug coverage --format=json   # machine-readable totals + per-chapter
```

Text output:

```
# Branch Coverage

Scenes reachable : 3/3 (100%)
Choice points    : 2
Options          : 4
Endings reachable: 2
Distinct paths   : 4
Dead options     : 0

✓ No orphan scenes or dead paths detected.
```

JSON adds `orphanScenes`, `unreachableNodes`, `distinctPaths`, and
`pathsTruncated` (true when a very branchy script exceeds the 5000-path
enumeration cap). `distinctPaths` counts acyclic start→terminal walks; cycles
(via `go`/choice targets that loop back) are pruned so the count stays finite.

> Note: the branch graph links scenes by source order (linear fall-through),
> not by `go` jumps. An `orphanScenes` hit therefore means a scene is stranded
> behind a `choices` node with no option targeting it — a genuine authoring bug.

Present a summary table per chapter using these numbers:

```
| Chapter | Scenes | Choice Points | Options | Paths | Dead |
|---------|--------|---------------|---------|-------|------|
| CH01    | 3      | 2             | 4       | 4     | 0    |
| CH02    | 2      | 1             | 2       | 2     | 1    |
```

### Step 4: Test Branch Paths via Play

For each chapter, systematically play through all branch paths:

```bash
# Start a new session for the chapter
adv play adv/chapters/chapter_01.adv.md --session-id debug-ch01-path1 --json

# Advance through the story
adv play next --session-id debug-ch01-path1 --json

# When choices appear, select each option in separate sessions
adv play choose 1 --session-id debug-ch01-path1 --json
```

For each branch:

1. Create a separate session with a descriptive ID (e.g., `debug-ch01-path1`)
2. Advance until a choice point
3. Take one choice per session
4. Continue until the end or next choice
5. Record what was encountered

### Step 5: Detect Issues

Look for these common problems:

#### Dead Paths

- A choice leads to content that abruptly ends without resolution
- A branch has no continuation in the next chapter

#### Inconsistencies

- A character referenced in dialog doesn't have a `.character.md` file
- A scene referenced in `【】` doesn't have a `scenes/*.md` definition
- Character behavior contradicts their personality in `.character.md`
- Terminology doesn't match `glossary.md` definitions

#### Structural Issues

- Chapters with no branch points (purely linear)
- Unbalanced branches (one path much longer than alternatives)
- Missing chapter transitions

### Step 6: Generate Coverage Report

Start from the project-wide aggregate (`adv debug coverage`), then annotate
chapters that the table flags (non-zero Dead / Orphan). Present findings in a
structured report:

```
## Branch Coverage Report

### CH01 — 转学第一天
- Branch 1 (line 25): "好的，麻烦你了" / "不用了，我自己逛逛就好"
  - Path A: ✅ Continues to line 30
  - Path B: ✅ Continues to line 30
- Branch 2 (line 42): "想看看文学社" / "想看看天文社"
  - Path A: ✅ Leads to scene change
  - Path B: ✅ Leads to scene change

### Issues Found
1. ⚠ CH02 branch B → CH03 lacks transition paragraph
2. ❌ BAD END path not yet defined
3. ℹ CH03 has only 1 branch point (consider adding more player agency)

### Recommendations
1. Add a transition scene between CH02 branch B and CH03
2. Define the BAD END trigger conditions and content
3. Consider adding a branch point in CH03 after the flashback scene
```

### Step 7: Clean Up Sessions

After testing, clean up all debug sessions:

```bash
adv play reset --session-id debug-ch01-path1
adv play reset --session-id debug-ch01-path2
# ... etc
```

## Analysis Checklist

- [ ] All `.adv.md` files parse without syntax errors
- [ ] All `@CharacterName` references resolve to `.character.md` files (or run `adv check --fix`)
- [ ] All `【Place】` references resolve to `scenes/*.md` files (or run `adv check --fix`)
- [ ] No `kind: "dead"` nodes in any chapter's branch graph
- [ ] Character dialog matches personality descriptions
- [ ] Terminology matches glossary definitions
- [ ] Each chapter has at least one meaningful branch point (see `choicePoints` in branch graph)
- [ ] Story transitions between chapters are smooth
- [ ] All ending paths (TRUE/NORMAL/BAD) are reachable

## Guidelines

- Be thorough but prioritize critical issues (dead paths, syntax errors) over style suggestions
- Present findings clearly with file paths and line references
- Offer concrete fix suggestions, not just problem descriptions
- Prefer `adv debug branches --format=json` over hand-counting branches — the AST never lies
- For trivially auto-fixable issues (unresolved character/scene refs), run `adv check --fix` first and report what remains
- Ask the user if they want you to fix the issues found