Populate Entity

Populate this entity: $ARGUMENTS

Overview

This skill analyzes an existing entity file to:

1. Identify plain text that should become wikilinks (names of people, places, organizations)
2. Find existing wikilinks that point to non-existent entities
3. Create all missing entities using appropriate templates
4. Update the source entity with proper wikilinks
5. Ensure bidirectional connections

Instructions

Step 1: Parse Arguments

Required:

• Entity path or name

Optional Flags:

Step 2: Locate Entity & Determine World

1. If path provided (contains / or .md):

   • Read the file directly
   • Extract world name from path: Worlds/[World Name]/...

2. If name provided:

   • Search Worlds/ directories for matching entity
   • Try exact filename match first
   • Then fuzzy match on filename and YAML name: field
   • If multiple matches, list them and ask user to clarify

3. If not found:

   • List similar entities and ask for clarification

The world name is required for knowing where to save new entities.

Step 3: Build Entity Index

Before analysis, create a complete index of existing entities in the world:

1. Scan all files in Worlds/[World Name]/ recursively
2. For each entity file, extract:
   • Filename (without .md extension)
   • YAML name: field
   • YAML aliases: array
   • File path
3. Build lookup dictionary (case-insensitive):

   {
     "entity name": "path/to/entity.md",
     "alias1": "path/to/entity.md",
     ...
   }
   

This index is used to:

• Avoid creating duplicate entities
• Detect existing entities mentioned as plain text
• Verify wikilinks point to real files

Step 4: Analyze Source Entity

Read the source entity file and perform three analyses:

4A: Extract Existing Wikilinks

Use regex pattern: \[\[([^\]|]+)(?:\|[^\]]+)?\]\]

For each wikilink found:

1. Extract the entity name (handling [[Name|Display]] format)
2. Check if it exists in the entity index
3. If not found, mark as broken link
4. Track line numbers for reporting

4B: Identify Potential Entity References

Scan the entity content (excluding YAML frontmatter, code blocks, and Image Prompts section) for proper noun patterns:

High-Confidence Patterns:

Medium-Confidence Patterns:

Detection Algorithm:

1. Split content into lines
2. Skip YAML frontmatter (between --- markers)
3. Skip Image Prompts section and below
4. Skip content inside code blocks (``` markers)
5. Skip existing wikilinks

6. For each line:
   a. Find capitalized multi-word phrases (2-4 words)
   b. Check against high-confidence patterns first
   c. If no pattern match, check context clues
   d. Skip common phrases that aren't entities:
      - "The [Direction]" (The North, The East)
      - Generic descriptors (The Great, The Ancient)
      - Section headers

7. For each detected phrase:
   a. Check if already in entity index -> mark as "needs wikilink"
   b. Check if not in index -> mark as "potential new entity"
   c. Record line numbers for all occurrences
   d. Extract surrounding context (10 words before/after)

4C: Classify Detected References

Sort all detected references into categories:

Step 5: Present Analysis Report

Display findings before taking action:

=== ENTITY ANALYSIS: [Source Entity Name] ===

World: [World Name]
Source Path: [path/to/source.md]

---

## EXISTING ENTITIES (Should Become Links)

Found X names matching existing entities but not wikilinked:

| # | Name | Line(s) | Matches Entity |
|---|------|---------|----------------|
| 1 | "Lady Serana Valdren" | 150 | [[Lady Serana Valdren]] |
| 2 | "Captain Alonzo" | 178, 192 | [[Captain Alonzo the Bold]] |

---

## BROKEN WIKILINKS (Need New Entities)

Found X wikilinks pointing to non-existent entities:

| # | Wikilink | Line(s) | Suggested Type | Template |
|---|----------|---------|----------------|----------|
| 1 | [[The Merchant Guilds]] | 286 | Organization | Guild.md |
| 2 | [[Marevento]] | 69, 278 | Settlement | Town.md |
| 3 | [[Serenzia]] | 72, 278 | Settlement | Town.md |

---

## DETECTED REFERENCES (Potential New Entities)

Found X capitalized names that may be entities:

| # | Name | Line(s) | Suggested Type | Context |
|---|------|---------|----------------|---------|
| 1 | "Marco Fortunato" | 171, 283 | Character | "wealthiest merchant", "key retainer" |
| 2 | "Adriano Valdren" | 165 | Character | "Varic's brother", "overseas trade" |
| 3 | "The Sunken Palace" | 166, 252 | Geography (Dungeon) | "underwater ruins", "pre-Faith secrets" |

---

## AMBIGUOUS REFERENCES (Need Confirmation)

| # | Name | Line(s) | Could Be | Please Specify |
|---|------|---------|----------|----------------|
| 1 | "The Reckoning" | 184, 253 | Event OR Tradition | history/concept? |

---

## SUMMARY

| Category | Count |
|----------|-------|
| Existing to link | X |
| Broken links to create | X |
| New entities detected | X |
| Ambiguous (need input) | X |
| **Total potential creations** | **X** |

---

**Options:**
1. Create all suggested entities (uses best-guess types)
2. Review each entity individually
3. Only fix broken wikilinks
4. Only add links to existing entities
5. Show dry-run (no changes)

If --auto flag is set, skip this step and proceed with best-guess types. If --dry-run flag is set, show report and stop.

Step 6: Determine Entity Types

For each entity to create, use pattern matching to determine the template:

Template Mapping (from create-entity):

Characters:

Settlements:

Organizations:

Geography:

History:

Category Folder Mappings:

Step 7: Confirm Creation Plan

Before creating entities, present the plan:

=== CREATION PLAN ===

Will create X new entities:

CHARACTERS (X):
| Entity | Template | Context from Source |
|--------|----------|---------------------|
| Marco Fortunato | Support Character.md | "wealthiest merchant" |
| Adriano Valdren | Support Character.md | "Varic's brother" |

SETTLEMENTS (X):
| Entity | Template | Context from Source |
|--------|----------|---------------------|
| Marevento | Town.md | "secondary port", "shipbuilding" |
| Serenzia | Town.md | "agricultural center" |

ORGANIZATIONS (X):
| Entity | Template | Context from Source |
|--------|----------|---------------------|
| The Merchant Guilds | Guild.md | "allied with House Valdren" |

GEOGRAPHY (X):
| Entity | Template | Context from Source |
|--------|----------|---------------------|
| The Sunken Palace | Dungeon.md | "underwater ruins", "pre-Faith" |

---

Proceed with creation? (yes/no/modify)

If --auto flag is set, skip confirmation and proceed.

Step 8: Create Entities

For each confirmed entity:

8A: Read Template

Read the appropriate template from Templates/[Category]/[Template].md

8B: Generate Content

Generate content based on:

1. Context from source entity – What does the source say about this entity?
2. World Overview – Read for tone, themes, naming conventions
3. Template requirements – Fill required sections

Content Generation Guidelines:

Since these are auto-generated entities, create minimal but coherent content:

1. YAML Frontmatter:

   • Set name: to the entity name
   • Set status: draft (marked for user review)
   • Fill category-specific fields with reasonable defaults
   • Leave image: empty

2. Overview Section:

   • 2-3 sentences based on context from source entity
   • Reference the source entity using [[wikilink]]

3. Core Identity Sections:

   • Fill minimally based on available context
   • Mark sections needing expansion with <!-- TODO: Expand -->

4. Connections Section:

   • Add [[Source Entity]] as primary connection
   • Use appropriate relationship category based on entity types

5. Image Prompts:

   • Leave as template placeholders or fill with basic descriptions

Naming Conventions:

Consult naming reference files when generating names:

• Templates/Reference/D&D Species Naming Conventions.md
• Templates/Reference/Tolkien Naming Conventions.md

Match naming style to the world’s established conventions.

8C: Save Entity

Save to: Worlds/[World Name]/[Category]/[Entity Name].md

Use Title Case with spaces for filenames.

8D: Add Reciprocal Link

After saving the new entity, add a connection back to the source entity:

Reciprocal Link Patterns:

Step 9: Update Source Entity

After creating all new entities:

9A: Convert Plain Text to Wikilinks

For each detected reference that now has an entity:

1. Find occurrences in source entity
2. Replace Entity Name with [[Entity Name]]
3. Handle partial name matches (e.g., “Lady Serana” → [[Lady Serana Valdren|Lady Serana]])

Use Edit tool for precise replacements.

9B: Ensure Connections Section is Updated

For each new entity created:

1. Determine appropriate connection category based on entity type
2. Check if source entity’s Connections section has this category
3. Add wikilink to appropriate subsection

Connection Section Formats:

## Connections

### People
- **Family:** [[Family Member]]
- **Allies:** [[Ally 1]], [[Ally 2]]
- **Associates:** [[Associate 1]]

### Organizations
- **Member Of:** [[Organization]]
- **Allied With:** [[Allied Org]]

### Locations
- **Headquarters:** [[Settlement]]
- **Territory:** [[Region]]

### Geography
- **Contains:** [[Location 1]], [[Location 2]]
- **Borders:** [[Neighboring Region]]

9C: Validate All Links

After updates, verify:

1. All new wikilinks resolve to existing entity files
2. No duplicate links in Connections section
3. Source entity frontmatter is intact

Step 10: Summary Report

=== POPULATE COMPLETE: [Source Entity Name] ===

Created X new entities:

CHARACTERS:
- [[Marco Fortunato]] - Wealthy merchant, Valdren ally (draft)
- [[Adriano Valdren]] - Varic's brother, trade manager (draft)

SETTLEMENTS:
- [[Marevento]] - Secondary port, shipbuilding center (draft)
- [[Serenzia]] - Agricultural town (draft)

ORGANIZATIONS:
- [[The Merchant Guilds]] - Allied trading organizations (draft)

GEOGRAPHY:
- [[The Sunken Palace]] - Underwater ruins with ancient secrets (draft)

---

Source Entity Updated:
- Added X wikilinks (previously plain text)
- Added X items to Connections section

Reciprocal Links Added:
- Marco Fortunato → [[Source Entity]] (employer)
- Marevento → [[The Western Shore]] (region)
- etc.

---

All new entities marked as 'draft' for review.

Suggested Next Steps:
1. Review and expand created entities with /expand-entity
2. Run /audit-world [World Name] to verify all connections
3. Generate images with /generate-image [Entity]

Bulk Processing Mode

When --world flag is provided, the skill processes multiple entities:

Bulk Mode Workflow

1. Scan world directory:

   • List all .md files in Worlds/[World Name]/
   • If --category specified, only scan that folder
   • Build a master entity index for the entire world

2. Analyze all entities:

   • Run detection on each entity file
   • Compile a master list of potential new entities
   • De-duplicate across files (same reference in multiple files = one entity)

3. Present consolidated plan:

   === BULK POPULATE: [World Name] ===
   
   Files Analyzed: X
   Files with Detections: Y
   
   ENTITIES TO CREATE (de-duplicated):
   
   | Entity | Type | Referenced In | Times |
   |--------|------|---------------|-------|
   | Marco Fortunato | Character | 3 files | 7 mentions |
   | The Iron Guild | Organization | 2 files | 4 mentions |
   ...
   
   Total: N new entities across M source files
   
   Options:
   1. Create all (uses best-guess types)
   2. Review by category
   3. Review each individually
   4. Dry run complete
   

4. Process with de-duplication:

   • Create each entity once
   • Update ALL source files that reference it
   • Add reciprocal links from new entity to all referencing entities

5. Bulk summary report:

   === BULK POPULATE COMPLETE ===
   
   Entities Created: N
   Source Files Updated: M
   Total Wikilinks Added: X
   Reciprocal Links Created: Y
   
   By Category:
   - Characters: N created
   - Settlements: N created
   ...
   

Bulk Mode Options

# Process entire world (with confirmations)
/populate-entity --world Eldermyr

# Fully automated (no confirmations)
/populate-entity --world Eldermyr --auto

# Only fix broken links across world
/populate-entity --world Eldermyr --broken-only

# Limit total entities created in bulk
/populate-entity --world Eldermyr --limit 50

# Preview bulk changes
/populate-entity --world Eldermyr --dry-run

Performance Notes

• Bulk mode builds entity index once (more efficient)
• De-duplication prevents creating duplicate entities
• For very large operations, use --limit to process in batches
• Consider running /audit-world --check links afterward to verify

Examples

# Populate a specific entity by name
/populate-entity "House Valdren"

# Populate by file path
/populate-entity Worlds/Eldermyr/Organizations/House Valdren.md

# Preview what would be created (no changes)
/populate-entity "Porto Valdris" --dry-run

# Auto-populate without prompts (for batch processing)
/populate-entity "Lord Varic Valdren" --auto

# Only fix broken wikilinks, skip text detection
/populate-entity "World Overview" --broken-only

# Only add wikilinks to existing entities, don't create new
/populate-entity "The Great War" --links-only

# Limit number of entities to create
/populate-entity "The Great War" --limit 5

# Combine flags
/populate-entity "House Valdren" --auto --limit 10

Integration with Other Skills

After /create-entity

Run /populate-entity on newly created entities to automatically flesh out referenced names.

Before /audit-world

Run /populate-entity on key entities to reduce broken link count before audit.

With /expand-entity

• /expand-entity adds depth to a single entity
• /populate-entity creates the network of related entities
• Use together: populate first, then expand key entities

With /link-entities

• /populate-entity creates entities from detected references
• /link-entities can refine the relationships afterward

Quality Guidelines

1. Conservative Creation: Only create entities with high-confidence type detection
2. Minimal Content: New entities get basic content marked as draft
3. Preserve Context: Use context from source to inform new entity content
4. Bidirectional: Always add reciprocal links
5. No Duplicates: Check entity index before creating
6. User Control: Confirmation prompts unless --auto flag