audit-world

This skill performs comprehensive audits on worldbuilding projects to ensure:

• Entity Linking: All [[wikilinks]] point to real entities
• Bidirectional Connections: If A links to B, B should link back to A
• D&D 5e 2024 Compliance: Stat blocks are mechanically correct
• Template Compliance: Entities use correct templates for their type
• Orphan Detection: No entities exist without incoming links
• Consistency: Cross-entity references make logical sense

Step 1: Parse Arguments

Extract from arguments:

1. World name - Required. Check Worlds/ for existing worlds.
2. --fix flag - Optional. If present, automatically fix issues where possible.
3. --category [type] - Optional. Only audit specific category (Characters, Settlements, etc.)
4. --check [type] - Optional. Run specific check only (links, stats, orphans, connections, templates, images, circular)

If world name not provided, list available worlds and ask which to audit.

Step 2: Scan World Structure

1. Verify directory structure:

```

Worlds/[World Name]/

├── World Overview.md

├── Characters/

├── Settlements/

├── Items/

├── Creatures/

├── Organizations/

├── Concepts/

├── History/

└── Geography/

```

1. Build entity index:

- Scan all .md files in the world

- Extract entity names from filenames

- Extract entity names from YAML name: field

- Build lookup table: {entity_name: file_path}

1. Count entities by category:

```

Category | Count

----------------|------

Characters | X

Settlements | X

Items | X

Creatures | X

Organizations | X

Concepts | X

History | X

Geography | X

----------------|------

TOTAL | X

```

---

Check 1: Wikilink Validation

Goal: Verify all [[Entity Name]] links point to real entities.

Process:

1. For each entity file:

- Extract all [[...]] patterns using regex: \[\[([^\]]+)\]\]

- For each link, check if target exists in entity index

- Track: {source_file, broken_link, line_number}

1. Ignore false positives:

- Links to D&D rules: [[D&D 5e...]], [[Stat Block...]]

- Links to images: [[...png]], [[...jpg]]

- Obsidian system links

1. Report:

```

## Broken Links Report

Found X broken links across Y entities.

### [Entity Name]

- Line XX: [[Missing Entity 1]]

- Line XX: [[Missing Entity 2]]

### [Entity Name 2]

...

```

1. Auto-fix options (if --fix):

- Offer to create stub entities for missing links

- Offer to remove broken links

- Offer fuzzy match suggestions for typos

---

Check 2: Bidirectional Connection Audit

Goal: Ensure connections are reciprocal.

Process:

1. For each entity, extract its ## Connections section
2. Parse all outgoing links
3. For each outgoing link, check if target links back
4. Track one-way connections

Reciprocal Relationship Matrix:

See [[Connection Matrix]] for complete bidirectional linking rules.

| Source Links To | Target Should Have |

|-----------------|-------------------|

| Settlement (as location) | Characters > Residents/Notable NPCs |

| Organization (as member) | Characters > Members |

| Region (as parent) | Settlements/Geography > Contains |

| Deity (as patron) | Characters > Worshippers |

| Character (as ally) | Characters > Allies |

| Character (as enemy) | Characters > Rivals/Enemies |

| Government (as ruler) | Characters > Leadership |

| Settlement (as HQ) | Organizations > Based Here |

| Parent Geography | Child Geography > Part Of |

| Historical Event | Locations > Site Of |

| Military (as army) | Government > Armed Forces |

| Criminal Organization (as operating) | Government > Criminal Elements |

| Creature (as habitat) | Geography > Native Wildlife/Monsters |

Report:

```

Found X connections missing reciprocal links.

[Entity A] → [Entity B]

• A links to B in: Connections > Organizations > Member
• B should link back in: Characters > Members
• Status: MISSING

[Entity C] → [Entity D]

...

```

Auto-fix (if --fix):

• Add reciprocal links to target entities
• Use appropriate section based on relationship type

---

Check 3: D&D 5e 2024 Stat Block Validation

Goal: Verify all stat blocks are mechanically correct.

Applies to: Characters (Protagonist, Antagonist, Support Character), Creatures (Monster, Animal, Insect)

#### 3-Pre: Stat Block Mode Detection (Characters Only)

Before validating characters, detect which stat block mode they use:

| Condition | Mode | Validation |

|-----------|------|------------|

| level: filled, challenge_rating: empty | PC-style | Use level-based proficiency, class features |

| challenge_rating: filled, level: empty | NPC-style | Use CR-based proficiency, monster rules |

| Both filled | WARNING | Ambiguous mode - flag for manual review |

| Neither filled | WARNING | Missing stat block info - flag for manual review |

PC-style validation applies:

• Proficiency from level (Check 3B)
• HP from class hit dice + CON (Check 3F)
• Spell slots from class progression
• Features match class/subclass

NPC-style validation applies:

• Proficiency from CR (Check 3A)
• HP from size hit dice + CON (Check 3F)
• CR/XP correlation (Check 3A)
• Legendary features for high CR (Check 3G)

Note: Creatures (Monster, Animal, Insect) always use NPC-style validation with challenge_rating:.

---

#### 3A: Challenge Rating & XP

Verify CR matches XP using official table:

| CR | XP | Proficiency |

|----|-----|-------------|

| 0 | 0 or 10 | +2 |

| 1/8 | 25 | +2 |

| 1/4 | 50 | +2 |

| 1/2 | 100 | +2 |

| 1 | 200 | +2 |

| 2 | 450 | +2 |

| 3 | 700 | +2 |

| 4 | 1,100 | +2 |

| 5 | 1,800 | +3 |

| 6 | 2,300 | +3 |

| 7 | 2,900 | +3 |

| 8 | 3,900 | +3 |

| 9 | 5,000 | +4 |

| 10 | 5,900 | +4 |

| 11 | 7,200 | +4 |

| 12 | 8,400 | +4 |

| 13 | 10,000 | +5 |

| 14 | 11,500 | +5 |

| 15 | 13,000 | +5 |

| 16 | 15,000 | +5 |

| 17 | 18,000 | +6 |

| 18 | 20,000 | +6 |

| 19 | 22,000 | +6 |

| 20 | 25,000 | +6 |

| 21 | 33,000 | +7 |

| 22 | 41,000 | +7 |

| 23 | 50,000 | +7 |

| 24 | 62,000 | +7 |

| 25 | 75,000 | +8 |

| 26 | 90,000 | +8 |

| 27 | 105,000 | +8 |

| 28 | 120,000 | +8 |

| 29 | 135,000 | +9 |

| 30 | 155,000 | +9 |

Check: experience_points in YAML matches CR from table.

#### 3B: Proficiency Bonus

By Level (Characters):

| Level | Proficiency |

|-------|-------------|

| 1-4 | +2 |

| 5-8 | +3 |

| 9-12 | +4 |

| 13-16 | +5 |

| 17-20 | +6 |

By CR (Monsters): Use CR table above.

Check: proficiency_bonus matches level/CR.

#### 3C: Ability Modifiers

Formula: modifier = floor((score - 10) / 2)

| Score | Modifier |

|-------|----------|

| 1 | -5 |

| 2-3 | -4 |

| 4-5 | -3 |

| 6-7 | -2 |

| 8-9 | -1 |

| 10-11 | +0 |

| 12-13 | +1 |

| 14-15 | +2 |

| 16-17 | +3 |

| 18-19 | +4 |

| 20-21 | +5 |

| 22-23 | +6 |

| 24-25 | +7 |

| 26-27 | +8 |

| 28-29 | +9 |

| 30 | +10 |

Check: Modifiers in ability score tables are calculated correctly.

#### 3D: Attack Bonuses

Formula: attack_bonus = proficiency_bonus + ability_modifier

• Melee: Usually STR (or DEX for finesse)
• Ranged: Usually DEX (or STR for thrown)

Check: Attack bonus in action descriptions matches formula.

#### 3E: Spell Save DC

Formula: spell_save_DC = 8 + proficiency_bonus + spellcasting_ability_modifier

| Class | Spellcasting Ability |

|-------|---------------------|

| Bard | Charisma |

| Cleric | Wisdom |

| Druid | Wisdom |

| Paladin | Charisma |

| Ranger | Wisdom |

| Sorcerer | Charisma |

| Warlock | Charisma |

| Wizard | Intelligence |

Check: Spell save DC in spellcasting section matches formula.

#### 3F: Hit Points

Formula for Characters:

```

HP = (hit_die_max + CON_mod) + ((level - 1) × (hit_die_avg + CON_mod))

```

Hit Die by Class:

| Class | Hit Die | Average |

|-------|---------|---------|

| Barbarian | d12 | 7 |

| Fighter, Paladin, Ranger | d10 | 6 |

| Bard, Cleric, Druid, Monk, Rogue, Warlock | d8 | 5 |

| Sorcerer, Wizard | d6 | 4 |

Formula for Monsters:

```

HP = hit_dice_count × hit_die_average + (hit_dice_count × CON_mod)

```

Hit Die by Size:

| Size | Hit Die | Average |

|------|---------|---------|

| Tiny | d4 | 2.5 |

| Small | d6 | 3.5 |

| Medium | d8 | 4.5 |

| Large | d10 | 5.5 |

| Huge | d12 | 6.5 |

| Gargantuan | d20 | 10.5 |

Check: HP matches hit dice formula with CON modifier.

#### 3G: Legendary Features (CR 5+)

For creatures CR 5 and above, check for:

• Legendary Resistance (3/Day) for CR 10+
• Legendary Actions for bosses
• Lair Actions if lair is defined

Report:

```

Found X errors across Y entities.

[Monster Name] (CR 5)

• ERROR: XP is 1500, should be 1800 for CR 5
• ERROR: Proficiency bonus is +2, should be +3 for CR 5
• WARNING: CR 5+ creature missing Legendary Actions (optional but recommended)

[Character Name] (Level 8)

• ERROR: Proficiency bonus is +2, should be +3 for level 8
• ERROR: Spell Save DC is 14, should be 15 (8 + 3 + 4)
• ERROR: Attack bonus is +5, should be +7 (proficiency 3 + STR 4)

```

Auto-fix (if --fix):

• Recalculate and update XP, proficiency, modifiers
• Update attack bonuses and spell save DCs
• Flag HP for manual review (hit dice formula)

---

Check 4: Orphan Entity Detection

Goal: Find entities with no incoming links.

Process:

1. Build incoming link count for each entity
2. Entities with 0 incoming links are orphans
3. Exception: World Overview.md (always root)

Report:

```

Found X entities with no incoming links.

Characters

• [[Forgotten NPC]] - 0 incoming links

Geography

• [[Unnamed Valley]] - 0 incoming links

```

Auto-fix (if --fix):

• Suggest parent entities to link from
• Offer to add to World Overview Quick Reference
• Offer to delete if truly orphaned

---

Check 5: Template Compliance

Goal: Verify entities match their templates.

Process:

1. Determine entity type from:

- File location (folder)

- YAML tags

- Content structure

1. Compare against expected template structure:

- Required YAML fields present

- Required sections present

- Section ordering correct

Template Requirements by Category:

Characters (All):

• YAML: name, status, tags containing character type
• Sections: Overview, Connections

Characters (Protagonist/Antagonist/Support Character):

• YAML: species, class, armor_class, hit_points
• YAML (Stat Block Mode): level OR challenge_rating (one required, not both)
• Sections: Stat Block, Ability Scores, Combat Statistics, Personality, Background

Creatures (Monster):

• YAML: size, creature_type, challenge_rating, experience_points
• Sections: Stat Block, Classification, Ability Scores, Traits, Actions

Settlements:

• YAML: settlement_type, population, government_type
• Sections: Overview, Districts/Areas, Notable Locations

Organizations:

• YAML: organization_type or appropriate tag
• Sections: Overview, Leadership, Goals, Resources

Geography:

• YAML: terrain_type or geographic tag
• Sections: Overview, Features, Inhabitants

Report:

```

Found X compliance issues across Y entities.

[Entity Name] (Characters/Protagonist.md)

• AMBIGUOUS YAML: Both level and challenge_rating are filled (use only one)
• MISSING SECTION: ## Ability Scores
• WRONG FOLDER: Located in Items/, should be Characters/

[Entity Name] (Characters/Antagonist.md)

• MISSING YAML: Neither level nor challenge_rating (one required for stat block)
• WARNING: Cannot validate proficiency bonus without level/CR

[Entity Name] (Settlements/City.md)

• MISSING YAML: population
• EMPTY SECTION: ## Districts

```

Auto-fix (if --fix):

• Add missing YAML fields with placeholder values
• Add missing section headers
• Suggest moving misplaced files

---

Check 6: Cross-Entity Consistency

Goal: Verify logical consistency across entities.

Checks:

1. Religious Consistency:

- Temples reference deities that exist

- Religious orders serve established deities

- Characters with deity patrons link to real deities

1. Political Consistency:

- Settlements reference governments that exist

- Military organizations belong to real governments

- Rulers are linked to their domains

1. Geographic Consistency:

- Settlements are in regions that exist

- Rivers flow from mountains to bodies of water

- Roads connect real settlements

- Terrain types match climate of parent region

1. Historical Consistency:

- Events reference locations that exist

- Battles are part of wars that exist

- Dynasties connect to governments

- Characters in historical events existed at that time

1. Economic Consistency:

- Currency matches issuing government

- Trade agreements connect trading partners

- Shops sell goods appropriate to region

Report:

```

Religious Inconsistencies

• Temple of [[Nonexistent God]] references deity not in pantheon
• Religious Order [[Knights of X]] serves [[Y]] but Y's domain doesn't match order purpose

Political Inconsistencies

• [[City A]] claims to be capital of [[Kingdom B]] but B lists different capital
• [[Military X]] serves [[Government Y]] but Y doesn't list X in armed forces

Geographic Inconsistencies

• [[River A]] claims to flow from [[Desert B]] (deserts don't have river sources)
• [[Settlement A]] is in [[Region B]] but B's climate is tundra, A's description is tropical

```

---

Check 7: Image Prompt Validation

Goal: Verify image prompt sections are properly filled for /generate-image readiness.

Process:

1. For each entity file, locate the Image Prompts section (usually near the end)
2. Find all Prompt: fields
3. Check if they contain actual content vs template placeholders

Template Placeholder Patterns to Detect:

• Empty field: Prompt: followed by nothing or whitespace
• Unfilled brackets: Prompt: [describe scene here]
• Generic text: Prompt: Describe the scene...
• Template instructions: Prompt: Write a detailed prompt for...

Valid Prompt Patterns:

• Specific descriptions: Prompt: A weathered dwarven blacksmith...
• Detailed scenes: Prompt: Interior of a dimly lit tavern...
• Minimum 20 characters of descriptive content

Report:

```

Ready for Image Generation

| Entity | Prompts Filled | Status |

|--------|----------------|--------|

| [[Lord Varic]] | 2/2 | ✓ Ready |

| [[Ironhold City]] | 2/2 | ✓ Ready |

Missing or Incomplete Prompts

| Entity | Issue | Line |

|--------|-------|------|

| [[The Sunken Palace]] | Empty prompt field | 245 |

| [[Captain Alonzo]] | Placeholder text only | 189 |

| [[Mountain Pass]] | Missing Image Prompts section | - |

Summary:

• Entities with complete prompts: X
• Entities with incomplete prompts: Y
• Entities missing Image Prompts section: Z

```

Auto-fix (if --fix):

• Cannot auto-fill image prompts (requires creative content)
• Flag entities needing attention
• Suggest running /create-entity to regenerate Image Prompts section

---

Check 8: Circular Reference Detection

Goal: Detect potentially problematic circular reference chains.

Process:

1. Build a directed graph of entity relationships
2. For each relationship type, check for cycles
3. Categorize cycles as valid (expected) or warning (potential error)

Valid Circular Patterns:

| Pattern | Example | Why Valid |

|---------|---------|-----------|

| Mutual relationship | A → B (ally), B → A (ally) | Symmetric relationship |

| Parent-child | Region → City (contains), City → Region (part of) | Bidirectional by design |

| Organization loop | Org → Member, Member → Org | Membership is bidirectional |

Warning Patterns:

| Pattern | Example | Why Problematic |

|---------|---------|-----------------|

| Geographic containment loop | A contains B contains C contains A | Impossible geography |

| Temporal causation loop | Event A caused B caused C caused A | Paradox |

| Hierarchical loop | God A serves B serves C serves A | Impossible hierarchy |

| "Part of" chain loop | Region A part of B part of C part of A | Invalid nesting |

Detection Algorithm:

```

1. Extract relationships by type:

- containment: "contains", "part of", "in"

- hierarchy: "serves", "reports to", "rules"

- causation: "caused", "led to", "resulted in"

- temporal: "before", "after", "during"

1. For each relationship type:

- Build directed graph

- Run cycle detection (DFS-based)

- Classify each cycle found

1. Report cycles by severity

```

Report:

```

Valid Bidirectional Links: X

(These are expected and correct)

Warning: Potential Problematic Cycles

#### Geographic Containment Loop

[[Region A]] → contains → [[Region B]] → contains → [[Region C]] → contains → [[Region A]]

Severity: HIGH - Geographic impossibility

Suggestion: Review containment relationships; one link is likely incorrect

#### Hierarchical Loop

[[Organization X]] → parent of → [[Organization Y]] → parent of → [[Organization X]]

Severity: MEDIUM - Circular hierarchy

Suggestion: Determine which org is truly the parent

No auto-fix available for circular references - requires manual review.

```

---

After all checks, provide comprehensive summary:

```

# World Audit Report: [World Name]

• Total Entities: X
• Audit Date: YYYY-MM-DD
• Issues Found: X (Y critical, Z warnings)

| Category | Count | Issues |

|----------|-------|--------|

| Characters | X | Y |

| Settlements | X | Y |

| Items | X | Y |

| Creatures | X | Y |

| Organizations | X | Y |

| Concepts | X | Y |

| History | X | Y |

| Geography | X | Y |

| TOTAL | X | Y |

Critical Issues (Must Fix)

| Issue Type | Count | Example |

|------------|-------|---------|

| Broken Links | X | [[Missing Entity]] in Entity.md |

| Stat Block Errors | X | Wrong XP for CR in Monster.md |

| Orphan Entities | X | Forgotten NPC.md |

Warnings (Should Review)

| Issue Type | Count | Example |

|------------|-------|---------|

| One-Way Links | X | A→B without B→A |

| Missing Sections | X | No Connections in Entity.md |

| Consistency Issues | X | Temple references wrong deity |

• Total Wikilinks: X
• Average Links Per Entity: X.X
• Most Connected Entity: [[Entity]] (X links)
• Least Connected Entity: [[Entity]] (X links)

High Priority

1. Fix X broken links in Y entities
2. Add reciprocal links for Z one-way connections
3. Correct stat block errors in W creatures

Medium Priority

1. Review X orphan entities for relevance
2. Fill missing sections in Y entities
3. Resolve Z consistency issues

Low Priority

1. Increase connections in sparse entities
2. Add missing optional YAML fields
3. Consider additional entities for coverage gaps

• Run /audit-world [world] --fix to auto-repair issues
• Use /create-entity to fill coverage gaps
• Review orphan entities for deletion or integration

```

---

When --fix is specified:

1. Ask before each fix category:

- "Found X broken links. Fix by creating stubs? (y/n)"

- "Found X one-way connections. Add reciprocal links? (y/n)"

- "Found X stat errors. Auto-correct calculations? (y/n)"

1. Create backup before modifying:

- Copy modified files to .audit-backup/ folder

- Log all changes made

1. Report changes:

```

## Auto-Fix Results

### Files Modified: X

- Entity1.md: Added 3 reciprocal links

- Entity2.md: Corrected XP (1500 → 1800)

- Entity3.md: Added missing YAML fields

### Files Created: X

- Missing Entity (stub).md: Created from broken link

### Backup Location: .audit-backup/[timestamp]/

```

---

If auto-fix made unwanted changes, you can restore from backup:

Backup Structure

```

Worlds/[World Name]/.audit-backup/

└── [YYYY-MM-DD_HH-MM-SS]/

├── manifest.json # List of all modified files

├── Characters/

│ └── [backed up files]

├── Settlements/

│ └── [backed up files]

└── ...

```

Manual Restore Steps

1. Find the backup timestamp:

```bash

ls Worlds/[World Name]/.audit-backup/

```

1. Review what was changed:

Read the manifest file to see what was modified:

```bash

cat Worlds/[World Name]/.audit-backup/[timestamp]/manifest.json

```

1. Restore specific files:

```bash

# Copy backed up file over current version

cp "Worlds/[World Name]/.audit-backup/[timestamp]/Characters/Lord Varic.md" \

"Worlds/[World Name]/Characters/Lord Varic.md"

```

1. Restore all files from a backup:

```bash

# Restore entire backup (overwrite current files)

cp -r "Worlds/[World Name]/.audit-backup/[timestamp]/"* "Worlds/[World Name]/"

```

Backup Retention

• Backups are kept for 7 days by default
• Each --fix run creates a new timestamped backup
• Old backups can be manually deleted from .audit-backup/

Partial Restore

To restore only certain changes:

1. Open the backed-up file
2. Compare with current file (use diff tool or Obsidian)
3. Manually copy specific sections you want to restore

---

After `/generate-world`

Run /audit-world [world] to:

• Verify all generated entities are linked
• Check stat blocks on generated monsters
• Ensure no orphans from generation

After `/create-entity`

Reciprocal link logic in create-entity should prevent most issues, but audit can catch edge cases.

Before `/generate-image`

Audit can verify image prompt sections are filled before batch image generation.

---

```

# Full audit

/audit-world Eldoria

# Audit with auto-fix

/audit-world Eldoria --fix

# Only check links

/audit-world Eldoria --check links

# Only check D&D stats

/audit-world Eldoria --check stats

# Only audit Characters

/audit-world Eldoria --category Characters

# Combination

/audit-world Eldoria --category Creatures --check stats --fix

```