Document Templates

Master templates for all poe-aio document types. Every content file in this project must derive from one of these templates.

---

Template Philosophy

Centralized Templates + Folder READMEs

• Templates stored here - Single source of truth, easy maintenance
• READMEs in content folders - Discoverability, context, naming conventions
• Clean queries - No template pollution in content searches
• Simple commands - Predictable template paths

Key Principle: No content file exists without a template. Templates enforce structure, required fields, and validation rules.

---

Template Inventory

Build Documentation

build-template.md - Character Build Guides

• Purpose: Complete build guides from leveling to endgame
• Used in: builds/[class]/
• Naming: [build-name].md (e.g., rf-juggernaut.md)
• Key Sections: Overview, gem setup, passive tree, gearing, leveling, atlas strategy
• Required Fields: build_name, class, ascendancy, league, budget_tier, ratings

Game Mechanics

skill-template.md - Skill & Gem Documentation

• Purpose: Detailed skill gem documentation and mechanics
• Used in: mechanics/skills/
• Naming: [skill-name].md (e.g., righteous-fire.md)
• Key Sections: Gem stats, mechanics, scaling, support gems, builds using it
• Required Fields: skill_name, skill_type, gem_color, damage_type, level_requirement

item-template.md - Unique Item Documentation

• Purpose: Unique item stats, acquisition, usage, and market analysis
• Used in: mechanics/items/
• Naming: [item-name].md (e.g., the-brass-dome.md)
• Key Sections: Item stats, acquisition, use cases, synergies, market analysis
• Required Fields: item_name, item_type, base_type, rarity, slot

mechanic-template.md - Game Mechanic Explanations

• Purpose: Core systems, crafting, atlas mechanics
• Used in: mechanics/[category]/
• Naming: [mechanic-name].md (e.g., essence-crafting.md)
• Key Sections: How it works, rewards, strategies, build requirements, atlas passives
• Required Fields: mechanic_name, mechanic_type, complexity, accessibility

league-template.md - League Mechanic Documentation

• Purpose: League-specific mechanics, past league content that went core
• Used in: mechanics/leagues/
• Naming: [league-name]-mechanic.md or [mechanic-name].md (e.g., heist.md, delve.md)
• Key Sections: Overview, mechanic details, rewards, atlas integration, strategy
• Required Fields: league_name, introduced_in, core_mechanic

Strategy & Research

guide-template.md - Strategy & How-To Guides

• Purpose: Step-by-step guides for farming, progression, and strategies
• Used in: research/strategy/
• Naming: [topic].md (e.g., atlas-completion-guide.md)
• Key Sections: Step-by-step instructions, resources needed, expected results, tips
• Required Fields: guide_title, guide_type, target_audience, difficulty

research-template.md - Meta Analysis & Research

• Purpose: Data-driven analysis of builds, economy, meta trends
• Used in: research/[category]/
• Naming: [league]-[topic].md or [date]-[topic].md
• Key Sections: Methodology, data, analysis, insights, implications
• Required Fields: research_title, research_type, confidence_level, data_sources

---

Usage Guide

For AI Assistants (Claude Code)

Creating Documents - The 3-Step Process

Step 1: Read folder README for requirements

Read("builds/marauder/README.md")
// Check: template_path, naming_pattern, required_fields

Step 2: Get the template

Read("templates/build-template.md")
// Review frontmatter requirements and structure

Step 3: Create document in appropriate folder

Write("builds/marauder/rf-juggernaut.md", content)
// Follow naming pattern, include all required fields

Template Path Pattern

const templatePath = `templates/${documentType}-template.md`

// Examples:
// "build" → "templates/build-template.md"
// "skill" → "templates/skill-template.md"
// "item" → "templates/item-template.md"
// "mechanic" → "templates/mechanic-template.md"
// "league" → "templates/league-template.md"
// "guide" → "templates/guide-template.md"
// "research" → "templates/research-template.md"

---

Template Structure

Every Template Contains

1. Metadata Block (YAML frontmatter at top)

   • Template version and ID
   • Validation rules
   • Required/optional fields
   • Field validation patterns

2. Document Fields (To be filled out)

   • Document type
   • Template reference (REQUIRED)
   • Type-specific fields
   • Status, author, dates
   • Tags and relationships

3. Content Structure (Markdown body)

   • Standardized sections
   • Tables and formatting
   • Placeholder guidance
   • Examples and instructions

---

Required Frontmatter Fields

Universal Fields (All Templates)

---
template: "templates/[template-name].md"  # REQUIRED - DO NOT CHANGE
document_type: "[type]"                   # build|skill|item|mechanic|guide|research
status: "draft"                           # draft|review|published|outdated|archived
author: "Author Name"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
league: "3.25"                            # Current league version
patch: "3.25.1"                           # Optional: specific patch
tags: ["tag1", "tag2"]                    # Searchable tags
---

Type-Specific Required Fields

Build:

• build_name, class, ascendancy, budget_tier, ratings

Skill:

• skill_name, skill_type, gem_color, damage_type, level_requirement

Item:

• item_name, item_type, base_type, rarity, slot

Mechanic:

• mechanic_name, mechanic_type, complexity, accessibility

League:

• league_name, introduced_in, core_mechanic

Guide:

• guide_title, guide_type, target_audience, difficulty

Research:

• research_title, research_type, confidence_level, data_sources

---

Relationship System

Bidirectional Linking

All templates support relationship metadata for cross-referencing:

relationships:
  requires:
    - path: "mechanics/items/unique-item.md"
      title: "Required Item Name"
      reason: "Why this relationship exists"

  synergizes_with:
    - path: "mechanics/skills/skill-name.md"
      title: "Skill Name"
      reason: "How they work together"

  used_by:
    - path: "builds/class/build-name.md"
      title: "Build Name"

  alternatives:
    - path: "mechanics/items/alternative.md"
      title: "Alternative Item"

Relationship Types

Type	Inverse	Usage
requires	required_by	Hard dependencies
synergizes_with	synergizes_with	Complementary content
used_by	uses	Builds using items/skills
alternatives	alternative_to	Similar/competing options
derived_from	informs	Based on other content

Always use absolute paths from project root, never relative paths!

---

Template Validation

Built-in Validation Rules

Each template includes validation_rules in its frontmatter metadata:

validation_rules:
  required_fields:
    - template
    - document_type
    - [type-specific fields]

  field_rules:
    - field: "template"
      rule: "Must equal 'templates/[name].md'"
      regex: "^templates/[name]\\.md$"
    - field: "status"
      rule: "Must be valid status"
      values: ["draft", "review", "published", "outdated", "archived"]

Validation Checklist

Before publishing any document:

• [ ] template field points to correct template
• [ ] All required fields are present
• [ ] Field values match validation rules
• [ ] Status is appropriate
• [ ] Absolute paths used for all relationships
• [ ] Tags are relevant and searchable
• [ ] Content follows template structure

---

Template Maintenance

Version Control

• Templates are versioned (template_version: "1.0.0")
• Breaking changes increment major version
• New sections increment minor version
• Small fixes increment patch version

Updating Templates

When updating a template:

1. Increment template_version
2. Document changes in template's changelog
3. No need to update existing documents unless required fields change
4. Old documents remain valid until deprecated

Adding New Templates

To create a new template type:

1. Copy existing template structure
2. Adapt metadata and validation rules
3. Define type-specific required fields
4. Create appropriate content sections
5. Add to this README inventory
6. Update CLAUDE.md if needed

---

Best Practices

For Template Users

✅ DO:

• Read the template before creating content
• Fill out ALL required fields
• Follow section structure
• Use absolute paths for relationships
• Keep content current with patch updates

❌ DON'T:

• Skip required fields
• Use relative paths
• Create content without a template
• Change template reference after creation
• Forget to update updated field

For Content Creators

Quality Guidelines:

1. Completeness: Fill out all relevant sections
2. Accuracy: Verify stats, mechanics, and information
3. Currency: Update for current league/patch
4. Links: Create bidirectional relationships
5. Tags: Use consistent, searchable tags

---

Template Quick Reference

Template	Document Type	Primary Use	Location Pattern
build-template.md	Character builds	Full build guides	builds/[class]/
skill-template.md	Skills & gems	Skill documentation	mechanics/skills/
item-template.md	Unique items	Item documentation	mechanics/items/
mechanic-template.md	Game mechanics	Mechanic explanations	mechanics/[category]/
league-template.md	League mechanics	League content docs	mechanics/leagues/
guide-template.md	Strategy guides	How-to guides	research/strategy/
research-template.md	Analysis	Meta/economic research	research/[category]/

---

Getting Help

For questions about:

• Template usage: See template's internal documentation
• Required fields: Check template's validation_rules section
• Naming conventions: See folder READMEs
• General guidance: See /CLAUDE.md

---

Template System Version: 1.0.0 Last Updated: 2025-11-04 Total Templates: 7