-
-
Notifications
You must be signed in to change notification settings - Fork 34
Cross References
Saros Industries edited this page Jun 28, 2025
·
1 revision
The Cross-Reference System creates intelligent links between different parts of your project, maintaining traceability and relationships across requirements, code, documentation, and issues.
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
[βοΈΟβ:Xα΅’]
Components:
-
βοΈ= Cross-reference indicator -
Οβ= Memory file (Οβ-Οβ) -
Xα΅’= Item index (Rβ, Fβ, etc.)
[βοΈΟβ:Rβ] // Requirement 3 in projectbrief.md
[βοΈΟβ:Pβ] // Pattern 1 in systemPatterns.md
[βοΈΟβ
:Iβ] // Issue 7 in progress.md
Link to a specific item:
This feature implements [βοΈΟβ:Rβ] which requires user authentication.Include context information:
[βοΈΟβ:Rβ|Ξβ:validateUser()]Links requirement Rβ specifically to the validateUser() function.
Reference multiple related items:
This addresses [βοΈΟβ
:Iβ], [βοΈΟβ
:Iβ
], and [βοΈΟβ
:Iβ].Combine with protection markers:
[βοΈΟβ:Pβ|Ξ¨β] - Protected region 3, PROTECTED levelDirect context without memory file:
[Ξβ:AuthService] - Reference to AuthService code
[Ξβ:config.json] - Reference to config file| 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β |
Οβ (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
## 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)## 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).## 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β]
Create two-way links:
// In implementation file
// Implements [βοΈΟβ:Rβ]
// In requirements file
[Rβ] User authentication - Implemented in [βοΈΟβ:auth.service.js]Link through multiple documents:
[βοΈΟβ:Rβ] β [βοΈΟβ:Pβ
] β [βοΈΟβ
:Fβ]
(Requirement β Pattern β Feature)Context-dependent links:
If using SQL: See [βοΈΟβ:Pβ|SQL]
If using NoSQL: See [βοΈΟβ:Pβ|NoSQL]Track changes over time:
Original: [βοΈΟβ:Dβ|v1.0]
Updated: [βοΈΟβ:Dβ|v2.0] per [βοΈΟβ
:Iββ]Add cross-references when creating items:
## [Rββ] New Requirement
Related to [βοΈΟβ:Rβ] and [βοΈΟβ:Rβ]
Addresses [βοΈΟβ
:Iββ
]Always create reverse references:
// In source
Implements [βοΈΟβ:Rβ
]
// In target
[Rβ
] Implemented by [βοΈΟβ:feature.js]Add context to clarify references:
// Less clear
See [βοΈΟβ:Pβ]
// More clear
Following [βοΈΟβ:Pβ] (Repository Pattern) for data accessOrganize multiple references:
### Related Items
- Requirements: [βοΈΟβ:Rβ], [βοΈΟβ:Rβ
], [βοΈΟβ:Rβ]
- Patterns: [βοΈΟβ:Pβ], [βοΈΟβ:Pβ]
- Issues: [βοΈΟβ
:Iβ], [βοΈΟβ
:Iβ]Regularly check reference validity:
## Reference Audit
- [βοΈΟβ:Rβ] β Valid
- [βοΈΟβ:Rβ] β οΈ Deprecated, see [βοΈΟβ:Rββ]
- [βοΈΟβ:Pβ] β Not found/**
* User Authentication Service
* Implements [βοΈΟβ:Rβ] (User Authentication)
* Follows [βοΈΟβ:Pβ
] (JWT Pattern)
* Addresses [βοΈΟβ
:Iββ] (Session timeout issue)
*/
class AuthService {
// Implementation per [βοΈΟβ:Rβ|specifications]
}# API Documentation
## POST /api/auth/login
Implements [βοΈΟβ:Rβ] with security measures from [βοΈΟβ:Dβ].
### Request
Per [βοΈΟβ:Rβ|interface], accepts:
- email: string
- password: stringdescribe('Authentication Tests [βοΈΟβ:Rβ]', () => {
it('should validate credentials per [βοΈΟβ:Rβ|validation]', () => {
// Test implementation
});
it('should handle edge case [βοΈΟβ
:Iββ
]', () => {
// Regression test for issue
});
});git commit -m "feat: implement user auth [βοΈΟβ:Rβ]
- Add JWT authentication per [βοΈΟβ:Pβ
]
- Fix session timeout [βοΈΟβ
:Iββ]
- Update tests for [βοΈΟβ:Cβ]"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#45Check reference integrity:
// Reference validator
function validateReferences() {
const references = findAllReferences();
references.forEach(ref => {
if (!targetExists(ref)) {
console.warn(`Broken reference: ${ref}`);
}
});
}Update references when restructuring:
## Reference Migration
### Old Structure
[βοΈΟβ:Pβ] β Repository Pattern
### New Structure
[βοΈΟβ:Pβ] β DEPRECATED, see [βοΈΟβ:Pββ]
[βοΈΟβ:Pββ] β Updated Repository Pattern (v2)Problem: Target doesn't exist Solution: Regular validation, update or remove
Problem: AβBβCβA loops Solution: Identify hierarchy, break cycles
Problem: Unclear what reference points to Solution: Add context information
Problem: Points to old version Solution: Version tracking, migration notes
## 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)## [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)## [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ββ
]- ποΈ Framework Overview
- π RIPER Modes
- πΎ Memory System
- π£ Symbolic Notation
- π Phase Management
- π‘οΈ Code Protection
- π Context References
- π Permission System
- π Cross-References
- πΎ Backup System
- π Mode Transitions
- πΎ Memory Management
- π‘οΈ Protection Workflow
- π Context Management
- π₯ Team Collaboration
- π£ Symbol Reference
- β¨οΈ Command Reference
- π Mode Reference
- π Permission Matrix
- π API Reference
- π Overview
- π GitHub Integration
- π Web Search
- π Browser Automation
- π³ Docker Integration
-
Installation Issues
- Node.js Version Compatibility
- Package Installation Failures
- Framework Dependencies Missing
- Database Connection Issues
- Port Conflicts
- Environment Setup Issues
- Build and Development Issues
- Framework CLI Issues
-
Configuration & Runtime Issues
- Framework Configuration Problems
- Runtime Performance Issues
- Module Loading and Plugin Issues
- Database and Storage Issues
- Memory Leaks and High Memory Usage
- High CPU Usage
-
BMAD Module Issues
- BMAD Module Initialization Problems
- Business Model Canvas Issues
- Stakeholder Management Issues
- Analytics and Reporting Issues
- Performance Optimization
-
Database & API Issues
- Database Connection Problems
- Database Migration Issues
- API Performance and Reliability Issues
- Data Consistency Issues
- Transaction Problems
-
Performance & Memory Issues
- Memory Management
- CPU Optimization
- Database Query Performance
- Caching Issues
- Resource Monitoring
-
Security & Authentication Issues
- Authentication Failures
- Authorization Problems
- JWT Token Issues
- Session Management
- CORS and Security Headers
- SSL/TLS Configuration
-
Deployment & Production Issues
- Production Deployment Failures
- Environment Configuration
- Load Balancing Issues
- Monitoring and Logging
- Backup and Recovery
When reporting issues, please include:
- Framework version (
npm list @cursoriper/core) - Node.js version (
node --version) - Operating system and version
- Error messages and stack traces
- Steps to reproduce the issue
- Configuration files (sanitized)
- Recent changes or deployments
- Technical Support: support@cursoriper.com
- Documentation: https://docs.cursoriper.com
- Community Forum: https://community.cursoriper.com