# Cursor Rules Optimization Recommendations

**Last Updated:** 2026-01-09

Analysis and recommendations for optimizing Cursor rule organization based on file sizes and best practices.

## Current State Analysis

### Rule File Sizes

**Average file size:** 430 lines per rule file

**Large Rules (>500 lines - Consider Splitting):**
- `product-updates.mdc`: 1,294 lines ⚠️
- `tools-pages-reference.mdc`: 1,103 lines ⚠️
- `excel-template-generator.mdc`: 892 lines ⚠️
- `comparison-pages-core.mdc`: 890 lines ⚠️

**Medium Rules (300-500 lines - Acceptable):**
- `templates-pages.mdc`: 770 lines
- `testimonials.mdc`: 747 lines
- `global.mdc`: 589 lines
- `tools-pages-core-design.mdc`: 539 lines
- `shared-patterns.mdc`: 520 lines

**Small Rules (<300 lines - Good):**
- All other rules are well-sized

## Recommendations

### High Priority: Split Large Rules

#### 1. product-updates.mdc (1,294 lines)

**Recommendation:** Split into:
- `product-updates-core.mdc` - Core CMS patterns, data structure
- `product-updates-admin.mdc` - Admin panel patterns, UI/UX
- `product-updates-content.mdc` - Content patterns, markdown processing

**Rationale:** 
- Significantly exceeds 500-line recommendation
- Contains distinct concerns (CMS, admin, content)
- Would improve maintainability

#### 2. tools-pages-reference.mdc (1,103 lines)

**Recommendation:** Split into:
- `tools-pages-reference-core.mdc` - JavaScript extraction, troubleshooting
- `tools-pages-reference-edge-cases.mdc` - Edge cases, common pitfalls
- `tools-pages-reference-examples.mdc` - Code examples, patterns

**Rationale:**
- Exceeds 500-line recommendation
- Contains reference material that could be better organized
- Would improve discoverability

#### 3. excel-template-generator.mdc (892 lines)

**Recommendation:** Consider splitting if it grows further:
- Current size is acceptable but close to limit
- Monitor for future growth
- Split if it exceeds 1,000 lines

#### 4. comparison-pages-core.mdc (890 lines)

**Recommendation:** Already split into core/content, but consider:
- Current split is working well
- Monitor for further growth
- Consider extracting schema patterns if it grows

### Medium Priority: Review Rule Relationships

**Completed:** Added `relatedRules` fields to:
- Comparison pages (core ↔ content)
- Tools pages (design ↔ validation ↔ schema ↔ etc.)
- ShiftOps (frontend-core ↔ frontend-qa ↔ backend)
- API endpoints (core ↔ security)
- Templates (pages ↔ cta)
- Pillar pages (pillar ↔ content-clusters)

**Next Steps:**
- Review if additional relationships should be documented
- Consider adding `relatedDocs` fields where helpful

### Low Priority: Consolidation Opportunities

**Review small related rules:**
- `tools-pages-patterns-export.mdc` (small) - Consider if it should merge with core
- `tools-pages-patterns-gated.mdc` (small) - Consider if it should merge with core
- `templates-cta.mdc` (small) - Keep separate (distinct concern)

**Decision:** Keep separate for now - they represent distinct concerns even if small.

## Implementation Plan

### Phase 1: Split Large Rules (High Priority)

1. **Split product-updates.mdc**
   - Create `product-updates-core.mdc`
   - Create `product-updates-admin.mdc`
   - Create `product-updates-content.mdc`
   - Update globs appropriately
   - Add relatedRules fields
   - Test rule discovery

2. **Split tools-pages-reference.mdc**
   - Create `tools-pages-reference-core.mdc`
   - Create `tools-pages-reference-edge-cases.mdc`
   - Create `tools-pages-reference-examples.mdc`
   - Update globs appropriately
   - Add relatedRules fields
   - Test rule discovery

### Phase 2: Monitor and Maintain

1. **Set up monitoring**
   - Add file size check to validation scripts
   - Alert when rules exceed 500 lines
   - Track rule growth over time

2. **Regular reviews**
   - Quarterly review of rule sizes
   - Assess if splits are needed
   - Review rule relationships

## Best Practices Going Forward

### Rule Size Guidelines

- **Target:** <500 lines per rule
- **Action required:** >1,000 lines (split immediately)
- **Monitor:** 500-1,000 lines (consider splitting)

### When to Split Rules

1. **Rule exceeds 1,000 lines** → Split immediately
2. **Rule exceeds 500 lines** → Consider splitting if:
   - Contains distinct concerns
   - Would improve maintainability
   - Would improve discoverability
3. **Rule has multiple distinct sections** → Consider splitting even if <500 lines

### When to Merge Rules

1. **Multiple small rules (<100 lines)** → Consider merging if:
   - They're always used together
   - They represent the same concern
   - Merging improves clarity
2. **Rules with overlapping content** → Merge to reduce redundancy

### Splitting Strategy

When splitting a rule:

1. **Identify distinct concerns** - What are the main sections?
2. **Create new rule files** - One per distinct concern
3. **Update globs** - Ensure patterns still match correctly
4. **Add relatedRules** - Link split rules together
5. **Update documentation** - Reference new structure
6. **Test discovery** - Verify rules still apply correctly
7. **Regenerate index** - Update METADATA_INDEX.json

## Monitoring Script

Add to validation scripts:

```python
# Check rule file sizes
for rule_file in rule_files:
    line_count = sum(1 for _ in open(rule_file))
    if line_count > 1000:
        warnings.append(f"{rule_file.name} exceeds 1000 lines ({line_count})")
    elif line_count > 500:
        warnings.append(f"{rule_file.name} exceeds 500 lines ({line_count})")
```

## Success Metrics

- ✅ No rules exceed 1,000 lines
- ✅ Average rule size <500 lines
- ✅ Large rules split appropriately
- ✅ Rule relationships documented
- ✅ Rule discovery still works after splits

## Related Documentation

- [Rule Maintenance Guide](CURSOR_RULES_MAINTENANCE.md) - How to maintain rules
- [Best Practices](CURSOR_RULES_BEST_PRACTICES.md) - Rule organization guidelines
- [Improvement Summary](CURSOR_RULES_IMPROVEMENT_SUMMARY.md) - What was improved