puzzle-design-kb/.opencode/skills/qa-dependency-graph/SKILL.md

---
name: qa-dependency-graph
description: Analyzes walkthroughs and dependency graph mermaid diagrams, and fixes them
---
# QA Dependency Graph Skill

Systematic validation and repair of puzzle dependency graphs for point-and-click adventure games.

## Purpose

Audit an existing dependency graph to identify and fix structural errors, orphaned nodes, and layout issues. Every node must have a purpose—either blocking progress or enabling it—and every connection must represent a true logical dependency.

## What This Graph Represents

### Locks and Keys

Adventure games are fundamentally about **locks** (obstacles) and **keys** (solutions). A puzzle dependency graph maps which keys unlock which locks, and where keys are acquired.

```
PROBLEM: Gnome won't talk
    ↑
    │ (enabled by)
    │
ACTION: Give nightingale to gnome
    ↑
    │ (requires)
    │
OUTCOME: Have nightingale
    ↑
    │ (enabled by)
    │
ACTION: Trade with pawn broker
```

### Node Types

| Prefix | Type | Definition |
|--------|------|------------|
| `A_` | Action | Player takes action: `A_PICK_UP_FLOWER`, `A_TALK_TO_FERRYMAN` |
| `O_` | Outcome | Result of action: `O_RECEIVE_RABBIT_FOOT`, `O_LEARN_SPELL` |
| `P_` | Problem | Obstacle to overcome: `P_DOOR_LOCKED`, `P_GNOME_WON'T_LISTEN` |
| `C_` | Consequence | Gateway/convergence: `C_ALL_GNOME_ITEMS`, `C_GATE_OPENED` |
| `UNLOCK_` | Unlock | Major unlock gateway: `UNLOCK_ISLAND_TRAVEL`, `UNLOCK_GNOME_ACCESS` |
| `START` | Start | Game beginning node |
| `END` | End | Game completion node |

### What This Graph is NOT

- **Walkthrough order**: The sequence you play through the game
- **Scene-by-scene narrative**: What happens in each room
- **Locked choice mechanics**: Player-selectable options that don't block progress

## Validation Checklist

### Node Rules

- [ ] Every node has at least one INPUT edge (except `START`)
- [ ] Every node has at least one OUTPUT edge (except `END`)
- [ ] Every `A_` action connects to its resulting `O_` outcome
- [ ] No orphaned nodes (nodes floating without connections)

### Lock/Unlock Rules

- [ ] Locked choices (pick 1-of-N rewards) show items as **UNLOCKED**, not as sequential trades
- [ ] Major unlocks (Magic Map, etc.) have dedicated gateway nodes when 5+ lines would cross
- [ ] Gateway nodes are concrete and singular (`UNLOCK_TRAVEL` not `UNLOCK_EVERYTHING`)

### Dependency Rules

- [ ] No batched transitive dependencies: if `A→B→C` and `C` specifically requires `A`, then `A→C` must exist
- [ ] Sequential walkthrough order ≠ logical dependency
- [ ] "Going to location" ≠ "Unlocking location"

### Layout Rules

- [ ] Top-down flow: `START` at top, `END` at bottom
- [ ] Fan-out model: parallel paths spread apart, then converge
- [ ] Only `START` and `END` outside subgraph groupings
- [ ] Area titles are prominent and readable
- [ ] Areas use index-based color palette

## Dangling Node Detection

Run the detection script to identify orphans, dead-ends, and undefined references:

```bash
cd /path/to/repo
./.opencode/skills/qa-dependency-graph/scripts/check-dangling-nodes.sh /path/to/chart.mmd
```

### Interpreting Results

**Orphan nodes** (no input edge):
- Usually means the node is disconnected from its prerequisite
- Fix: Add edge from the node's logical prerequisite
- If truly optional, add note explaining it

**Dead-end nodes** (no output edge):
- May be acceptable for terminal outcomes or truly optional content
- Check: Does this item ever get used? If yes, fix the connection

**Undefined references**:
- Node is referenced in an edge but never defined
- Fix: Add the node or correct the edge target

## Research Protocol for Orphaned Nodes

For EACH orphan node, follow this escalation path:

### Step 1: Search Walkthroughs

Use `@general` agent to search local walkthrough files:

```
Search query: "what is [orphan node name] used for" or "where is [item] used"
Example: "what is the rare book used for in king's quest vi"
```

Look in:
- `src/walkthroughs/[game-name]/*.html`
- `src/walkthroughs/[game-name]/*.md`

### Step 2: Web Search

If not found in walkthroughs, search the web:

```
Search query: "[game name] [orphan node] what is it for" or "[game name] [item] puzzle solution"
Example: "king's quest vi rare book what is it for"
```

Use `@general` agent with `websearch` tool.

### Step 3: Determine Fix

| Finding | Action |
|---------|--------|
| Found in walkthrough/web | Add the missing connection |
| Found as truly optional | Add `:: note` or mark as acceptable orphan |
| Not found anywhere | Investigate further or mark as ERROR |

### Example: Rare Book in KQVI

**Problem**: `O_RECEIVE_RARE_BOOK` is orphan. "What is the rare book for?"

**Walkthrough search**: "rare book" → Found reference: "trade rare book to Ali for spell book"

**Fix**: Add edge `O_RECEIVE_RARE_BOOK → A_TRADE_RARE_BOOK_FOR_SPELL`

## Common Errors and Fixes

### Error: Action Without Outcome

```mermaid
%% WRONG
A_PICK_UP_FLOWER

%% RIGHT
A_PICK_UP_FLOWER --> O_RECEIVE_FLOWER_OF_STENCH
```

**Fix**: Connect every action to its outcome.

### Error: Batched Transitive Dependency

```mermaid
%% WRONG - If C specifically requires A
A --> B --> C

%% RIGHT - A also connects directly to C
A --> B
A --> C
B --> C
```

**Fix**: If step N+1 specifically requires something from step N, add direct edge.

### Error: Sequential Order as Dependency

```mermaid
%% WRONG - "I went to beach first, then village" ≠ logical dependency
S1_BEACH --> S2_VILLAGE

%% RIGHT - Logical dependency: shell from beach is needed for gnome
O_RECEIVE_SHELL --> A_GIVE_SHELL_TO_GNOME
```

**Fix**: Track locks and keys, not player movement.

### Error: Locked Choice as Sequential Trades

```mermaid
%% WRONG - Don't model the choosing mechanic
A_TRADE_FOR_PAINTBRUSH --> A_TRADE_FOR_NIGHTINGALE --> ...

%% RIGHT - All items unlocked at once after paying price
A_PAY_PAWN_BROKER_COIN --> O_PAINTBRUSH_UNLOCKED
A_PAY_PAWN_BROKER_COIN --> O_NIGHTINGALE_UNLOCKED
A_PAY_PAWN_BROKER_COIN --> O_TINDERBOX_UNLOCKED
A_PAY_PAWN_BROKER_COIN --> O_FLUTE_UNLOCKED
```

**Fix**: Once price is paid, all locked-choice items show as UNLOCKED.

## Color Palette (Index-Based)

Use this fixed palette for area/subgraph coloring. Same area can appear multiple times at different logical points.

| Index | Hex | Sample |
|-------|-----|--------|
| 0 | `#FFFFFF` | Default/ungrouped |
| 1 | `#E3F2FD` | Light Blue |
| 2 | `#FFF3E0` | Light Orange |
| 3 | `#F3E5F5` | Light Purple |
| 4 | `#E8F5E9` | Light Green |
| 5 | `#FFF8E1` | Light Amber |
| 6 | `#FCE4EC` | Light Pink |
| 7 | `#E0F7FA` | Light Cyan |
| 8 | `#F5F5F5` | Light Grey |

### Applying Colors in Mermaid

```mermaid
subgraph "Isle of Wonder"["**Isle of Wonder**"]
    classDef area2 fill:#FFF3E0,stroke:#FF9800,stroke-width:2px
    class O_RECEIVE_NIGHTINGALE area2
    class O_RECEIVE_MINT area2
end
```

## Known Acceptable False Positives

The following are NOT errors:

1. **Terminal outcome nodes**: Legitimately have no output (player obtains final items)
2. **Optional side-quest items**: Player may never collect them
3. **Consequence nodes**: Some may have no input if they're self-evident state changes

Verify by checking if the item/action is ever referenced later in the graph.

## Output

After running QA:

1. **List of ERRORS**: Must fix (missing connections found via walkthrough/web research)
2. **List of WARNINGS**: Acceptable compromises or minor issues
3. **List of OPTIONAL**: Truly optional content that doesn't connect

## Usage

```bash
# Run QA on a chart
./.opencode/skills/qa-dependency-graph/scripts/check-dangling-nodes.sh src/inspiration/kings-quest-vi-chart.mmd

# After fixes, rebuild and verify
./build.sh
mdbook serve --open
```

## Integration

This skill is automatically invoked by the `create-dependency-graph` skill after initial graph creation. It can also be used standalone to audit existing graphs.