# AI Agent Guide - Documentation Discovery

**Last Updated:** 2026-01-08

Complete guide for Cursor AI agents to discover, navigate, and update Ordio documentation.

## Documentation Discovery Patterns

### Finding Documentation by Content Type

#### Tools Documentation

**Pattern:** `docs/content/tools/[tool-slug]-documentation.md`

**Examples:**

- Minijob-Rechner → `docs/content/tools/minijob-rechner-documentation.md`
- Brutto-Netto-Rechner → `docs/content/tools/brutto-netto-rechner-documentation.md`

**Inventory:** `docs/content/tools/TOOLS_INVENTORY.md`

#### Page Documentation

**Pattern:** `docs/content/pages/[page-type]/[page-slug]-documentation.md`

**Examples:**

- Comparison pages → `docs/content/pages/comparison-pages/[competitor-slug]-documentation.md`
- Product pages → `docs/content/pages/product-pages/[product-slug]-documentation.md`
- Industry pages → `docs/content/pages/industry-pages/[industry-slug]-documentation.md`

**Inventories:**

- `docs/content/pages/comparison-pages/COMPARISON_PAGES_INVENTORY.md`
- `docs/content/pages/product-pages/PRODUCT_PAGES_INVENTORY.md`
- `docs/content/pages/industry-pages/INDUSTRY_PAGES_INVENTORY.md`

#### Competitor Documentation

**Pattern:** `docs/content/competitors/[competitor-slug]-profile.md`

**Examples:**

- Personio → `docs/content/competitors/personio-profile.md`
- Deputy → `docs/content/competitors/deputy-profile.md`

**Inventory:** `docs/content/competitors/COMPETITORS_INVENTORY.md`

#### Product Features Documentation

**Pattern:** `docs/content/product-features/[feature-slug]-documentation.md`

**Examples:**

- Schichtplanung → `docs/content/product-features/schichtplanung-documentation.md`
- Zeiterfassung → `docs/content/product-features/zeiterfassung-documentation.md`

**Inventory:** `docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md`

### Finding System Documentation

**Pattern:** `docs/systems/[system-name]/`

**Examples:**

- ShiftOps → `docs/systems/shiftops/`
- Lead Capture → `docs/systems/lead-capture/`
- Product Updates → `docs/systems/product-updates/`

**Inventory:** `docs/systems/SYSTEMS_INVENTORY.md` (to be created)

### Finding Guides

**Pattern:** `docs/guides/[guide-type]/`

**Examples:**

- Comparison pages guide → `docs/guides/comparison-pages/`
- Tools pages guide → `docs/guides/tools-pages/`
- Page type guides → `docs/guides/PAGE_TYPE_GUIDES.md`

## Search Strategies

### 1. Start with Master Index

Always check `docs/README.md` first for navigation and quick links.

### 2. Use Inventory Files

Each content type has an inventory file listing all items:

- `TOOLS_INVENTORY.md` - All tools
- `COMPARISON_PAGES_INVENTORY.md` - All comparison pages
- `COMPETITORS_INVENTORY.md` - All competitors
- `PRODUCT_FEATURES_INVENTORY.md` - All features

### 3. Search by File Pattern

Use file naming patterns to locate documentation:

- Tool docs: `*-documentation.md` in `docs/content/tools/`
- Competitor docs: `*-profile.md` in `docs/content/competitors/`
- Page docs: `*-documentation.md` in `docs/content/pages/`

### 4. Use Search Script

Run search script: `python3 scripts/documentation/find-documentation.py "search term"`

## Before Creating New Documentation

### Step 1: Search Existing Documentation

1. Check [DOCUMENTATION_INVENTORY.md](DOCUMENTATION_INVENTORY.md)
2. Search `docs/` directory using patterns above
3. Check related directories (tools, pages, competitors, etc.)
4. Use search script if needed

### Step 2: Check for Gaps

1. Read [DOCUMENTATION_GAPS.md](DOCUMENTATION_GAPS.md) (pointer; full gap matrices live in [stale-docs-root](archive/2026-04-01-docs-cleanup/stale-docs-root/))
2. Verify documentation doesn't already exist
3. Check if similar documentation can be updated instead

### Step 3: Check Redundancy

1. Review [DOCUMENTATION_REDUNDANCY_REPORT.md](DOCUMENTATION_REDUNDANCY_REPORT.md)
2. Avoid creating duplicate documentation
3. Consolidate if similar docs exist

## Before Updating Documentation

### Step 1: Find Existing Documentation

1. Use search patterns above
2. Check inventory files
3. Verify file location

### Step 2: Read Completely

1. Read entire file before updating
2. Understand current structure
3. Identify what needs updating

### Step 3: Follow Update Process

1. Update content
2. Update "Last Updated" date (use accurate date)
3. Update cross-references
4. Update related inventory files
5. Run validation scripts

## Documentation Update Workflow

### When Code Changes

1. **Identify affected documentation**

   - Which tools/pages/systems are affected?
   - What documentation needs updating?

2. **Find existing documentation**

   - Use search patterns
   - Check inventory files

3. **Update documentation**
   - Follow [DOCUMENTATION_STANDARDS.md](DOCUMENTATION_STANDARDS.md)
   - Update dates and cross-references
   - Run validation

### When Adding New Content

1. **Check if documentation exists**

   - Search for existing docs
   - Check gaps document

2. **Create new documentation**

   - Follow naming conventions
   - Use templates from standards
   - Add to inventory files

3. **Create cross-references**
   - Link from related docs
   - Update master index if needed

## Cursor Rules Discovery

### Finding Relevant Rules

1. **Check rule index:** `.cursor/rules/README.md`
2. **Use decision tree** in rule index
3. **Check file patterns** in rule metadata
4. **Review rule hierarchy:** `docs/ai/rule-hierarchy.md`

### Rule Application

- Global rules (`global.mdc`) always apply
- Scoped rules apply based on file patterns
- Multiple rules can apply simultaneously

## Validation Commands

### Link Validation

```bash
python3 scripts/documentation/validate-links.py
```

### Date Validation

```bash
python3 scripts/documentation/update-dates.py --check
```

### Redundancy Check

```bash
python3 scripts/documentation/check-redundancy.py
```

### Find Documentation

```bash
python3 scripts/documentation/find-documentation.py "search term"
```

## Quick Reference

### Documentation Locations

- **Master Index:** `docs/README.md`
- **Inventory:** `docs/DOCUMENTATION_INVENTORY.md`
- **Gaps:** `docs/DOCUMENTATION_GAPS.md`
- **Standards:** `docs/DOCUMENTATION_STANDARDS.md`
- **Maintenance:** `docs/DOCUMENTATION_MAINTENANCE_PROCESS.md`

### Content Documentation

- **Tools:** `docs/content/tools/`
- **Pages:** `docs/content/pages/`
- **Competitors:** `docs/content/competitors/`
- **Features:** `docs/content/product-features/`
- **Blog:** `docs/content/blog/`

### System Documentation

- **Systems:** `docs/systems/`
- **Guides:** `docs/guides/`
- **Reference:** `docs/reference/`
- **Development:** `docs/development/`
- **AI:** `docs/ai/`

### Cursor Rules

- **Rule Index:** `.cursor/rules/README.md`
- **All Rules:** `.cursor/rules/*.mdc`

## Semantic Search Patterns

### Common Query Patterns

**"How do I create [page type]?"**
→ Check [Semantic Search Index](ai/SEMANTIC_SEARCH_INDEX.md) for query → documentation mapping
→ Use [Rule Discovery Patterns](ai/RULE_DISCOVERY_PATTERNS.md) to find applicable rules

**"Where is [content type] documented?"**
→ Check content inventories:

- Tools → `docs/content/tools/TOOLS_INVENTORY.md`
- Competitors → `docs/content/competitors/COMPETITORS_INVENTORY.md`
- Product Features → `docs/content/product-features/PRODUCT_FEATURES_INVENTORY.md`
- Pages → `docs/content/pages/[page-type]/[PAGE_TYPE]_INVENTORY.md`

**"What rules apply to [file path]?"**
→ Use [Rule Discovery Patterns](ai/RULE_DISCOVERY_PATTERNS.md) file path → rule mapping
→ Check `.cursor/rules/METADATA_INDEX.json` for programmatic lookup

### Semantic Search Workflow

1. **Start with query type**

   - Page creation → Check Semantic Search Index
   - System development → Check system documentation
   - Content management → Check content inventories

2. **Find relevant documentation**

   - Use Semantic Search Index for common queries
   - Use Rule Discovery Patterns for file-based queries
   - Use Rule-to-Doc Mapping for rule-based queries

3. **Discover applicable rules**

   - Match file path against Rule Discovery Patterns
   - Check Rule Dependency Graph for rule combinations
   - Always include `global.mdc` and check for `shared-patterns.mdc`

4. **Read documentation and rules**
   - Read relevant guide files completely
   - Read applicable rule files completely
   - Check cross-references in both directions

## Rule Discovery Patterns

### File Path → Rule Discovery

**Pattern Matching:**

- Extract file path from task
- Match against patterns in [Rule Discovery Patterns](ai/RULE_DISCOVERY_PATTERNS.md)
- Check `.cursor/rules/README.md` decision tree
- Verify with `METADATA_INDEX.json`

**Rule Combination:**

- Always include `global.mdc`
- Include page-type or system-specific rules
- Include `shared-patterns.mdc` for validation checklists
- Check Rule Dependency Graph for combinations

### Task Type → Rule Selection

**Creating new content:**

- Identify file pattern
- Apply page-type rules
- Check documentation for creation guides
- Follow planning requirements from `global.mdc`

**Updating existing content:**

- Identify file pattern
- Apply same rules as creation
- Check existing documentation
- Follow update workflows

**Working with systems:**

- Identify system component
- Apply system-specific rules
- Check system documentation
- Include API rules if applicable

## Cross-Reference Navigation

### Rule → Documentation

**When working with a rule:**

1. Check rule file's "Related Documentation" section
2. Use [Rule to Documentation Mapping](ai/RULE_TO_DOC_MAPPING.md)
3. Read relevant guide files
4. Check content inventories if applicable

### Documentation → Rule

**When working with documentation:**

1. Check documentation's "Related Cursor Rules" section
2. Use [Rule to Documentation Mapping](ai/RULE_TO_DOC_MAPPING.md) (reverse lookup)
3. Check Rule Discovery Patterns for file patterns
4. Verify rules apply to your task

### Bidirectional Discovery

**Complete workflow:**

1. Start with task/file path
2. Find applicable rules using Rule Discovery Patterns
3. Check rule's Related Documentation
4. Read documentation files
5. Check documentation's Related Rules
6. Verify all rules are accounted for

## Related Documentation

- **[Documentation Standards](DOCUMENTATION_STANDARDS.md)** - File naming and structure
- **[Maintenance Process](DOCUMENTATION_MAINTENANCE_PROCESS.md)** - Update workflows
- **[Rule Hierarchy](ai/rule-hierarchy.md)** - Cursor rule architecture
- **[Cursor Playbook](ai/cursor-playbook.md)** - Complete workflow guide
- **[Semantic Search Index](ai/SEMANTIC_SEARCH_INDEX.md)** - Query → documentation mapping
- **[Rule Discovery Patterns](ai/RULE_DISCOVERY_PATTERNS.md)** - File path → rule mapping
- **[Rule to Documentation Mapping](ai/RULE_TO_DOC_MAPPING.md)** - Bidirectional mapping
- **[Rule Dependency Graph](ai/RULE_DEPENDENCY_GRAPH.md)** - Visual rule relationships