Agent Skills: Audit World

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