audit-world

name	audit-world
description	Audit a world for consistency, D&D 5e 2024 rule compliance, broken links, orphaned entities, and connection gaps. Provides detailed reports and can auto-fix issues.
argument-hint	[world] [--fix] [--check links|stats|orphans|images|circular] [--category Type]

Audit World

Audit world: $ARGUMENTS

Overview

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

Instructions

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/
   

2. 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}

3. Count entities by category:

   Category        | Count
   ----------------|------
   Characters      | X
   Settlements     | X
   Items           | X
   Creatures       | X
   Organizations   | X
   Concepts        | X
   History         | X
   Geography       | X
   ----------------|------
   TOTAL           | X
   

---

Audit Checks

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}

2. Ignore false positives:

   • Links to D&D rules: [[D&D 5e...]], [[Stat Block...]]
   • Links to images: [[...png]], [[...jpg]]
   • Obsidian system links

3. 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]
   ...
   

4. 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:

## One-Way Connection 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:

## D&D 5e Stat Block Errors

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:

## Orphan Entities

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

2. 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:

## Template Compliance Issues

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

2. Political Consistency:

   • Settlements reference governments that exist
   • Military organizations belong to real governments
   • Rulers are linked to their domains

3. 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

4. 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

5. Economic Consistency:

   • Currency matches issuing government
   • Trade agreements connect trading partners
   • Shops sell goods appropriate to region

Report:

## Cross-Entity Consistency Issues

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

## Image Prompt Status

### 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"

2. For each relationship type:
   - Build directed graph
   - Run cycle detection (DFS-based)
   - Classify each cycle found

3. Report cycles by severity

Report:

## Circular Reference Analysis

### 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.

---

Summary Report

After all checks, provide comprehensive summary:

# World Audit Report: [World Name]

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

## Entity Count
| 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** |

## Issue Summary

### 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 |

## Connection Statistics
- **Total Wikilinks:** X
- **Average Links Per Entity:** X.X
- **Most Connected Entity:** [[Entity]] (X links)
- **Least Connected Entity:** [[Entity]] (X links)

## Recommendations

### 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

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

---

Auto-Fix Mode (--fix)

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)"

2. Create backup before modifying:

   • Copy modified files to .audit-backup/ folder
   • Log all changes made

3. 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]/
   

---

Rollback & Restore Procedure

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:

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

2. Review what was changed: Read the manifest file to see what was modified:

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

3. Restore specific files:

   # 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"
   

4. Restore all files from a backup:

   # 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

---

Integration with Other Skills

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.

---

Usage Examples

# 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