# Cursor Rule Hierarchy & Decision Tree

**Last Updated:** 2026-04-04

This document explains the Ordio Cursor rule architecture and provides a decision tree for determining which rules apply to any given task.

**SSOT note:** The canonical list of `.mdc` files lives in `.cursor/rules/`. Run `python3 scripts/ai/rule-footprint.py` for line counts and glob overlap. This document is the human-readable map.

**Rule vs doc vs skill vs subagent:** See `[CURSOR_RULES_MAINTENANCE.md](CURSOR_RULES_MAINTENANCE.md)` § *Rule vs doc vs skill vs subagent*. Official Cursor product links: `[CURSOR_OFFICIAL_DOCS_REFERENCE.md](CURSOR_OFFICIAL_DOCS_REFERENCE.md)`.

## Rule Architecture Overview

### Three-Tier System

1. **Global Rules** (always apply — `alwaysApply: true` in frontmatter)
  - `.cursor/rules/global.mdc` only — plan quality, pointers to `docs/ai/global-guidelines.md`, QA expectations.
2. **Scoped Rules** (apply based on file patterns — `globs` in frontmatter)
  - Page-type-specific rules (product, industry, tools, etc.)
  - Component rules (base components, API endpoints)
  - ShiftOps rules (backend, frontend)
  - Trigger based on `globs` patterns in rule files
3. **On-demand rules** (not always-applied; read when relevant)
  - `.cursor/rules/mcp-usage.mdc` — MCP tool governance (`alwaysApply: false`). Use when the task involves MCP servers, Fetch, browser, or Firecrawl. See `docs/development/MCP_INTEGRATION.md`.
4. **Legacy compatibility**
  - Legacy rule references should be treated as archived guidance; `.cursor/rules/*.mdc` is the active contract.

### Rule Precedence

When multiple rules apply:

1. Global rules provide baseline expectations
2. Scoped rules add specific requirements
3. More specific rules take precedence over general ones
4. Rules combine (don't override) – all applicable rules are considered

## Complete Rule Map

### Always-Applied Rules


| Rule File    | Scope     | Purpose                            |
| ------------ | --------- | ---------------------------------- |
| `global.mdc` | All tasks | Plan quality, tone, QA, validation |


### Page-Type Rules


| Rule File(s)                                                                                    | Glob Pattern                                                                                      | Notes                                                                               |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `comparison-pages-core.mdc`, `comparison-pages-content.mdc`, `comparison-pages-schema-meta.mdc` | `v2/pages/compare_*.php`                                                                          | Split for context efficiency; same glob — all three can attach for comparison edits |
| `product-pages.mdc`                                                                             | `v2/pages/product_*.php`, `v2/css/product-pages.css`                                              | Feature marketing                                                                   |
| `industry-pages.mdc`                                                                            | `v2/pages/industry_*.php`, `v2/pages/branchen_gastronomie_neu.php`                                | Vertical targeting                                                                  |
| `tools-pages.mdc`, `tools-prioritization.mdc`                                                   | `v2/pages/tools_*.php`, `v2/data/tools-faqs/*.json`, `docs/content/tools/**/*.md` (see each file) | Unified tools rule + SISTRIX/prioritization                                         |
| `templates-pages.mdc`                                                                           | `v2/pages/templates_*.php`, `v2/css/templates-pages.css`                                          | Template generators                                                                 |
| `download-pages.mdc`                                                                            | `v2/pages/download_*.php`                                                                         | Gated content                                                                       |
| `webinar-pages.mdc`                                                                             | `v2/pages/webinar_*.php`                                                                          | Event registration                                                                  |
| `pillar-pages.mdc`                                                                              | `v2/pages/pillar_*.php`                                                                           | SEO content hubs                                                                    |
| `static-pages.mdc`                                                                              | `v2/pages/static_*.php`                                                                           | Legal/pricing/about                                                                 |
| `homepage.mdc`                                                                                  | `v2/pages/landingpage*.php`, `v2/pages/start*.php`                                                | Primary entry points                                                                |


### Component & API Rules


| Rule File                                                | Glob Pattern                                                                      | Purpose                                |
| -------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------- |
| `base-components.mdc`                                    | `v2/base/*.php`                                                                   | **HIGH PROTECTION** shared includes    |
| `api-endpoints-core.mdc`, `api-endpoints-security.mdc`   | Explicit per-file globs under `v2/api/` (see each rule; non–ShiftOps endpoints)   | Lead capture, forms, exports, security |
| `shiftops-backend.mdc`                                   | `v2/api/shiftops*.php`, config/data paths per rule frontmatter                    | ShiftOps API/analyzer                  |
| `shiftops-frontend-core.mdc`, `shiftops-frontend-qa.mdc` | `v2/pages/shiftops*.php`, `v2/components/lead-capture*.php`, `v2/js/shiftops*.js` | ShiftOps UI/UX + QA                    |


### Context Management


| File            | Purpose                                                       |
| --------------- | ------------------------------------------------------------- |
| `.cursorignore` | Excludes noise (node_modules, vendor, WordPress core, caches) |
| `.gitignore`    | Git exclusions (includes `.cursor/rules/` for tracking)       |


## Decision Tree

```
START: What are you working on?
│
├─ Is it a page in v2/pages/?
│  │
│  ├─ compare_*.php → comparison-pages-core.mdc + comparison-pages-content.mdc + comparison-pages-schema-meta.mdc
│  ├─ product_*.php → product-pages.mdc
│  ├─ industry_*.php → industry-pages.mdc
│  ├─ tools_*.php → tools-pages.mdc (+ tools-prioritization.mdc when prioritising tool SEO work)
│  ├─ templates_*.php → templates-pages.mdc
│  ├─ download_*.php → download-pages.mdc
│  ├─ webinar_*.php → webinar-pages.mdc
│  ├─ pillar_*.php → pillar-pages.mdc
│  ├─ static_*.php → static-pages.mdc
│  ├─ landingpage*.php or start*.php → homepage.mdc
│  └─ shiftops*.php → shiftops-frontend-core.mdc + shiftops-frontend-qa.mdc
│
├─ Is it a shared component in v2/base/?
│  └─ ⚠️ base-components.mdc (HIGH PROTECTION)
│
├─ Is it an API endpoint in v2/api/?
│  │
│  ├─ shiftops*.php → shiftops-backend.mdc
│  └─ Other listed endpoints → api-endpoints-core.mdc + api-endpoints-security.mdc (per-file globs)
│
├─ Is it ShiftOps-related?
│  │
│  ├─ Backend (API, config, data) → shiftops-backend.mdc
│  └─ Frontend (pages, components, JS) → shiftops-frontend-core.mdc, shiftops-frontend-qa.mdc
│
├─ Is it blog content (JSON posts, drafts, pipeline artifacts)?
│  │
│  ├─ v2/data/blog/posts/**/*.json (and v2/data/blog categories/topics) → blog-json-edit-prohibition.mdc, blog-backup.mdc, global.mdc (body changes via update-post-content.php only)
│  ├─ docs/content/blog/posts/** (CONTENT_OUTLINE.md, content-draft.html, data/*.json) → blog-new-post-creation.mdc, blog-content-creation-gate.mdc, blog-data-collection.mdc as applicable
│  └─ Hub: docs/content/blog/CONTENT_SYSTEM_INDEX.md · Project skills: .cursor/skills/ordio-blog-*
│
├─ Is it template marketing content / template systems docs (beyond PHP shell)?
│  └─ templates-content-creation-gate.mdc, templates-new-template-creation.mdc, templates-cta.mdc, etc. as applicable · Full detail: `docs/ai/agent-workflows.md` · Skill: ordio-template-content-workflow (if present)
│
├─ Is it tools page SEO blocks / tools FAQs / tools content docs (beyond calculator UI)?
│  └─ tools-pages.mdc (pointer to `docs/ai/rules-archive/tools-pages-unified.md`) · `docs/guides/tools-pages/TOOLS_CONTENT_WORKFLOW.md`
│
├─ Is it CSS?
│  │
│  ├─ product-pages.css → product-pages.mdc
│  ├─ tools-pages.css → tools-pages.mdc
│  ├─ templates-pages.css → templates-pages.mdc
│  └─ comparison-pages.css → comparison-pages-*.mdc (same family as compare_*.php)
│
└─ Everything else → global.mdc only
```

## Rule Selection Examples

### Example 1: Update Product Page

**Task:** Update `v2/pages/product_timetracking.php`

**Rules Applied:**

1. `global.mdc` (always)
2. `product-pages.mdc` (matches `v2/pages/product_*.php`)

**Guidance:**

- Global: Concrete plans, du tone, validation steps
- Product: SoftwareApplication schema, benefit-driven copy, CTA patterns

---

### Example 2: Update Comparison Page

**Task:** Update `v2/pages/compare_planday.php`

**Rules Applied:**

1. `global.mdc` (always)
2. `comparison-pages-core.mdc`, `comparison-pages-content.mdc`, `comparison-pages-schema-meta.mdc` (match `v2/pages/compare_*.php`)

**Guidance:**

- Global: Concrete plans, du tone, validation steps
- Comparison: Layout preservation, competitor positioning, schema (Table, Product) — see split rules and `docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md`

---

### Example 3: Update Header Component

**Task:** Update `v2/base/header.php`

**Rules Applied:**

1. `global.mdc` (always)
2. `base-components.mdc` (matches `v2/base/*.php`)

**Guidance:**

- Global: Concrete plans, du tone, validation steps
- Base: **HIGH PROTECTION**, require explicit approval, test across 5+ page types

---

### Example 4: Update ShiftOps API

**Task:** Update `v2/api/shiftops-cost-calculator.php`

**Rules Applied:**

1. `global.mdc` (always)
2. `shiftops-backend.mdc` (matches `v2/api/shiftops*.php`)

**Guidance:**

- Global: Concrete plans, du tone, validation steps
- ShiftOps Backend: Scoring algorithm, caching, error handling, customer matching

---

### Example 5: Update Tools Calculator

**Task:** Update `v2/pages/tools_kostenrechner.php`

**Rules Applied:**

1. `global.mdc` (always)
2. `tools-pages.mdc` (matches `v2/pages/tools_*.php`)

**Guidance:**

- Global: Concrete plans, du tone, validation steps
- Tools: Calculator logic, validation, export (Excel/PDF/CSV), HowTo schema

---

### Example 6: Update Tools CSS

**Task:** Update `v2/css/tools-pages.css`

**Rules Applied:**

1. `global.mdc` (always)
2. `tools-pages.mdc` (matches `v2/css/tools-pages.css`)

**Guidance:**

- Global: Concrete plans, validation steps
- Tools: Form styling, responsive breakpoints, dotted background

---

### Example 7: Multiple Files (Product Page + CSS)

**Task:** Update `v2/pages/product_schichtplan_neu.php` (`/schichtplan`) and `v2/css/product-pages.css`

**Rules Applied:**

1. `global.mdc` (always)
2. `product-pages.mdc` (matches both files)

**Guidance:**

- Global: Concrete plans, du tone, validation steps
- Product: Schema, copy, CTAs, CSS classes

---

### Example 8: Non-Scoped File

**Task:** Update `scripts/generate-resized-webp.js`

**Rules Applied:**

1. `global.mdc` (only)

**Guidance:**

- Global: Concrete plans, validation steps
- No page-type-specific rules apply

---

## Rule Conflict Resolution

### Scenario: Overlapping Rules

If multiple scoped rules could apply (rare), Cursor uses:

1. Most specific glob pattern wins
2. Rules combine (don't override)
3. Later rules can add to earlier rules

### Scenario: Contradictory Guidance

If rules contradict (shouldn't happen with good design):

1. More specific rule takes precedence
2. User can clarify intent in prompt
3. File an issue to fix rule conflict

## Maintenance Guidelines

### When to Update Rules

**Update a rule when:**

- Pattern emerges across multiple tasks
- Common pitfall identified
- New page type added
- Schema requirements change
- Best practice evolves

**Don't update rules for:**

- One-off tasks
- Temporary workarounds
- Experimental features
- User-specific preferences (use memories instead)

### How to Update Rules

1. **Identify the rule:** Use decision tree to find correct rule file
2. **Read existing rule:** Understand current guidance
3. **Plan update:** What needs to change and why?
4. **Edit rule file:** Update `.cursor/rules/[rule].mdc`
5. **Test:** Run dry-run prompts to validate changes
6. **Document:** Update playbook/guides if needed
7. **Monitor:** Watch for regressions or improvements

### Rule Versioning

- Rules are tracked in Git (`.cursor/rules/` included in `.gitignore` exceptions)
- Commit rule changes with clear messages
- Tag major rule updates (e.g., `v1.0-rules`)
- Document breaking changes in commit messages

## Troubleshooting

### Problem: Rule Not Triggering

**Symptoms:** Expected rule doesn't attach to task

**Possible Causes:**

1. Glob pattern doesn't match file path
2. File not in workspace
3. Cursor version doesn't support `.mdc` files

**Solutions:**

1. Check glob pattern in rule file
2. Verify file path matches pattern
3. Update Cursor to latest version
4. Check `.cursorignore` isn't excluding file

---

### Problem: Wrong Rule Triggering

**Symptoms:** Unexpected rule attaches to task

**Possible Causes:**

1. Glob pattern too broad
2. File naming convention changed
3. Multiple rules with overlapping patterns

**Solutions:**

1. Narrow glob pattern in rule file
2. Rename files to match expected pattern
3. Review all rules for conflicts

---

### Problem: Generic Plans Despite Rules

**Symptoms:** Plans still vague even with rules

**Possible Causes:**

1. Rule guidance too vague
2. Prompt lacks specificity
3. Cursor not reading rule content

**Solutions:**

1. Add concrete examples to rule
2. Improve prompt with file paths, selectors
3. Verify rule file syntax (YAML frontmatter, markdown content)

---

### Problem: Too Many Rules Triggering

**Symptoms:** Plans overwhelmed with guidance

**Possible Causes:**

1. Overlapping glob patterns
2. Rules too verbose
3. Redundant guidance across rules

**Solutions:**

1. Narrow glob patterns
2. Keep rules concise (<500 lines per Cursor best practices)
3. Move common guidance to `global.mdc`

---

## Best Practices

### For Rule Authors

1. **Be specific:** Concrete examples > abstract principles
2. **Be concise:** Shorter rules are more likely to be followed
3. **Be actionable:** "Do X" not "Consider X"
4. **Be consistent:** Use same terminology across rules
5. **Be testable:** Include validation checklists

### For Rule Users

1. **Trust the system:** Rules are designed to help, not hinder
2. **Provide context:** Good prompts + good rules = great plans
3. **Report issues:** If rules don't help, document why
4. **Iterate:** Rules improve over time with feedback
5. **Stay updated:** Review rule changes in Git commits

### For Maintainers

1. **Monitor quality:** Track plan quality over time
2. **Gather feedback:** Ask users about rule effectiveness
3. **Evolve gradually:** Small, incremental improvements
4. **Document changes:** Clear commit messages and changelogs
5. **Test thoroughly:** Dry-run prompts after rule updates

---

## Quick Reference Card

**Print this and keep it handy:**

```
┌─────────────────────────────────────────────────────────┐
│ ORDIO CURSOR RULE QUICK REFERENCE                       │
├─────────────────────────────────────────────────────────┤
│ Comparison pages → comparison-pages-core/content/schema-meta.mdc │
│ Product pages → product-pages.mdc                       │
│ Industry pages → industry-pages.mdc                     │
│ Tools pages → tools-pages.mdc                           │
│ Templates pages → templates-pages.mdc                   │
│ Download pages → download-pages.mdc                     │
│ Webinar pages → webinar-pages.mdc                       │
│ Pillar pages → pillar-pages.mdc                         │
│ Static pages → static-pages.mdc                         │
│ Homepage → homepage.mdc                                 │
│ Base components → base-components.mdc ⚠️ HIGH PROTECTION│
│ API endpoints → api-endpoints-core.mdc + security.mdc   │
│ ShiftOps backend → shiftops-backend.mdc                 │
│ ShiftOps frontend → shiftops-frontend-core + qa.mdc     │
│ Everything else → global.mdc (always applies)           │
├─────────────────────────────────────────────────────────┤
│ DOCS: docs/ai/cursor-playbook.md                           │
│       docs/guides/PAGE_TYPE_GUIDES.md                          │
│       docs/ai/validation-workflows.md                      │
│       COMPARISON_PAGES_GUIDE.md                         │
└─────────────────────────────────────────────────────────┘
```

---

## Related Documentation

- **Cursor Playbook:** `docs/ai/cursor-playbook.md` – Workflows and prompt patterns
- **Page Type Guides:** `docs/guides/PAGE_TYPE_GUIDES.md` – Quick reference for each page type
- **Validation Workflows:** `docs/ai/validation-workflows.md` – Schema, links, performance, accessibility
- **Comparison Guide:** `COMPARISON_PAGES_GUIDE.md` – Detailed comparison page requirements
- **Rule Scoping Tests:** `docs/ai/rule-scoping-tests.md` – Test scenarios and expected behavior
- **Cursor Validation:** `docs/ai/cursor-validation.md` – Dry-run results and observations

---

By following this rule hierarchy and decision tree, you'll ensure the right guidance applies to every task, maintaining consistency and quality across all Ordio pages.