# Cursor Rule Validation Log


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

## 2025-11-07 Dry Run

### Scenario

Prompted Cursor (Plan Mode) with:

```
Create a plan to refresh `v2/pages/compare_askdante.php`. Goals: update hero copy to the latest du messaging, refresh pricing table with the spreadsheet provided, and regenerate JSON-LD schema. Keep comparison layout + CSS untouched.
```

### Observations

- Plan automatically attached the new rule set (`global.mdc`, `comparison-pages.mdc`) and referenced `docs/ai/cursor-playbook.md`.
- Generated checklist included:
  1. Confirm assets + context (hero copy source, pricing JSON, schema template).
  2. Edit targets with file paths (`v2/pages/compare_askdante.php`, `COMPARISON_PAGES_GUIDE.md` for reference).
  3. Explicit tooling suggestions (use Multi-Edit for table rows, block replace for hero copy).
  4. Validation steps (local preview, schema/jsonlint check, PageSpeed spot-check, visual diff).
- Plan called out risk areas: unintended class changes, missing preload tag, duplicate Ordio mentions.
- Output matched the required plan depth (file paths, selectors, QA) and avoided vague language.

### Additional Checks

- `.cursorignore` reduced context suggestions to relevant PHP/JS files; heavy directories (WordPress core, node_modules, vendor) stayed out of context.
- Scoped rules triggered correctly for a ShiftOps backend prompt (confirmed `shiftops-backend.mdc` details appeared when planning an analyzer refactor).
- Legacy `.cursorrules` no longer duplicates guidance; it points to the new rule structure, preventing rule bloat.

### Next Steps

- Monitor upcoming agent runs for a week and log any plan regressions here.
- Consider automating plan snapshot capture via Cursor's upcoming plan export once available.

---

## 2025-11-07 Comprehensive Optimization Implementation

### Overview

Completed comprehensive Cursor rule optimization covering all Ordio page types, components, and API endpoints.

### What Was Implemented

**New Rule Files Created (11 total):**

1. `.cursor/rules/product-pages.mdc` – Product/feature marketing pages
2. `.cursor/rules/industry-pages.mdc` – Industry/Branchen vertical pages
3. `.cursor/rules/tools-pages.mdc` – Interactive calculator pages
4. `.cursor/rules/templates-pages.mdc` – Template generator pages
5. `.cursor/rules/download-pages.mdc` – Gated content pages
6. `.cursor/rules/webinar-pages.mdc` – Event registration pages
7. `.cursor/rules/pillar-pages.mdc` – SEO content hub pages
8. `.cursor/rules/static-pages.mdc` – Legal/pricing/about pages
9. `.cursor/rules/homepage.mdc` – Homepage/landing pages
10. `.cursor/rules/base-components.mdc` – Shared includes (HIGH PROTECTION)
11. `.cursor/rules/api-endpoints.mdc` – API handlers (non-ShiftOps)

**Existing Rules (4 total):**

- `.cursor/rules/global.mdc` – Already existed, applies to all tasks
- `.cursor/rules/comparison-pages.mdc` – Already existed, updated
- `.cursor/rules/shiftops-backend.mdc` – Already existed
- `.cursor/rules/shiftops-frontend.mdc` – Already existed

**Documentation Created/Updated:**

1. `docs/ai/cursor-playbook.md` – Expanded with page-type-specific workflows, prompt patterns, decision tree, quick reference table
2. `docs/guides/PAGE_TYPE_GUIDES.md` – NEW: Quick reference guides for all page types
3. `docs/ai/validation-workflows.md` – NEW: Schema, link, performance, accessibility validation workflows
4. `docs/rule-scoping-tests.md` – NEW: Test scenarios for each page type
5. `docs/ai/rule-hierarchy.md` – NEW: Rule architecture, decision tree, troubleshooting
6. `.cursorrules` – Updated to point to new rule structure (legacy compatibility)
7. `.cursorignore` – Already existed, optimized
8. `.gitignore` – Updated to track `.cursor/rules/` directory

### Coverage Analysis

**Page Types Covered:**

- ✅ Comparison pages (67 files) – `comparison-pages.mdc`
- ✅ Product pages (8 files) – `product-pages.mdc`
- ✅ Industry pages (5 files) – `industry-pages.mdc`
- ✅ Tools pages (15 files) – `tools-pages.mdc`
- ✅ Templates pages (3 files) – `templates-pages.mdc`
- ✅ Download pages (5 files) – `download-pages.mdc`
- ✅ Webinar pages (4 files) – `webinar-pages.mdc`
- ✅ Pillar pages (3 files) – `pillar-pages.mdc`
- ✅ Static pages (15 files) – `static-pages.mdc`
- ✅ Homepage/landing pages (5 files) – `homepage.mdc`
- ✅ Base components (40 files) – `base-components.mdc`
- ✅ API endpoints (9 files) – `api-endpoints.mdc`
- ✅ ShiftOps backend (~20 files) – `shiftops-backend.mdc`
- ✅ ShiftOps frontend (~10 files) – `shiftops-frontend.mdc`

**Total Coverage:** 179 PHP files in `v2/pages/` + 40 base components + 20+ API endpoints = **239+ files** with specific rule guidance

### Rule Architecture

**Three-Tier System:**

1. **Global Rules** (always apply) – `global.mdc`
2. **Scoped Rules** (apply based on file patterns) – 14 page-type/component rules
3. **Legacy Rules** (backward compatibility) – `.cursorrules`

**Rule Precedence:**

- Global rules provide baseline expectations
- Scoped rules add specific requirements
- More specific rules take precedence
- Rules combine (don't override)

### Key Features

**Each Rule Includes:**

- Purpose and scope (glob patterns)
- Required elements and structure
- Schema requirements (specific to page type)
- Copy guidelines (du tone, Ordio mentions, competitor language)
- Component usage patterns
- CSS guidelines and available classes
- Meta tags requirements
- Performance and accessibility guidelines
- Editing workflow (plan, tool selection, validation)
- Common pitfalls
- Validation checklist

**Special Protections:**

- **HIGH PROTECTION** for `base-components.mdc` (requires explicit approval, extensive testing)
- Legal page protection in `static-pages.mdc` (changes require approval)
- Excel branding compliance in `tools-pages.mdc` and `templates-pages.mdc` (memory reference)

### Documentation Highlights

**Cursor Playbook (`docs/ai/cursor-playbook.md`):**

- Page-type-specific workflows for all 14 page types
- Prompt patterns for each page type
- Rule decision tree (text-based)
- Quick reference table (page type → rule file → schema → focus)

**Page Type Guides (`docs/guides/PAGE_TYPE_GUIDES.md`):**

- Quick reference for each page type
- Purpose, key elements, required schema
- Copy guidelines, CSS classes, validation checklists
- General guidelines (du tone, Ordio mentions, performance, accessibility, SEO)
- Quick reference table (page type → schema → focus → common pitfall)

**Validation Workflows (`docs/ai/validation-workflows.md`):**

- Schema validation (JSON-LD, required fields, URLs, dates)
- Link checking (internal, external, CTA buttons)
- Performance audits (PageSpeed, LCP, CLS, image optimization)
- Accessibility audits (WCAG compliance, keyboard nav, color contrast)
- Content quality checks (du tone, Ordio mentions, competitor language)
- SEO checks (meta tags, keywords)
- Pre-deployment checklist

**Rule Scoping Tests (`docs/rule-scoping-tests.md`):**

- 12 test scenarios (one per major page type + base components + API)
- Expected rules, plan quality indicators, validation steps
- Test log template for user testing
- Continuous monitoring guidelines

**Rule Hierarchy (`docs/ai/rule-hierarchy.md`):**

- Complete rule map (15 rules total)
- Visual decision tree
- Rule selection examples (8 scenarios)
- Conflict resolution guidelines
- Maintenance guidelines (when/how to update rules)
- Troubleshooting (4 common problems + solutions)
- Best practices (for authors, users, maintainers)
- Quick reference card (printable)

### Expected Benefits

**Plan Quality:**

- ✅ Specific file paths instead of vague "update the page"
- ✅ Selectors and line ranges for precise edits
- ✅ Validation steps listed (schema, links, performance, accessibility)
- ✅ Risk callouts (unintended changes, missing elements, schema errors)
- ✅ Tool suggestions (Multi-Edit, block replacement, targeted edits)
- ✅ References to relevant docs (playbook, guides)

**Consistency:**

- ✅ Du tone enforced across all pages
- ✅ Ordio mentions natural (once per major section)
- ✅ No competitor praise
- ✅ Schema requirements clear and consistent
- ✅ Performance and accessibility standards uniform

**Efficiency:**

- ✅ Faster edits (right tool for the job)
- ✅ Fewer errors (validation checklists)
- ✅ Less rework (clear guardrails)
- ✅ Better context (`.cursorignore` excludes noise)

**Safety:**

- ✅ HIGH PROTECTION for shared components
- ✅ Legal page safeguards
- ✅ Excel branding compliance
- ✅ Risk awareness in plans

### Validation Status

**Comparison Pages:** ✅ Previously validated (2025-11-07 dry run)

- Rules attached correctly (`global.mdc`, `comparison-pages.mdc`)
- Plan quality high (file paths, selectors, validation, risks)
- Context optimized (`.cursorignore` working)

**Other Page Types:** ⏳ Pending user testing

- Test scenarios documented in `docs/rule-scoping-tests.md`
- Expected behavior defined
- Test log template provided

### Next Steps

**Immediate (Week 1):**

1. ✅ Complete comprehensive optimization (DONE)
2. ⏳ User tests rule scoping for each page type
3. ⏳ Log observations in `docs/rule-scoping-tests.md`
4. ⏳ Adjust rules if scoping issues found

**Short-term (Month 1):**

1. Monitor plan quality across all page types
2. Log any plan regressions in this document
3. Gather user feedback on rule effectiveness
4. Iterate on rules based on feedback

**Long-term (Quarter 1):**

1. Automate validation workflows (schema, links, performance)
2. Create plan quality metrics dashboard
3. Explore Cursor plan export for automated testing
4. Consider rule versioning and changelog

### Success Metrics

**Plan Quality Indicators:**

- Plans include specific file paths (target: 100%)
- Plans include validation steps (target: 100%)
- Plans call out risks (target: 80%+)
- Plans suggest appropriate tools (target: 80%+)

**Consistency Indicators:**

- Du tone maintained (target: 100%)
- Ordio mentions natural (target: 100%)
- No competitor praise (target: 100%)
- Schema requirements met (target: 95%+)

**Efficiency Indicators:**

- Fewer edit retries (target: -50%)
- Faster task completion (target: -30%)
- Fewer validation errors (target: -70%)

**Safety Indicators:**

- No unintended base component changes (target: 0)
- No legal page changes without approval (target: 0)
- Excel branding compliance (target: 100%)

### Files Changed

**New Files (17):**

- `.cursor/rules/product-pages.mdc`
- `.cursor/rules/industry-pages.mdc`
- `.cursor/rules/tools-pages.mdc`
- `.cursor/rules/templates-pages.mdc`
- `.cursor/rules/download-pages.mdc`
- `.cursor/rules/webinar-pages.mdc`
- `.cursor/rules/pillar-pages.mdc`
- `.cursor/rules/static-pages.mdc`
- `.cursor/rules/homepage.mdc`
- `.cursor/rules/base-components.mdc`
- `.cursor/rules/api-endpoints.mdc`
- `docs/ai/cursor-playbook.md` (expanded)
- `docs/guides/PAGE_TYPE_GUIDES.md` (new)
- `docs/ai/validation-workflows.md` (new)
- `docs/rule-scoping-tests.md` (new)
- `docs/ai/rule-hierarchy.md` (new)
- `docs/ai/cursor-validation.md` (this file, updated)

**Modified Files (2):**

- `.cursorrules` (updated to point to new structure)
- `.gitignore` (updated to track `.cursor/rules/`)

**Existing Files (unchanged):**

- `.cursorignore` (already optimized)
- `.cursor/rules/global.mdc` (already existed)
- `.cursor/rules/comparison-pages.mdc` (already existed)
- `.cursor/rules/shiftops-backend.mdc` (already existed)
- `.cursor/rules/shiftops-frontend.mdc` (already existed)
- `COMPARISON_PAGES_GUIDE.md` (already existed)

### Conclusion

The comprehensive Cursor optimization is complete. All Ordio page types, components, and API endpoints now have specific rule guidance. Documentation is thorough and cross-referenced. The system is ready for user testing and monitoring.

**Key Achievement:** From 4 rules covering ~70 comparison pages to **15 rules covering 239+ files** across the entire Ordio website.

**Next Milestone:** User validation of rule scoping and plan quality across all page types.

---

## Monitoring Log

### Week 1 (2025-11-07 to 2025-11-14)

_User to log observations here_

### Week 2 (2025-11-14 to 2025-11-21)

_User to log observations here_

### Week 3 (2025-11-21 to 2025-11-28)

_User to log observations here_

### Week 4 (2025-11-28 to 2025-12-05)

_User to log observations here_

---

## Regression Log

_Log any plan quality regressions here with date, page type, issue, and resolution_

## 2025-11-07 Plan Quality Update

### Summary

- Strengthened `.cursor/rules/global.mdc` with structured output requirements (discovery → implementation → validation → risks → handoff) and explicit to-do expectations.
- Updated `docs/ai/cursor-playbook.md` with a mandatory plan template so every Plan Mode session follows the five-phase structure and enumerates tasks.

### Next Validation Step

- Re-run Plan Mode on three representative tasks (comparison page refresh, ShiftOps analyzer tweak, product page update).
- Confirm plans include:
  1. Discovery tasks (research + missing inputs)
  2. Implementation steps with file paths, selectors, tooling
  3. Validation checklist (commands/tools)
  4. Risk + rollback measures
  5. Handoff notes with owners/follow-ups
- Log observations below once runs are complete.

### Pending Test Log

| Date | Scenario               | Result  | Notes |
| ---- | ---------------------- | ------- | ----- |
|      | Comparison page plan   | Pending |       |
|      | ShiftOps analyzer plan | Pending |       |
|      | Product page plan      | Pending |       |