cursor-rules-review

# Cursor Rules Review

## Quick Start

**5-Gate Review Process:**

```
Rule File (.mdc)
    ↓
Gate 1: Frontmatter Review
    ↓ PASS
Gate 2: Glob Patterns Review
    ↓ PASS
Gate 3: Content Quality Review
    ↓ PASS
Gate 4: File Length Review
    ↓ PASS
Gate 5: Functionality Review
    ↓ PASS
✅ APPROVED
```

**Severity Levels:**

- **BLOCKER** - Must fix before merge (prevents rule from working)
- **CRITICAL** - Must fix before production (causes issues)
- **MAJOR** - Should fix (impacts quality significantly)
- **MINOR** - Nice to have (improvements)

---

## When to Load Additional References

The 5-gate review process below provides core checks. Load these references for detailed examples and checklists:

**For detailed examples of good and bad patterns:**

```
Read `~/.claude/skills/cursor-rules-review/references/EXAMPLES.md`
```

Use when: You need concrete examples of violations, want to see before/after comparisons, or need reference patterns

**For copy-paste review checklist:**

```
Read `~/.claude/skills/cursor-rules-review/references/CHECKLIST.md`
```

Use when: Performing systematic review, want a comprehensive checklist, or need to document findings

**For test scenarios and edge cases:**

```
Read `~/.claude/skills/cursor-rules-review/references/test-scenarios.md`
```

Use when: Testing rules, validating fixes, or handling complex edge cases

---

## 5-Gate Review Process (Quick Summary)

### Gate 1: Frontmatter Review

- **YAML Syntax**: Valid YAML with proper `---` delimiters (BLOCKER if invalid)
- **Required Fields**: `description` field present and under 1024 chars (BLOCKER if missing)
- **Description Quality**: Specific, third-person, explains WHAT and WHEN (MAJOR if vague)
- **Triggering Config**: Appropriate use of `alwaysApply`, `globs`, or manual-only (CRITICAL if incorrect)

### Gate 2: Glob Patterns Review

- **Specificity**: Patterns match intended files only, not overly broad (CRITICAL if too broad)
- **Performance**: Efficient patterns, not excessive count (MAJOR if >10 patterns)
- **Correctness**: Patterns work with `find` command, correct syntax (BLOCKER if broken)

### Gate 3: Content Quality Review

- **Single Responsibility**: Focused on one concern, split if multiple topics (MAJOR if mixed)
- **Organization**: Clear structure, logical flow, no redundancy (MAJOR if poor)
- **Examples**: Realistic good/bad patterns with explanations (MAJOR if missing)
- **Cross-References**: Valid `@` syntax, referenced rules exist (CRITICAL if broken)

### Gate 4: File Length Review

- **Recommended**: <300 lines optimal, 300-500 good, 500-750 acceptable
- **Action Required**: Split if >750 lines into base/advanced/examples (MAJOR if >1000)

### Gate 5: Functionality Review

- **Triggering Test**: Create test files, verify correct triggering (BLOCKER if doesn't trigger)
- **Cross-Reference Validation**: Verify referenced files exist (CRITICAL if broken)
- **Maintainability**: Clear, follows conventions, documented (MINOR if poor)

**For detailed checks, examples, and criteria for each gate:**

```
Read `~/.claude/skills/cursor-rules-review/references/GATE-REVIEWS.md`
```

Use when: Performing comprehensive review, need detailed validation criteria, or checking specific gate requirements

---

## Review Output Format

**Report Structure**: Summary table with gate-by-gate status, issues grouped by severity (BLOCKER → CRITICAL → MAJOR → MINOR), specific fixes with line numbers, and prioritized recommendations.

**For complete report template with examples:**

```
Read `~/.claude/skills/cursor-rules-review/references/REPORT-FORMAT.md`
```

Use when: Documenting review findings, creating comprehensive reports, or presenting results to team

---

## Best Practices

### 1. Start with Frontmatter

Always validate frontmatter first - if it's broken, nothing else matters.

### 2. Test Triggering Early

Create test files and verify the rule triggers as expected.

### 3. Use Consistent Severity

Apply severity levels consistently across reviews.

### 4. Provide Actionable Fixes

Every issue should have a clear fix recommendation.

### 5. Re-Review After Fixes

Always run review again after fixes to confirm resolution.

---

## Common Issues (Quick Reference)

### Rule Not Triggering

- **Symptoms**: Rule doesn't appear when expected, glob patterns look correct
- **Fix**: Test glob with `find`, verify YAML syntax, check file location, restart Cursor

### Context Bloat

- **Symptoms**: Too much context loaded, slow performance, irrelevant info in responses
- **Fix**: Make globs more specific, minimize `alwaysApply: true`, split large rules

### Broken Cross-References

- **Symptoms**: `@referenced-rule` doesn't load, errors in Cursor logs
- **Fix**: Verify filename case-sensitivity, ensure file exists, use correct `@filename` syntax

**For detailed troubleshooting with debug commands and comprehensive solutions:**

```
Read `~/.claude/skills/cursor-rules-review/references/TROUBLESHOOTING.md`
```

Use when: Debugging specific issues, need detailed diagnostic steps, or handling complex problems

---

## Quick Validation Commands

```bash
# Check frontmatter
head -n 10 .cursor/rules/rule-name.mdc

# Check file length
wc -l .cursor/rules/rule-name.mdc

# Test glob patterns
find . -path "**/Chart.yaml"

# Verify cross-references
grep "@" .cursor/rules/rule-name.mdc
ls .cursor/rules/referenced-rule.mdc

# For complete checklist, read references/CHECKLIST.md
```

---

## Related Skills

- **cursor-rules-writing**: Create new Cursor rules following best practices
- **skill-review**: Review Claude Code skills (different from Cursor rules)

---

**This skill should be reviewed quarterly for updates to align with latest Cursor IDE features.**