# Rule Discovery Patterns for AI Agents

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

Patterns and strategies for AI agents to discover relevant Cursor rules based on file paths, task types, and content types.

## File Path → Rule Mapping Patterns

### Page Files (`v2/pages/`)

**Comparison Pages:**

- Pattern: `v2/pages/compare_*.php`
- Rules: `comparison-pages-core.mdc`, `comparison-pages-content.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Tools Pages:**

- Pattern: `v2/pages/tools_*.php`
- Rules: `tools-pages-core-design.mdc`, `tools-pages-core-validation.mdc`, `tools-pages-schema.mdc`, `tools-pages-faq.mdc`
- Additional rules as needed: `tools-pages-patterns-export.mdc`, `tools-pages-patterns-gated.mdc`, `tools-pages-reference.mdc`, `tools-pages-documentation.mdc`
- Special case: `tools-pages-alg1-calculator.mdc` for `tools_arbeitslosengeld_rechner.php`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Product Pages:**

- Pattern: `v2/pages/product_*.php`
- Rules: `product-pages.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Industry Pages:**

- Pattern: `v2/pages/industry_*.php`
- Rules: `industry-pages.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Template Pages:**

- Pattern: `v2/pages/templates_*.php`
- Rules: `templates-pages.mdc`, `templates-cta.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Download Pages:**

- Pattern: `v2/pages/download_*.php`
- Rules: `download-pages.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Webinar Pages:**

- Pattern: `v2/pages/webinar_*.php`
- Rules: `webinar-pages.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Pillar Pages:**

- Pattern: `v2/pages/pillar_*.php`
- Rules: `pillar-pages.mdc`, `content-clusters.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Static Pages:**

- Pattern: `v2/pages/static_*.php`
- Rules: `static-pages.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Homepage:**

- Pattern: `v2/pages/landingpage*.php`, `v2/pages/start*.php`
- Rules: `homepage.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

### Component Files

**Base Components (HIGH PROTECTION):**

- Pattern: `v2/base/*.php`
- Rules: `base-components.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`
- ⚠️ **Requires explicit approval before editing**

**API Endpoints:**

- Pattern: `v2/api/*.php` (excluding ShiftOps)
- Rules: `api-endpoints-core.mdc`, `api-endpoints-security.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**ShiftOps API:**

- Pattern: `v2/api/shiftops*.php`, `v2/config/shiftops-*.php`
- Rules: `shiftops-backend.mdc`, `api-endpoints-core.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**ShiftOps Frontend:**

- Pattern: `v2/pages/shiftops*.php`, `v2/js/shiftops*.js`
- Rules: `shiftops-frontend-core.mdc`, `shiftops-frontend-qa.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Lead Capture:**

- Pattern: `v2/components/lead-capture*.php`, `v2/js/lead-capture*.js`
- Rules: `lead-capture.mdc`, `form-tracking.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Form Tracking:**

- Pattern: `v2/base/include_form*.php`, `v2/js/*form*.js`
- Rules: `form-tracking.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Excel Generator:**

- Pattern: `v2/systems/excel-template-generator/**/*`
- Rules: `excel-template-generator.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Product Updates:**

- Pattern: `v2/pages/produkt_updates*.php`, `v2/data/produkt_updates.json`
- Rules: `product-updates.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Testimonials:**

- Pattern: `v2/data/testimonials/**/*.json`
- Rules: `testimonials.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

**Booking Calendars:**

- Pattern: `v2/pages/*booking*.php`, `v2/pages/*calendar*.php`
- Rules: `booking-calendars.mdc`
- Always also: `global.mdc`, `shared-patterns.mdc`

### Documentation Files

**Tools Documentation:**

- Pattern: `docs/guides/tools-pages/*.md`, `docs/content/tools/*.md`
- Rules: `tools-pages-documentation.mdc`
- Always also: `global.mdc`

**SEO Strategy Documentation:**

- Pattern: `docs/seo-strategy-2026/**/*` (if tracked)
- Rules: `seo-strategy-2026.mdc`, `seo-strategy-organic-goals.mdc`, `goal-setting-metrics.mdc`
- Always also: `global.mdc`

**Dashboard Documentation:**

- Pattern: `docs/seo-strategy-2026/**/*` (if tracked), `v2/admin/seo-dashboard/**/*`
- Rules: `dashboard.mdc`, `seo-dashboard-admin.mdc`
- Always also: `global.mdc`

## Task Type → Rule Selection Patterns

### Creating New Content

**Creating a comparison page:**

1. Check file pattern: `v2/pages/compare_*.php`
2. Apply rules: `comparison-pages-core.mdc`, `comparison-pages-content.mdc`
3. Always include: `global.mdc`, `shared-patterns.mdc`
4. Check documentation: `docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md`

**Creating a tools page:**

1. Check file pattern: `v2/pages/tools_*.php`
2. Apply rules: `tools-pages-core-design.mdc`, `tools-pages-core-validation.mdc`, `tools-pages-schema.mdc`, `tools-pages-faq.mdc`
3. Check if export needed → add `tools-pages-patterns-export.mdc`
4. Check if gated content → add `tools-pages-patterns-gated.mdc`
5. Always include: `global.mdc`, `shared-patterns.mdc`
6. Check documentation: `docs/guides/tools-pages/README.md`

**Creating an API endpoint:**

1. Check file pattern: `v2/api/*.php`
2. Check if ShiftOps → `shiftops-backend.mdc`
3. Otherwise → `api-endpoints-core.mdc`, `api-endpoints-security.mdc`
4. Always include: `global.mdc`, `shared-patterns.mdc`

### Updating Existing Content

**Updating a comparison page:**

1. Identify file: `v2/pages/compare_*.php`
2. Apply same rules as creation
3. Check for data updates: `v2/data/competitors.php`
4. Check documentation: `docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md`

**Updating a tool:**

1. Identify file: `v2/pages/tools_*.php`
2. Apply same rules as creation
3. Check documentation: `docs/content/tools/[tool-slug]-documentation.md`
4. Check maintenance guide: `docs/guides/tools-pages/TOOLS_MAINTENANCE_GUIDE.md`

**Updating base components:**

1. Identify file: `v2/base/*.php`
2. ⚠️ **STOP** - Requires explicit approval
3. Apply rules: `base-components.mdc`
4. Always include: `global.mdc`, `shared-patterns.mdc`
5. Test across 5+ page types before finalizing

### Working with Systems

**Working with ShiftOps:**

1. Identify file pattern
2. Backend (`v2/api/shiftops*.php`) → `shiftops-backend.mdc`
3. Frontend (`v2/pages/shiftops*.php`) → `shiftops-frontend-core.mdc`, `shiftops-frontend-qa.mdc`
4. Always include: `global.mdc`, `shared-patterns.mdc`, `api-endpoints-core.mdc`
5. Check documentation: `docs/systems/shiftops/`

**Working with lead capture:**

1. Identify file pattern: `v2/components/lead-capture*.php`
2. Apply rules: `lead-capture.mdc`, `form-tracking.mdc`
3. Always include: `global.mdc`, `shared-patterns.mdc`
4. Check documentation: `docs/systems/lead-capture/`

## Content Type → Rule Application Patterns

### Tools/Calculators

**All tools pages:**

- Core rules: `tools-pages-core-design.mdc`, `tools-pages-core-validation.mdc`, `tools-pages-schema.mdc`, `tools-pages-faq.mdc`
- Reference: `tools-pages-reference.mdc` (for troubleshooting)
- Documentation: `tools-pages-documentation.mdc` (for doc updates)
- Always: `global.mdc`, `shared-patterns.mdc`

**ALG 1 Calculator specifically:**

- Add: `tools-pages-alg1-calculator.mdc`
- File: `v2/pages/tools_arbeitslosengeld_rechner.php`

### Comparison Pages

**All comparison pages:**

- Core rules: `comparison-pages-core.mdc`, `comparison-pages-content.mdc`
- Always: `global.mdc`, `shared-patterns.mdc`
- Data source: `v2/data/competitors.php`

### Product Pages

**All product pages:**

- Rules: `product-pages.mdc`
- Always: `global.mdc`, `shared-patterns.mdc`
- Documentation: `docs/content/product-features/`

## Discovery Workflow

### Step 1: Identify File Pattern

1. Extract file path from task
2. Match against known patterns (see above)
3. Identify file type (page, component, system, etc.)

### Step 2: Find Applicable Rules

1. Check `.cursor/rules/README.md` decision tree
2. Match file pattern against rule globs in `METADATA_INDEX.json`
3. Always include `global.mdc`
4. Check if `shared-patterns.mdc` is referenced

### Step 3: Check Documentation

1. Use `docs/ai/RULE_TO_DOC_MAPPING.md` to find related docs
2. Check rule file's "Related Documentation" section
3. Read relevant guide files before making changes

### Step 4: Apply Rules

1. Read all applicable rule files completely
2. Follow planning requirements from `global.mdc`
3. Apply page-type-specific patterns
4. Use validation checklists from `shared-patterns.mdc`

## Rule Combination Patterns

### Always Applied Together

**Every task:**

- `global.mdc` (always)

**Every page-type task:**

- `global.mdc` + page-type rule(s) + `shared-patterns.mdc`

**Every API task:**

- `global.mdc` + `api-endpoints-core.mdc` + `shared-patterns.mdc`

**Every ShiftOps task:**

- `global.mdc` + `shiftops-backend.mdc` or `shiftops-frontend-core.mdc` + `api-endpoints-core.mdc` + `shared-patterns.mdc`

### Conditional Combinations

**Tools pages with export:**

- Add `tools-pages-patterns-export.mdc`

**Tools pages with gated content:**

- Add `tools-pages-patterns-gated.mdc`

**Comparison pages with content updates:**

- Ensure both `comparison-pages-core.mdc` and `comparison-pages-content.mdc` are checked

**Pillar pages:**

- Add `content-clusters.mdc` for content cluster strategy

## Quick Reference

### Rule Discovery Checklist

- [ ] Identify file path pattern
- [ ] Check `.cursor/rules/README.md` decision tree
- [ ] Match against `METADATA_INDEX.json` globs
- [ ] Always include `global.mdc`
- [ ] Include `shared-patterns.mdc` for validation
- [ ] Check rule file's "Related Documentation" section
- [ ] Read relevant documentation files
- [ ] Apply all applicable rules

### Common Rule Combinations

**Page Creation:**

- `global.mdc` + page-type rule + `shared-patterns.mdc`

**System Development:**

- `global.mdc` + system rule + `api-endpoints-core.mdc` + `shared-patterns.mdc`

**Component Editing:**

- `global.mdc` + component rule + `shared-patterns.mdc`
- ⚠️ Base components require approval

## Related Documentation

- **[Semantic Search Index](SEMANTIC_SEARCH_INDEX.md)** - Query → documentation mapping
- **[Rule to Documentation Mapping](RULE_TO_DOC_MAPPING.md)** - Bidirectional mapping
- **[Rule Dependency Graph](RULE_DEPENDENCY_GRAPH.md)** - Visual rule relationships
- **[Cursor Rules Index](.cursor/rules/README.md)** - Complete rule list
- **[AI Agent Guide](AI_AGENT_GUIDE.md)** - Complete documentation discovery guide