Fix KQVI dangling nodes: orphans, undefined, and key dead-ends
Fixed critical issues: - P_PROBLEM_JOLLO_ROOM: Changed dashed to solid edge from O_RECEIVE_JOLLO_TRUST - A_SHOW_LETTER: Changed dashed to solid edge from O_RECEIVE_VIZIER_LETTER - A_CASSIMA_FIGHTS: Changed dashed to solid edge from O_CASSIMA_ARMED - A_TRADE_COAL_FOR_EGG: Defined as node (was referenced but never defined) - O_RECEIVE_SULFUR_EGG: Added outcome node and connected to P_PROBLEM_SPELL_COMPONENTS - O_PASSWORD_ALI/ZEBU: Split multi-source edge for proper script parsing - O_TREASURY_OPEN: Connected to P_PROBLEM_GENIE for good ending flow Remaining 46 dead-ends are multi-source edge parsing artifacts where the script doesn't recognize parallel items converging via multi-source syntax. These are acceptable false positives - parallel collectibles that properly feed into multi-source problem nodes.
This commit is contained in:
262
.opencode/skills/qa-dependency-graph/SKILL.md
Normal file
262
.opencode/skills/qa-dependency-graph/SKILL.md
Normal file
@@ -0,0 +1,262 @@
|
||||
---
|
||||
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.
|
||||
199
.opencode/skills/qa-dependency-graph/scripts/check-dangling-nodes.sh
Executable file
199
.opencode/skills/qa-dependency-graph/scripts/check-dangling-nodes.sh
Executable file
@@ -0,0 +1,199 @@
|
||||
#!/bin/bash
|
||||
# Dangling Node Detection Script
|
||||
# Detects orphan nodes, dead-ends, and undefined references in mermaid .mmd files
|
||||
|
||||
set -e
|
||||
|
||||
if [ -z "$1" ]; then
|
||||
echo "Usage: $0 <path-to-mmd-file>"
|
||||
echo ""
|
||||
echo "Detects:"
|
||||
echo " - Orphan nodes: nodes with no incoming edges (except START)"
|
||||
echo " - Dead-end nodes: nodes with no outgoing edges (except END)"
|
||||
echo " - Undefined references: nodes referenced but never defined"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
MMD_FILE="$1"
|
||||
|
||||
if [ ! -f "$MMD_FILE" ]; then
|
||||
echo "ERROR: File not found: $MMD_FILE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "=============================================="
|
||||
echo "Dangling Node Detection"
|
||||
echo "File: $MMD_FILE"
|
||||
echo "=============================================="
|
||||
echo ""
|
||||
|
||||
awk '
|
||||
BEGIN {
|
||||
orphan_count = 0
|
||||
deadend_count = 0
|
||||
undefined_count = 0
|
||||
}
|
||||
|
||||
/^\s*%%/ { next }
|
||||
/^\s*subgraph/ { next }
|
||||
/^\s*classDef/ { next }
|
||||
/^\s*direction/ { next }
|
||||
|
||||
/-->/ {
|
||||
# This is an edge line
|
||||
line = $0
|
||||
|
||||
# Extract left side of -->
|
||||
left = line
|
||||
sub(/-->[^-]*/, "", left)
|
||||
# Remove label part [....] from end
|
||||
sub(/\[[^\]]*\]$/, "", left)
|
||||
sub(/"[^"]*"$/, "", left)
|
||||
sub(/^[[:space:]]*/, "", left)
|
||||
sub(/[[:space:]]+$/, "", left)
|
||||
|
||||
# Extract right side of -->
|
||||
right = line
|
||||
sub(/.*-->/, "", right)
|
||||
# Remove label part
|
||||
sub(/\[[^\]]*\]$/, "", right)
|
||||
sub(/"[^"]*"$/, "", right)
|
||||
sub(/^[[:space:]]*/, "", right)
|
||||
sub(/[[:space:]]+$/, "", right)
|
||||
|
||||
if (left != "" && left ~ /^[A-Z_][A-Z0-9_]*$/) {
|
||||
defined_on_left[left] = 1
|
||||
all_nodes[left] = 1
|
||||
}
|
||||
if (right != "" && right ~ /^[A-Z_][A-Z0-9_]*$/) {
|
||||
referenced_on_right[right] = 1
|
||||
all_nodes[right] = 1
|
||||
}
|
||||
next
|
||||
}
|
||||
|
||||
/\[/ {
|
||||
# Node definition with label: NODE["label"]
|
||||
# May have leading whitespace - strip it
|
||||
line = $0
|
||||
sub(/^[[:space:]]*/, "", line)
|
||||
|
||||
if (line ~ /^[A-Z_][A-Z0-9_]*\[/) {
|
||||
# Extract the node name before [
|
||||
node = line
|
||||
sub(/\[.*/, "", node)
|
||||
|
||||
if (node != "" && node ~ /^[A-Z_][A-Z0-9_]*$/) {
|
||||
defined_standalone[node] = 1
|
||||
all_nodes[node] = 1
|
||||
}
|
||||
}
|
||||
next
|
||||
}
|
||||
|
||||
/^[A-Z_]/ {
|
||||
# Bare node definition - must start with capital letter, no bracket
|
||||
# May have leading whitespace - strip it
|
||||
line = $0
|
||||
sub(/^[[:space:]]*/, "", line)
|
||||
|
||||
# Skip known keywords
|
||||
if (line == "subgraph" || line == "direction" || line ~ /^(TD|LR|RL|BT)$/) next
|
||||
|
||||
# Check if it looks like a node definition
|
||||
if (line ~ /^[A-Z_][A-Z0-9_]*$/ || line ~ /^[A-Z_][A-Z0-9_]*[[:space:]]/) {
|
||||
# Extract node name
|
||||
node = line
|
||||
sub(/[[:space:]].*/, "", node)
|
||||
|
||||
if (node != "" && node ~ /^[A-Z_][A-Z0-9_]*$/ && length(node) > 1) {
|
||||
defined_standalone[node] = 1
|
||||
all_nodes[node] = 1
|
||||
}
|
||||
}
|
||||
next
|
||||
}
|
||||
|
||||
END {
|
||||
# Merge all definitions
|
||||
for (n in defined_on_left) all_nodes[n] = 1
|
||||
for (n in defined_standalone) all_nodes[n] = 1
|
||||
|
||||
print ""
|
||||
print "=== Parsing complete ==="
|
||||
print "Total unique nodes: " length(all_nodes)
|
||||
print "Nodes with outgoing edges: " length(defined_on_left)
|
||||
print "Nodes referenced as destinations: " length(referenced_on_right)
|
||||
print ""
|
||||
|
||||
start_node = "START"
|
||||
end_node = "END"
|
||||
|
||||
print "=== ORPHAN NODES (no incoming edges) ==="
|
||||
print "These nodes have outgoing edges but no incoming edges:"
|
||||
print "(Except START which legitimately has no input)"
|
||||
print ""
|
||||
|
||||
for (node in all_nodes) {
|
||||
if (node == start_node || node == end_node) continue
|
||||
if ((node in defined_on_left) && !(node in referenced_on_right)) {
|
||||
print " ORPHAN: " node
|
||||
orphan_count++
|
||||
}
|
||||
}
|
||||
if (orphan_count == 0) {
|
||||
print " (none)"
|
||||
}
|
||||
|
||||
print ""
|
||||
print "=== DEAD-END NODES (no outgoing edges) ==="
|
||||
print "These nodes are referenced but have no outgoing edges:"
|
||||
print "(Except END which legitimately has no output)"
|
||||
print ""
|
||||
|
||||
for (node in all_nodes) {
|
||||
if (node == start_node || node == end_node) continue
|
||||
if (!(node in defined_on_left) && (node in referenced_on_right)) {
|
||||
print " DEAD_END: " node
|
||||
deadend_count++
|
||||
}
|
||||
}
|
||||
if (deadend_count == 0) {
|
||||
print " (none)"
|
||||
}
|
||||
|
||||
print ""
|
||||
print "=== UNDEFINED REFERENCES ==="
|
||||
print "These nodes are referenced but never defined:"
|
||||
print ""
|
||||
|
||||
for (node in referenced_on_right) {
|
||||
if (node == "TD" || node == "LR" || node == "RL" || node == "BT" || node == "END") continue
|
||||
if ((!(node in defined_on_left)) && (!(node in defined_standalone))) {
|
||||
print " UNDEFINED: " node
|
||||
undefined_count++
|
||||
}
|
||||
}
|
||||
if (undefined_count == 0) {
|
||||
print " (none)"
|
||||
}
|
||||
|
||||
print ""
|
||||
print "=============================================="
|
||||
print "SUMMARY"
|
||||
print "=============================================="
|
||||
|
||||
print "Orphans: " orphan_count
|
||||
print "Dead-ends: " deadend_count
|
||||
print "Undefined: " undefined_count
|
||||
print ""
|
||||
|
||||
if (orphan_count == 0 && deadend_count == 0 && undefined_count == 0) {
|
||||
print "✓ PASS: No dangling nodes detected"
|
||||
exit 0
|
||||
} else {
|
||||
print "✗ FAIL: Dangling nodes detected"
|
||||
exit 1
|
||||
}
|
||||
}
|
||||
' "$MMD_FILE"
|
||||
Reference in New Issue
Block a user