# Rule-Documentation Cross-Reference Validation

**Last Updated:** 2026-01-20

Validation of bidirectional cross-references between Cursor rules and documentation files.

## Cross-Reference Status

### Rule → Documentation References

**Status:** ✅ Complete

- All 63 rules have `relatedDocs` arrays
- Most rules reference relevant documentation
- References validated for existence

**Validation:**
- Run `python3 scripts/validate-cursor-rules.py` to check cross-references
- Check `METADATA_INDEX.json` for complete list

### Documentation → Rule References

**Status:** ⚠️ Partial

**Files with Rule References:**
- `docs/ai/RULE_TO_DOC_MAPPING.md` - Complete bidirectional mapping ✅
- `docs/DOCUMENTATION_STANDARDS.md` - References key rules ✅
- `docs/guides/comparison-pages/COMPARISON_PAGES_GUIDE.md` - References rules ✅
- `docs/DOCUMENTATION_TEMPLATES.md` - References rules ✅

**Files That Should Reference Rules:**
- Guide files should reference relevant rules
- System documentation should reference system-specific rules
- API documentation should reference API rules

## Validation Process

### Automated Validation

**Script:** `scripts/validate-cursor-rules.py`

**Checks:**
- Rule `relatedDocs` paths exist
- Rule `relatedRules` references exist
- Documentation files reference rules (manual review)

### Manual Review Needed

**Documentation Files to Review:**
- Guide files in `docs/guides/`
- System documentation in `docs/systems/`
- API documentation in `docs/reference/api/`

**Action:** Add "Related Cursor Rules" sections to key documentation files.

## Best Practices

### Rule → Documentation

**Pattern:**
```yaml
relatedDocs:
  - docs/path/to/relevant-doc.md
  - docs/another/relevant-doc.md
```

**Guidelines:**
- Reference relevant documentation (not all docs)
- Use relative paths from `docs/`
- Keep references up-to-date

### Documentation → Rules

**Pattern:**
```markdown
## Related Cursor Rules

- **[rule-name.mdc](.cursor/rules/rule-name.mdc)** - Description
- **[another-rule.mdc](.cursor/rules/another-rule.mdc)** - Description
```

**Guidelines:**
- Add "Related Cursor Rules" section to key docs
- Reference rules that apply to the documentation topic
- Use relative paths from `docs/` to `.cursor/rules/`

## Related Documentation

- **[RULE_TO_DOC_MAPPING.md](ai/RULE_TO_DOC_MAPPING.md)** - Complete bidirectional mapping
- **[DOCUMENTATION_STANDARDS.md](DOCUMENTATION_STANDARDS.md)** - Documentation standards
- **[validate-cursor-rules.py](../../scripts/validate-cursor-rules.py)** - Validation script