# Decision Trees for AI Agents

Visual decision trees to help AI agents navigate documentation and understand which rules apply.

**Last Updated:** 2025-11-20

## Documentation Navigation Decision Tree

```
What are you trying to do?
│
├─ Create a new page?
│  ├─ Comparison page? → guides/comparison-pages/COMPARISON_PAGES_GUIDE.md
│  ├─ Product page? → guides/PAGE_TYPE_GUIDES.md (Product Pages section)
│  ├─ Industry page? → guides/PAGE_TYPE_GUIDES.md (Industry Pages section)
│  ├─ Tools page? → guides/tools-pages/
│  ├─ Template page? → guides/PAGE_TYPE_GUIDES.md (Templates Pages section)
│  ├─ Download page? → guides/PAGE_TYPE_GUIDES.md (Download Pages section)
│  ├─ Webinar page? → guides/PAGE_TYPE_GUIDES.md (Webinar Pages section)
│  ├─ Pillar page? → guides/PAGE_TYPE_GUIDES.md (Pillar Pages section)
│  ├─ Static page? → guides/PAGE_TYPE_GUIDES.md (Static Pages section)
│  └─ Homepage? → guides/PAGE_TYPE_GUIDES.md (Homepage section)
│
├─ Work on a system?
│  ├─ ShiftOps? → systems/shiftops/
│  ├─ Lead Capture? → systems/lead-capture/
│  └─ Product Updates? → systems/product-updates/
│
├─ Need technical reference?
│  ├─ API documentation? → reference/api/
│  ├─ Architecture? → reference/architecture/
│  └─ Date management? → reference/DATE_HELPER.md
│
├─ Developer tasks?
│  ├─ Setup environment? → development/setup/
│  ├─ Write tests? → development/testing/
│  ├─ Debug issues? → development/troubleshooting/
│  └─ JavaScript logging? → development/JAVASCRIPT_LOGGING_BEST_PRACTICES.md
│
└─ AI agent tasks?
   ├─ Understand rules? → ai/rule-hierarchy.md
   ├─ Workflow guide? → ai/cursor-playbook.md
   ├─ Validation? → ai/validation-workflows.md
   └─ Configure Cursor? → ai/CURSOR_MODEL_CONFIGURATION.md
```

## Rule Selection Decision Tree

```
Which rule applies to your task?
│
├─ File pattern matches?
│  ├─ v2/pages/compare_*.php → comparison-pages-core.mdc + comparison-pages-content.mdc
│  ├─ v2/pages/product_*.php → product-pages.mdc
│  ├─ v2/pages/industry_*.php → industry-pages.mdc
│  ├─ v2/pages/tools_*.php → tools-pages-*.mdc (multiple files)
│  ├─ v2/pages/templates_*.php → templates-pages.mdc
│  ├─ v2/pages/download_*.php → download-pages.mdc
│  ├─ v2/pages/webinar_*.php → webinar-pages.mdc
│  ├─ v2/pages/pillar_*.php → pillar-pages.mdc
│  ├─ v2/pages/static_*.php → static-pages.mdc
│  ├─ v2/pages/landingpage*.php → homepage.mdc
│  ├─ v2/base/*.php → base-components.mdc (HIGH PROTECTION)
│  ├─ v2/api/shiftops-*.php → shiftops-backend.mdc
│  ├─ v2/js/shiftops-*.js → shiftops-frontend-core.mdc + shiftops-frontend-qa.mdc
│  └─ v2/api/*.php → api-endpoints-core.mdc + api-endpoints-security.mdc
│
├─ Task type?
│  ├─ Lead capture popup? → lead-capture.mdc
│  ├─ Product updates? → product-updates.mdc
│  ├─ Content clusters? → content-clusters.mdc
│  └─ Date management? → date-management.mdc
│
└─ Always applies?
   └─ global.mdc (applies to all tasks)
```

## Documentation Reference Decision Tree

```
Need to find documentation?
│
├─ What type?
│  ├─ User guide? → guides/
│  ├─ System docs? → systems/
│  ├─ Technical reference? → reference/
│  ├─ Developer docs? → development/
│  └─ AI agent docs? → ai/
│
├─ Specific topic?
│  ├─ Comparison pages? → guides/comparison-pages/
│  ├─ Tools pages? → guides/tools-pages/
│  ├─ ShiftOps? → systems/shiftops/
│  ├─ Lead capture? → systems/lead-capture/
│  ├─ Product updates? → systems/product-updates/
│  ├─ API? → reference/api/
│  ├─ Architecture? → reference/architecture/
│  ├─ Setup? → development/setup/
│  ├─ Testing? → development/testing/
│  └─ Troubleshooting? → development/troubleshooting/
│
└─ Quick reference?
   └─ QUICK_START.md
```

## Planning Decision Tree

```
Starting a new task?
│
├─ Research-heavy task?
│  ├─ New feature with unfamiliar requirements
│  ├─ Architecture changes
│  ├─ Unfamiliar code/technologies
│  └─ Complex refactoring
│  └─ → Full 5-phase plan (Discovery, Implementation, Validation, Risks, Handoff)
│
├─ Implementation-heavy task?
│  ├─ Well-defined requirements
│  ├─ Following existing patterns
│  └─ Adding known features
│  └─ → 3-phase plan (Discovery, Implementation, Validation)
│
└─ Maintenance task?
   ├─ Bug fixes with known cause
   ├─ Typo corrections
   └─ Schema/meta tag updates
   └─ → 2-phase plan (Discovery, Implementation)
```

## Validation Decision Tree

```
What needs validation?
│
├─ Schema?
│  └─ → Use Google Rich Results Test
│
├─ Links?
│  └─ → Check all internal/external links work
│
├─ Performance?
│  └─ → PageSpeed Insights, check LCP, FID, CLS
│
├─ Accessibility?
│  └─ → Check alt text, heading hierarchy, keyboard navigation
│
└─ Code quality?
   └─ → Run lint, check console, verify functionality
```

## Quick Reference

- **Can't decide?** → Start with [QUICK_START.md](../QUICK_START.md)
- **Need rule info?** → See [rule-hierarchy.md](rule-hierarchy.md)
- **Workflow help?** → See [cursor-playbook.md](cursor-playbook.md)
- **Validation?** → See [validation-workflows.md](validation-workflows.md)