Cross References - johnpeterman72/CursorRIPER.sigma GitHub Wiki
๐ Cross-Reference System
The Cross-Reference System creates intelligent links between different parts of your project, maintaining traceability and relationships across requirements, code, documentation, and issues.
๐ฏ What are Cross-References?
Cross-references are smart links that connect related elements:
- Requirements to implementation
- Issues to fixes
- Documentation to code
- Patterns to usage
Without cross-references:
- ๐ซ Lost traceability
- ๐ซ Orphaned documentation
- ๐ซ Unclear relationships
- ๐ซ Difficult navigation
๐ Cross-Reference Notation
Basic Syntax
[โ๏ธฯโ:Xแตข]
Components:
โ๏ธ= Cross-reference indicatorฯโ= Memory file (ฯโ-ฯโ)Xแตข= Item index (Rโ, Fโ, etc.)
Examples
[โ๏ธฯโ:Rโ] // Requirement 3 in projectbrief.md
[โ๏ธฯโ:Pโ] // Pattern 1 in systemPatterns.md
[โ๏ธฯโ
:Iโ] // Issue 7 in progress.md
๐จ Cross-Reference Types
1. Simple References
Link to a specific item:
This feature implements [โ๏ธฯโ:Rโ] which requires user authentication.
2. Context-Enhanced References
Include context information:
[โ๏ธฯโ:Rโ|ฮโ:validateUser()]
Links requirement Rโ specifically to the validateUser() function.
3. Multi-References
Reference multiple related items:
This addresses [โ๏ธฯโ
:Iโ], [โ๏ธฯโ
:Iโ
], and [โ๏ธฯโ
:Iโ].
4. Protection References
Combine with protection markers:
[โ๏ธฯโ:Pโ|ฮจโ] - Protected region 3, PROTECTED level
5. Contextual References
Direct context without memory file:
[ฮโ:AuthService] - Reference to AuthService code
[ฮโ:config.json] - Reference to config file
๐ Index Naming Convention
Standard Prefixes
| Prefix | Meaning | Example |
|---|---|---|
| R | Requirement | Rโ, Rโ, Rโ |
| F | Feature | Fโ, Fโ, Fโ |
| P | Pattern/Protected | Pโ, Pโ, Pโ |
| I | Issue | Iโ, Iโ, Iโ |
| M | Milestone | Mโ, Mโ, Mโ |
| D | Decision | Dโ, Dโ, Dโ |
| T | Task | Tโ, Tโ, Tโ |
| C | Criteria | Cโ, Cโ, Cโ |
Memory File Mapping
ฯโ (projectbrief.md): R, C, constraints
ฯโ (systemPatterns.md): P, D, components
ฯโ (techContext.md): stack, env, deps
ฯโ (activeContext.md): current, next, context
ฯโ
(progress.md): F, I, M, metrics
ฯโ (protection.md): P, history, violations
๐ Cross-Reference Patterns
Requirement Traceability
## Feature: User Authentication
Implements [โ๏ธฯโ:Rโ] (User must authenticate before accessing protected resources)
### Implementation Details
- Login endpoint: [โ๏ธฯโ:Rโ|ฮโ:loginUser()]
- Session management: [โ๏ธฯโ:Rโ|ฮโ:SessionManager]
- Security: [โ๏ธฯโ:Pโ
] (JWT pattern)
Issue Resolution
## Bug Fix: Login Timeout
Fixes [โ๏ธฯโ
:Iโโ] (Users randomly logged out)
### Root Cause
Session timeout was hardcoded [โ๏ธฯโ:config] instead of using environment variable.
### Solution
Implemented configurable timeout following [โ๏ธฯโ:Dโ] (configuration pattern).
Pattern Implementation
## Repository Pattern Implementation
Following [โ๏ธฯโ:Pโ] (Repository Pattern):
```javascript
// Implementation of [โ๏ธฯโ:Pโ]
class UserRepository {
// Methods as specified in [โ๏ธฯโ:Pโ|components]
}
### Decision Documentation
```markdown
## Architecture Decision
Per [โ๏ธฯโ:Dโ] (Microservices over Monolith):
### Rationale
- Scalability requirements [โ๏ธฯโ:Rโ]
- Team structure [โ๏ธฯโ:constraints]
- Performance goals [โ๏ธฯโ:Cโ]
๐ฏ Advanced Cross-References
Bidirectional References
Create two-way links:
// In implementation file
// Implements [โ๏ธฯโ:Rโ]
// In requirements file
[Rโ] User authentication - Implemented in [โ๏ธฯโ:auth.service.js]
Chain References
Link through multiple documents:
[โ๏ธฯโ:Rโ] โ [โ๏ธฯโ:Pโ
] โ [โ๏ธฯโ
:Fโ]
(Requirement โ Pattern โ Feature)
Conditional References
Context-dependent links:
If using SQL: See [โ๏ธฯโ:Pโ|SQL]
If using NoSQL: See [โ๏ธฯโ:Pโ|NoSQL]
Version References
Track changes over time:
Original: [โ๏ธฯโ:Dโ|v1.0]
Updated: [โ๏ธฯโ:Dโ|v2.0] per [โ๏ธฯโ
:Iโโ]
๐ก Cross-Reference Best Practices
1. Reference at Creation
Add cross-references when creating items:
## [Rโโ] New Requirement
Related to [โ๏ธฯโ:Rโ] and [โ๏ธฯโ:Rโ]
Addresses [โ๏ธฯโ
:Iโโ
]
2. Maintain Bidirectionality
Always create reverse references:
// In source
Implements [โ๏ธฯโ:Rโ
]
// In target
[Rโ
] Implemented by [โ๏ธฯโ:feature.js]
3. Use Descriptive Context
Add context to clarify references:
// Less clear
See [โ๏ธฯโ:Pโ]
// More clear
Following [โ๏ธฯโ:Pโ] (Repository Pattern) for data access
4. Group Related References
Organize multiple references:
### Related Items
- Requirements: [โ๏ธฯโ:Rโ], [โ๏ธฯโ:Rโ
], [โ๏ธฯโ:Rโ]
- Patterns: [โ๏ธฯโ:Pโ], [โ๏ธฯโ:Pโ]
- Issues: [โ๏ธฯโ
:Iโ], [โ๏ธฯโ
:Iโ]
5. Verify References
Regularly check reference validity:
## Reference Audit
- [โ๏ธฯโ:Rโ] โ Valid
- [โ๏ธฯโ:Rโ] โ ๏ธ Deprecated, see [โ๏ธฯโ:Rโโ]
- [โ๏ธฯโ:Pโ] โ Not found
๐ Cross-Reference Usage
In Code Comments
/**
* User Authentication Service
* Implements [โ๏ธฯโ:Rโ] (User Authentication)
* Follows [โ๏ธฯโ:Pโ
] (JWT Pattern)
* Addresses [โ๏ธฯโ
:Iโโ] (Session timeout issue)
*/
class AuthService {
// Implementation per [โ๏ธฯโ:Rโ|specifications]
}
In Documentation
# API Documentation
## POST /api/auth/login
Implements [โ๏ธฯโ:Rโ] with security measures from [โ๏ธฯโ:Dโ].
### Request
Per [โ๏ธฯโ:Rโ|interface], accepts:
- email: string
- password: string
In Test Files
describe('Authentication Tests [โ๏ธฯโ:Rโ]', () => {
it('should validate credentials per [โ๏ธฯโ:Rโ|validation]', () => {
// Test implementation
});
it('should handle edge case [โ๏ธฯโ
:Iโโ
]', () => {
// Regression test for issue
});
});
In Commit Messages
git commit -m "feat: implement user auth [โ๏ธฯโ:Rโ]
- Add JWT authentication per [โ๏ธฯโ:Pโ
]
- Fix session timeout [โ๏ธฯโ
:Iโโ]
- Update tests for [โ๏ธฯโ:Cโ]"
๐ Cross-Reference Management
Reference Tracking
Maintain reference index:
## Cross-Reference Index
### Requirements โ Implementation
- [Rโ] โ auth.service.js, login.component.ts
- [Rโ] โ user.model.js, validation.js
- [Rโ] โ jwt.utils.js, middleware/auth.js
### Issues โ Fixes
- [Iโ] โ commit:abc123, PR#42
- [Iโ] โ commit:def456, PR#45
Reference Validation
Check reference integrity:
// Reference validator
function validateReferences() {
const references = findAllReferences();
references.forEach(ref => {
if (!targetExists(ref)) {
console.warn(`Broken reference: ${ref}`);
}
});
}
Reference Refactoring
Update references when restructuring:
## Reference Migration
### Old Structure
[โ๏ธฯโ:Pโ] โ Repository Pattern
### New Structure
[โ๏ธฯโ:Pโ] โ DEPRECATED, see [โ๏ธฯโ:Pโโ]
[โ๏ธฯโ:Pโโ] โ Updated Repository Pattern (v2)
๐จ Common Cross-Reference Issues
Broken References
Problem: Target doesn't exist Solution: Regular validation, update or remove
Circular References
Problem: AโBโCโA loops Solution: Identify hierarchy, break cycles
Ambiguous References
Problem: Unclear what reference points to Solution: Add context information
Outdated References
Problem: Points to old version Solution: Version tracking, migration notes
๐ Cross-Reference Examples
Example 1: Feature Development
## Feature: Payment Processing
### Requirements
Implements [โ๏ธฯโ:Rโโ
] (Process payments)
Related to [โ๏ธฯโ:Rโโ] (Payment history)
### Design
Following patterns:
- [โ๏ธฯโ:Pโ] (Strategy pattern for payment methods)
- [โ๏ธฯโ:Pโ] (Observer pattern for notifications)
### Implementation
- Service: [ฮโ:PaymentService]
- Controller: [ฮโ:PaymentController]
- Tests: [ฮโ:tests/payment.test.js]
### Issues Addressed
- [โ๏ธฯโ
:Iโโ] (Timeout on large payments)
- [โ๏ธฯโ
:Iโโ
] (Currency conversion errors)
Example 2: Bug Report
## [Iโโ
] Login fails with special characters
### Description
Users with @ in password cannot login
### Related
- Requirement: [โ๏ธฯโ:Rโ|validation]
- Pattern deviation: [โ๏ธฯโ:Pโ
|security]
- Similar issues: [โ๏ธฯโ
:Iโโ], [โ๏ธฯโ
:Iโโ]
### Fix
See PR#123 implementing [โ๏ธฯโ:Dโโ
] (input sanitization)
Example 3: Architecture Decision
## [Dโโ] Switch to Event-Driven Architecture
### Rationale
- Performance requirement [โ๏ธฯโ:Cโ] not met
- Scalability needs [โ๏ธฯโ:Rโโ] increasing
- Current architecture [โ๏ธฯโ:Dโ] limitations
### Impact
- Deprecates [โ๏ธฯโ:Pโ-Pโ
]
- Introduces [โ๏ธฯโ:Pโโ-Pโโ
]
- Addresses [โ๏ธฯโ
:Iโโ], [โ๏ธฯโ
:Iโโ], [โ๏ธฯโ
:Iโโ
]