diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 0000000..ae4db58 --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,306 @@ +# .cursor Rules Organization + +This directory contains all the rules and guidelines for AI assistants working +with the TimeSafari project. + +## Directory Structure + +### **`core/`** - Core Principles and Context + +Core rules that apply to all AI interactions and provide fundamental context. + +- **`base_context.mdc`** - Human competence first principles and interaction guidelines +- **`harbor_pilot_universal.mdc`** - Technical guide creation and investigation rules +- **`less_complex.mdc`** - Minimalist solution principle and complexity guidelines + +### **`development/`** - Development Practices and Standards + +Rules for software development, coding standards, and development workflows. + +- **`software_development.mdc`** - Core development principles and evidence requirements +- **`type_safety_guide.mdc`** - TypeScript type safety guidelines and best practices +- **`development_guide.mdc`** - Development environment setup and standards +- **`logging_standards.mdc`** - Logging implementation standards and rules +- **`logging_migration.mdc`** - Migration from console.* to structured logging +- **`time.mdc`** - Time handling principles and UTC standards +- **`time_examples.mdc`** - Practical time implementation examples +- **`time_implementation.mdc`** - Detailed time implementation guidelines +- **`realistic_time_estimation.mdc`** - Time estimation framework and principles +- **`planning_examples.mdc`** - Planning examples and best practices +- **`complexity_assessment.mdc`** - Complexity evaluation and assessment +- **`dependency_management.mdc`** - Dependency management and version control +- **`asset_configuration.mdc`** - Asset configuration and build integration +- **`research_diagnostic.mdc`** - Research and investigation workflows +- **`investigation_report_example.mdc`** - Investigation report templates and examples +- **`historical_comment_management.mdc`** - Historical comment transformation rules +- **`historical_comment_patterns.mdc`** - Comment transformation patterns and examples + +### **`architecture/`** - Architecture and Design Patterns + +Rules for architectural decisions, patterns, and system design. + +- **`build_architecture_guard.mdc`** - Build system protection and change levels +- **`build_validation.mdc`** - Build validation procedures and testing +- **`build_testing.mdc`** - Build testing requirements and feedback collection + +### **`app/`** - Application-Specific Rules + +Rules specific to the TimeSafari application and its architecture. + +- **`timesafari.mdc`** - Core application context and principles +- **`timesafari_platforms.mdc`** - Platform-specific implementation guidelines +- **`timesafari_development.mdc`** - TimeSafari development workflow +- **`architectural_decision_record.mdc`** - ADR creation and management +- **`architectural_implementation.mdc`** - Architecture implementation guidelines +- **`architectural_patterns.mdc`** - Architectural patterns and examples +- **`architectural_examples.mdc`** - Architecture examples and testing + +### **`database/`** - Database and Data Management + +Rules for database operations, migrations, and data handling. + +- **`absurd-sql.mdc`** - Absurd SQL implementation and worker thread setup +- **`legacy_dexie.mdc`** - Legacy Dexie migration guidelines + +### **`workflow/`** - Process and Workflow Management + +Rules for development workflows, version control, and process management. + +- **`version_control.mdc`** - Version control principles and commit guidelines +- **`version_sync.mdc`** - Version synchronization and changelog management +- **`commit_messages.mdc`** - Commit message format and conventions + +### **`features/** - Feature-Specific Implementations + +Rules for implementing specific features across platforms. + +- **`camera-implementation.mdc`** - Camera feature implementation overview +- **`camera_technical.mdc`** - Technical camera implementation details +- **`camera_platforms.mdc`** - Platform-specific camera implementation + +### **`docs/`** - Documentation Standards + +Rules for creating and maintaining documentation. + +- **`markdown_core.mdc`** - Core markdown formatting standards +- **`markdown_templates.mdc`** - Document templates and examples +- **`markdown_workflow.mdc`** - Markdown validation and workflow +- **`documentation.mdc`** - Documentation generation principles +- **`meta_rule_usage_guide.md`** - How to use meta-rules in practice + +### **`templates/`** - Templates and Examples + +Template files and examples for various documentation types. + +- **`adr_template.mdc`** - Architectural Decision Record template + +### **Meta-Rules** - Workflow Bundling + +High-level meta-rules that bundle related sub-rules for specific workflows. + +- **`meta_core_always_on.mdc`** - Core rules that apply to every single prompt +- **`meta_documentation.mdc`** - Documentation writing and education workflow +- **`meta_feature_planning.mdc`** - Feature planning workflow bundling +- **`meta_bug_diagnosis.mdc`** - Bug investigation workflow bundling +- **`meta_bug_fixing.mdc`** - Bug fix implementation workflow bundling +- **`meta_feature_implementation.mdc`** - Feature implementation workflow bundling +- **`meta_research.mdc`** - Investigation and research workflow bundling + +### **Workflow State Management** + +The project uses a sophisticated workflow state management system to ensure systematic development processes and maintain code quality across all phases of development. + +#### **Workflow State System** + +The workflow state is managed through `.cursor/rules/.workflow_state.json` and enforces different modes with specific constraints. The system automatically tracks workflow progression and maintains a complete history of mode transitions. + +**Available Modes**: +- **`diagnosis`** - Investigation and analysis phase (read-only) +- **`fixing`** - Implementation and bug fixing phase (full access) +- **`planning`** - Design and architecture phase (design only) +- **`research`** - Investigation and research phase (investigation only) +- **`documentation`** - Documentation writing phase (writing only) + +**Mode Constraints**: +```json +{ + "diagnosis": { + "mode": "read_only", + "forbidden": ["modify", "create", "build", "commit"], + "allowed": ["read", "search", "analyze", "document"] + }, + "fixing": { + "mode": "implementation", + "forbidden": [], + "allowed": ["modify", "create", "build", "commit", "test"] + } +} +``` + +**Workflow History Tracking**: + +The system automatically maintains a `workflowHistory` array that records all mode transitions and meta-rule invocations: + +```json +{ + "workflowHistory": [ + { + "mode": "research", + "invoked": "meta_core_always_on.mdc", + "timestamp": "2025-08-25T02:14:37Z" + }, + { + "mode": "diagnosis", + "invoked": "meta_bug_diagnosis.mdc", + "timestamp": "2025-08-25T02:14:37Z" + } + ] +} +``` + +**History Entry Format**: +- **`mode`**: The workflow mode that was activated +- **`invoked`**: The specific meta-rule that triggered the mode change +- **`timestamp`**: UTC timestamp when the mode transition occurred + +**History Purpose**: +- **Workflow Continuity**: Track progression through development phases +- **Meta-Rule Usage**: Monitor which rules are invoked and when +- **Temporal Context**: Maintain chronological order of workflow changes +- **State Persistence**: Preserve workflow history across development sessions +- **Debugging Support**: Help diagnose workflow state issues +- **Process Analysis**: Understand development patterns and meta-rule effectiveness + +#### **Commit Override System** + +The workflow includes a flexible commit override mechanism that allows commits on demand while maintaining workflow integrity: + +```json +{ + "overrides": { + "commit": { + "allowed": true, + "requires_override": true, + "override_reason": "user_requested" + } + } +} +``` + +**Override Benefits**: +- ✅ **Investigation Commits**: Document findings during diagnosis phases +- ✅ **Work-in-Progress**: Commit partial solutions during complex investigations +- ✅ **Emergency Fixes**: Commit critical fixes without mode transitions +- ✅ **Flexible Workflow**: Maintain systematic approach while accommodating real needs + +**Override Limitations**: +- ❌ **Does NOT bypass**: Version control rules, commit message standards, or security requirements +- ❌ **Does NOT bypass**: Code quality standards, testing requirements, or documentation requirements + +#### **Workflow Enforcement** + +The system automatically enforces workflow constraints through the core always-on rules: + +**Before Every Interaction**: +1. **Read current workflow state** from `.cursor/rules/.workflow_state.json` +2. **Identify current mode** and its constraints +3. **Validate user request** against current mode constraints +4. **Enforce constraints** before generating response +5. **Guide model behavior** based on current mode + +**Mode-Specific Enforcement**: +- **Diagnosis Mode**: Blocks modification, creation, building, and commits +- **Fixing Mode**: Allows full implementation and testing capabilities +- **Planning Mode**: Focuses on design and architecture, blocks implementation +- **Research Mode**: Enables investigation and analysis, blocks modification +- **Documentation Mode**: Allows writing and editing, blocks implementation + +#### **Workflow Transitions** + +To change workflow modes, invoke the appropriate meta-rule: + +```bash +# Switch to bug fixing mode +@meta_bug_fixing.mdc + +# Switch to feature planning mode +@meta_feature_planning.mdc + +# Switch to documentation mode +@meta_documentation.mdc +``` + +**Transition Requirements**: +- **Mode Changes**: Require explicit meta-rule invocation +- **State Updates**: Automatically update workflow state file +- **Constraint Enforcement**: Immediately apply new mode constraints +- **History Tracking**: Automatically maintained in `workflowHistory` array +- **Timestamp Recording**: Each transition recorded with UTC timestamp + +#### **Integration with Development Process** + +The workflow system integrates seamlessly with existing development practices: + +**Version Control**: +- All commits must follow TimeSafari commit message standards +- Security audit checklists are enforced regardless of workflow mode +- Documentation updates are required for substantial changes + +**Quality Assurance**: +- Code quality standards (PEP8, TypeScript, etc.) are always enforced +- Testing requirements apply to all implementation work +- Documentation standards are maintained across all phases + +**Build System**: +- Build Architecture Guard protects critical build files +- Platform-specific build processes respect workflow constraints +- Asset generation follows established patterns + +**Migration Context**: +- Database migration work respects investigation vs. implementation phases +- Component migration progress is tracked through workflow states + +## Usage Guidelines + +1. **Always-On Rules**: Start with `meta_core_always_on.mdc` for every + single prompt +2. **Core Rules**: Always apply rules from `core/` directory +3. **Context-Specific**: Use rules from appropriate subdirectories based on + your task +4. **Meta-Rules**: Use workflow-specific meta-rules for specialized tasks + - **Documentation**: Use `meta_documentation.mdc` for all documentation work + - **Getting Started**: See `docs/meta_rule_usage_guide.md` for comprehensive usage instructions +5. **Cross-References**: All files contain updated cross-references to + reflect the new structure +6. **Validation**: All files pass markdown validation and maintain + consistent formatting + +## Benefits of New Organization + +1. **Logical grouping** - Related rules are now co-located +2. **Easier navigation** - Developers can quickly find relevant rules +3. **Better maintainability** - Clear separation of concerns +4. **Scalable structure** - Easy to add new rules in appropriate categories +5. **Consistent cross-references** - All file links updated and working +6. **Workflow bundling** - Meta-rules provide high-level workflow guidance +7. **Feedback integration** - Built-in feedback mechanisms for continuous improvement +8. **Educational focus** - Documentation emphasizes human competence over technical description + +## File Naming Convention + +- **Lowercase with underscores**: `file_name.mdc` +- **Descriptive names**: Names clearly indicate the rule's purpose +- **Consistent extensions**: All files use `.mdc` extension + +## Maintenance + +- **Cross-references**: Update when moving files between directories +- **Markdown validation**: Run `npm run markdown:check` after any changes +- **Organization**: Keep related rules in appropriate subdirectories +- **Documentation**: Update this README when adding new rules or directories + +--- + +**Status**: Active organization structure +**Last Updated**: 2025-08-21 +**Maintainer**: Development team diff --git a/.cursor/rules/always_on_rules.mdc b/.cursor/rules/always_on_rules.mdc new file mode 100644 index 0000000..33128c1 --- /dev/null +++ b/.cursor/rules/always_on_rules.mdc @@ -0,0 +1,192 @@ +# Meta-Rule: Core Always-On Rules + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Core rules for every prompt + +## Purpose + +This meta-rule bundles the core rules that should be applied to **every single +prompt** because they define fundamental behaviors, principles, and context +that are essential for all AI interactions. + +## When to Use + +**ALWAYS** - These rules apply to every single prompt, regardless of the task +or context. They form the foundation for all AI assistant behavior. + +## Bundled Rules + +### **Core Human Competence Principles** + +- **`core/base_context.mdc`** - Human competence first principles, interaction + guidelines, and output contract requirements +- **`core/less_complex.mdc`** - Minimalist solution principle and complexity + guidelines + +### **Time & Context Standards** + +- **`development/time.mdc`** - Time handling principles and UTC standards +- **`development/time_examples.mdc`** - Practical time implementation examples +- **`development/time_implementation.mdc`** - Detailed time implementation + guidelines + +### **Version Control & Process** + +- **`workflow/version_control.mdc`** - Version control principles and commit + guidelines +- **`workflow/commit_messages.mdc`** - Commit message format and conventions + +### **Application Context** + +- **`app/timesafari.mdc`** - Core TimeSafari application context and + development principles +- **`app/timesafari_development.mdc`** - TimeSafari-specific development + workflow and quality standards + +## Why These Rules Are Always-On + +### **Base Context** + +- **Human Competence First**: Every interaction must increase human competence +- **Output Contract**: All responses must follow the required structure +- **Competence Hooks**: Learning and collaboration must be built into every response + +### **Time Standards** + +- **UTC Consistency**: All timestamps must use UTC for system operations +- **Evidence Collection**: Time context is essential for debugging and investigation +- **Cross-Platform**: Time handling affects all platforms and features + +### **Version Control** + +- **Commit Standards**: Every code change must follow commit message conventions +- **Process Consistency**: Version control affects all development work +- **Team Collaboration**: Commit standards enable effective team communication + +### **Application Context** + +- **Platform Awareness**: Every task must consider web/mobile/desktop platforms +- **Architecture Principles**: All work must follow TimeSafari patterns +- **Development Standards**: Quality and testing requirements apply to all work + +## Application Priority + +### **Primary (Apply First)** + +1. **Base Context** - Human competence and output contract +2. **Time Standards** - UTC and timestamp requirements +3. **Application Context** - TimeSafari principles and platforms + +### **Secondary (Apply as Needed)** + +1. **Version Control** - When making code changes +2. **Complexity Guidelines** - When evaluating solution approaches + +## Integration with Other Meta-Rules + +### **Feature Planning** + +- Base context ensures human competence focus +- Time standards inform planning and estimation +- Application context drives platform considerations + +### **Bug Diagnosis** + +- Base context ensures systematic investigation +- Time standards enable proper evidence collection +- Application context provides system understanding + +### **Bug Fixing** + +- Base context ensures quality implementation +- Time standards maintain logging consistency +- Application context guides testing strategy + +### **Feature Implementation** + +- Base context ensures proper development approach +- Time standards maintain system consistency +- Application context drives architecture decisions + +## Success Criteria + +- [ ] **Base context applied** to every single prompt +- [ ] **Time standards followed** for all timestamps and logging +- [ ] **Version control standards** applied to all code changes +- [ ] **Application context considered** for all platform work +- [ ] **Human competence focus** maintained in all interactions +- [ ] **Output contract structure** followed in all responses + +## Common Pitfalls + +- **Don't skip base context** - loses human competence focus +- **Don't ignore time standards** - creates inconsistent timestamps +- **Don't forget application context** - misses platform considerations +- **Don't skip version control** - creates inconsistent commit history +- **Don't lose competence focus** - reduces learning value + +## Feedback & Improvement + +### **Rule Effectiveness Ratings (1-5 scale)** + +- **Base Context**: ___/5 - Comments: _______________ +- **Time Standards**: ___/5 - Comments: _______________ +- **Version Control**: ___/5 - Comments: _______________ +- **Application Context**: ___/5 - Comments: _______________ + +### **Always-On Effectiveness** + +- **Consistency**: Are these rules applied consistently across all prompts? +- **Value**: Do these rules add value to every interaction? +- **Overhead**: Are these rules too burdensome for simple tasks? + +### **Integration Feedback** + +- **With Other Meta-Rules**: How well do these integrate with workflow rules? +- **Context Switching**: Do these rules help or hinder context switching? +- **Learning Curve**: Are these rules easy for new users to understand? + +### **Overall Experience** + +- **Quality Improvement**: Do these rules improve response quality? +- **Efficiency**: Do these rules make interactions more efficient? +- **Recommendation**: Would you recommend keeping these always-on? + +## Model Implementation Checklist + +### Before Every Prompt + +- [ ] **Base Context**: Ensure human competence principles are active +- [ ] **Time Standards**: Verify UTC and timestamp requirements are clear +- [ ] **Application Context**: Confirm TimeSafari context is loaded +- [ ] **Version Control**: Prepare commit standards if code changes are needed + +### During Response Creation + +- [ ] **Output Contract**: Follow required response structure +- [ ] **Competence Hooks**: Include learning and collaboration elements +- [ ] **Time Consistency**: Apply UTC standards for all time references +- [ ] **Platform Awareness**: Consider all target platforms + +### After Response Creation + +- [ ] **Validation**: Verify all always-on rules were applied +- [ ] **Quality Check**: Ensure response meets competence standards +- [ ] **Context Review**: Confirm application context was properly considered +- [ ] **Feedback Collection**: Note any issues with always-on application + +--- + +**See also**: + +- `.cursor/rules/meta_feature_planning.mdc` for workflow-specific rules +- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation workflows +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation +- `.cursor/rules/meta_feature_implementation.mdc` for feature development + +**Status**: Active core always-on meta-rule +**Priority**: Critical (applies to every prompt) +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: All AI interactions, Development team diff --git a/.cursor/rules/app/architectural_decision_record.mdc b/.cursor/rules/app/architectural_decision_record.mdc new file mode 100644 index 0000000..c562272 --- /dev/null +++ b/.cursor/rules/app/architectural_decision_record.mdc @@ -0,0 +1,193 @@ +# TimeSafari Cross-Platform Architecture Guide + +**Author**: Matthew Raymer +**Date**: 2025-08-19 +**Status**: 🎯 **ACTIVE** - Architecture guidelines + +## 1. Platform Support Matrix + +| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) | +|---------|-----------|--------------------|-------------------| +| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | + Not Implemented | +| Deep Linking | URL Parameters | App URL Open Events | Not Implemented | +| File System | Limited (Browser API) | Capacitor Filesystem | Electron fs | +| Camera Access | MediaDevices API | Capacitor Camera | Not Implemented | +| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env + checks | + +## 2. Project Structure + +### Core Directories + +``` + +src/ +├── components/ # Vue components +├── services/ # Platform services and business logic +├── views/ # Page components +├── router/ # Vue router configuration +├── types/ # TypeScript type definitions +├── utils/ # Utility functions +├── lib/ # Core libraries +├── platforms/ # Platform-specific implementations +├── electron/ # Electron-specific code +├── constants/ # Application constants +├── db/ # Database related code +├── interfaces/ # TypeScript interfaces +└── assets/ # Static assets + +``` + +### Entry Points + +- `main.ts` → Base entry + +- `main.common.ts` → Shared init + +- `main.capacitor.ts` → Mobile entry + +- `main.electron.ts` → Electron entry + +- `main.web.ts` → Web entry + +## 3. Service Architecture + +### Service Organization + +```tree + +services/ +├── QRScanner/ +│ ├── WebInlineQRScanner.ts +│ └── interfaces.ts +├── platforms/ +│ ├── WebPlatformService.ts +│ ├── CapacitorPlatformService.ts +│ └── ElectronPlatformService.ts +└── factory/ + └── PlatformServiceFactory.ts + +``` + +### Factory Pattern + +Use a **singleton factory** to select platform services via +`process.env.VITE_PLATFORM`. + +## 4. Feature Guidelines + +### QR Code Scanning + +- Define `QRScannerService` interface. + +- Implement platform-specific classes (`WebInlineQRScanner`, Capacitor, + + etc). + +- Provide `addListener` and `onStream` hooks for composability. + +### Deep Linking + +- URL format: `timesafari://[/][?query=value]` + +- Web: `router.beforeEach` → parse query + +- Capacitor: `App.addListener("appUrlOpen", …)` + +## 5. Build Process + +- `vite.config.common.mts` → shared config + +- Platform configs: `vite.config.web.mts`, `.capacitor.mts`, + + `.electron.mts` + +- Use `process.env.VITE_PLATFORM` for conditional loading. + +```bash + +npm run build:web +npm run build:capacitor +npm run build:electron + +``` + +## 6. Testing Strategy + +- **Unit Tests**: Jest for business logic and utilities + +- **E2E Tests**: Playwright for critical user journeys + +- **Platform Tests**: Test platform-specific implementations + +- **Integration Tests**: Test service interactions + +## 7. Key Principles + +### Platform Independence + +- **Abstract platform differences** behind interfaces + +- **Use factory pattern** for service selection + +- **Maintain consistent APIs** across platforms + +- **Graceful degradation** when features unavailable + +### Code Organization + +- **Single responsibility** for each service + +- **Interface segregation** for platform services + +- **Dependency injection** via mixins + +- **Composition over inheritance** + +--- + +**See also**: + +- `.cursor/rules/app/architectural_implementation.mdc` for + + detailed implementation details + +- `.cursor/rules/app/architectural_patterns.mdc` for architectural patterns and + + examples + +**Status**: Active architecture guidelines +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: timesafari.mdc +**Stakeholders**: Development team, Architecture team + +- [ ] Have relevant ADRs been updated/linked? + +- [ ] Did I add competence hooks or prompts for the team? + +- [ ] Was human interaction (sync/review/demo) scheduled? + +## Model Implementation Checklist + +### Before Architectural Decisions + +- [ ] **Decision Context**: Understand the architectural challenge to be addressed +- [ ] **Stakeholder Identification**: Identify all decision makers and affected parties +- [ ] **Research**: Research alternatives and gather evidence +- [ ] **Impact Assessment**: Assess impact on existing architecture + +### During Architectural Decisions + +- [ ] **Context Documentation**: Document the context and forces at play +- [ ] **Decision Recording**: Record the decision and rationale clearly +- [ ] **Consequences Analysis**: Analyze positive, negative, and neutral consequences +- [ ] **Alternatives Documentation**: Document alternatives considered and why rejected + +### After Architectural Decisions + +- [ ] **ADR Creation**: Create or update Architectural Decision Record +- [ ] **Team Communication**: Communicate decision to all stakeholders +- [ ] **Implementation Planning**: Plan implementation of the architectural decision +- [ ] **Documentation Update**: Update relevant architectural documentation diff --git a/.cursor/rules/app/architectural_examples.mdc b/.cursor/rules/app/architectural_examples.mdc new file mode 100644 index 0000000..babc8e1 --- /dev/null +++ b/.cursor/rules/app/architectural_examples.mdc @@ -0,0 +1,246 @@ +# Time Safari Architecture — Examples and Testing + +> **Agent role**: Reference this file for architectural examples and + testing patterns when working with TimeSafari architecture. + +## Error Handling Patterns + +### Global Error Handler + +```typescript + +// main.ts +app.config.errorHandler = (err, instance, info) => { + const componentName = instance?.$options?.name || 'Unknown'; + logger.error(`[${componentName}] Vue error`, err, info); +}; + +window.addEventListener('unhandledrejection', (event) => { + logger.error('[Global] Unhandled promise rejection', event.reason); +}); + +``` + +### Platform-Specific Error Wrapping + +```typescript + +// services/platforms/CapacitorPlatformService.ts +export class CapacitorPlatformService { + async getFileContents(path: string): Promise { + try { + const result = await Filesystem.readFile({ + path: path, + encoding: 'utf8' + }); + return result.data; + } catch (error) { + logger.error('[Capacitor API Error] Failed to read file', error, path); + throw new Error(`Failed to read file: ${path}`); + } + } +} + +``` + +## Testing Patterns + +### Platform-Specific Test Skipping + +```typescript + +// tests/QRScanner.test.ts +describe('QRScanner Service', () => { + test('should start scanning on web', async () => { + test.skip(process.env.VITE_PLATFORM !== 'web', 'Web-only test'); + + const scanner = new WebInlineQRScanner(); + await scanner.startScanning(); + // Assert scanning started + }); + + test('should start scanning on mobile', async () => { + test.skip(process.env.VITE_PLATFORM !== 'capacitor', 'Mobile-only test'); + + const scanner = new CapacitorQRScanner(); + await scanner.startScanning(); + // Assert scanning started + }); +}); + +``` + +### Mock Service Testing + +```typescript + +// tests/mocks/QRScannerMock.ts +export class QRScannerMock implements QRScannerService { + private isScanning = false; + private listeners: Map = new Map(); + + async startScanning(): Promise { + this.isScanning = true; + this.emit('scanningStarted'); + } + + async stopScanning(): Promise { + this.isScanning = false; + this.emit('scanningStopped'); + } + + addListener(event: string, callback: Function): void { + if (!this.listeners.has(event)) { + this.listeners.set(event, []); + } + this.listeners.get(event)!.push(callback); + } + + removeListener(event: string, callback: Function): void { + const callbacks = this.listeners.get(event); + if (callbacks) { + const index = callbacks.indexOf(callback); + if (index > -1) { + callbacks.splice(index, 1); + } + } + } + + private emit(event: string, ...args: any[]): void { + const callbacks = this.listeners.get(event); + if (callbacks) { + callbacks.forEach(callback => callback(...args)); + } + } + + getScanningState(): boolean { + return this.isScanning; + } +} + +``` + +## Integration Examples + +### Service Composition + +```typescript + +// services/QRScannerService.ts +export class QRScannerService { + constructor( + private platformService: PlatformService, + private notificationService: NotificationService + ) {} + + async startScanning(): Promise { + try { + await this.platformService.startCamera(); + this.notificationService.show('Camera started'); + } catch (error) { + this.notificationService.showError('Failed to start camera'); + throw error; + } + } +} + +``` + +### Component Integration + +```typescript + +// components/QRScannerDialog.vue +export default class QRScannerDialog extends Vue { + @Inject() private qrScannerService!: QRScannerService; + + async mounted() { + try { + await this.qrScannerService.startScanning(); + } catch (error) { + this.$notify.error('Failed to start scanner'); + } + } + + beforeDestroy() { + this.qrScannerService.stopScanning(); + } +} + +``` + +## Best Practices + +### Service Design + +- Keep services focused and single-purpose + +- Use dependency injection for service composition + +- Implement proper error handling and logging + +- Provide clear interfaces and contracts + +### Testing Strategy + +- Test platform-specific behavior separately + +- Use mocks for external dependencies + +- Test error conditions and edge cases + +- Validate service contracts and interfaces + +### Error Handling + +- Log errors with appropriate context + +- Provide user-friendly error messages + +- Implement graceful degradation + +- Handle platform-specific error scenarios + +--- + +**See also**: + +- `.cursor/rules/app/architectural_decision_record.mdc` for + + core architecture principles + +- `.cursor/rules/app/architectural_implementation.mdc` for + + implementation details + +- `.cursor/rules/app/architectural_patterns.mdc` for core patterns + +**Status**: Active examples and testing guide +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: architectural_patterns.mdc +**Stakeholders**: Development team, Testing team + +## Model Implementation Checklist + +### Before Architectural Examples + +- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use + case +- [ ] **Service Design**: Plan service structure and dependencies +- [ ] **Testing Strategy**: Plan testing approach for the example +- [ ] **Error Handling**: Plan error handling and logging strategy + +### During Architectural Examples + +- [ ] **Service Implementation**: Implement focused, single-purpose services +- [ ] **Dependency Injection**: Use proper dependency injection patterns +- [ ] **Error Handling**: Implement proper error handling and logging +- [ ] **Interface Design**: Provide clear interfaces and contracts + +### After Architectural Examples + +- [ ] **Testing Execution**: Test platform-specific behavior separately +- [ ] **Service Validation**: Validate service contracts and interfaces +- [ ] **Error Testing**: Test error conditions and edge cases +- [ ] **Documentation**: Update architectural examples documentation diff --git a/.cursor/rules/app/architectural_implementation.mdc b/.cursor/rules/app/architectural_implementation.mdc new file mode 100644 index 0000000..bd85386 --- /dev/null +++ b/.cursor/rules/app/architectural_implementation.mdc @@ -0,0 +1,139 @@ +# Time Safari Architecture — Implementation Details + +> **Agent role**: Reference this file for detailed implementation details when + working with TimeSafari architecture implementation. + +## Error Handling + +- Global Vue error handler → logs with component name. + +- Platform-specific wrappers log API errors with platform prefix + + (`[Capacitor API Error]`, etc). + +- Use structured logging (not `console.log`). + +## Best Practices + +- Keep platform code **isolated** in `platforms/`. + +- Always define a **shared interface** first. + +- Use feature detection, not platform detection, when possible. + +- Dependency injection for services → improves testability. + +- Maintain **Competence Hooks** in PRs (2–3 prompts for dev + + discussion). + +## Dependency Management + +- Key deps: `@capacitor/core`, `electron`, `vue`. + +- Use conditional `import()` for platform-specific libs. + +## Security Considerations + +- **Permissions**: Always check + request gracefully. + +- **Storage**: Secure storage for sensitive data; encrypt when possible. + +- **Audits**: Schedule quarterly security reviews. + +## ADR Process + +- All major architecture choices → log in `doc/adr/`. + +- Use ADR template with Context, Decision, Consequences, Status. + +- Link related ADRs in PR descriptions. + +> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min +> design sync for discussion, not just async review. + +## Collaboration Hooks + +- **QR features**: Sync with Security before merging → permissions & + + privacy. + +- **New platform builds**: Demo in team meeting → confirm UX + + differences. + +- **Critical ADRs**: Present in guild or architecture review. + +## Testing Implementation + +- **Unit tests** for services. + +- **Playwright** for Web + Capacitor: + + - `playwright.config-local.ts` includes web + Pixel 5. + +- **Electron tests**: add `spectron` or Playwright-Electron. + +- Mark tests with platform tags: + + ```ts + + test.skip(!process.env.MOBILE_TEST, "Mobile-only test"); + + ``` + +> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15 +> min) with QA to align on coverage and flaky test risks. + +## Self-Check + +- [ ] Does this feature implement a shared interface? + +- [ ] Are fallbacks + errors handled gracefully? + +- [ ] Have relevant ADRs been updated/linked? + +- [ ] Did I add competence hooks or prompts for the team? + +- [ ] Was human interaction (sync/review/demo) scheduled? + +--- + +**See also**: + +- `.cursor/rules/app/architectural_decision_record.mdc` for + + core architecture principles + +- `.cursor/rules/app/architectural_patterns.mdc` for architectural patterns and + + examples + +**Status**: Active implementation guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: architectural_decision_record.mdc +**Stakeholders**: Development team, Architecture team + +## Model Implementation Checklist + +### Before Architectural Implementation + +- [ ] **Interface Review**: Verify feature implements shared interface +- [ ] **ADR Review**: Check if ADR is required for major changes +- [ ] **Security Assessment**: Assess security implications for QR features +- [ ] **Platform Planning**: Plan platform-specific implementation details + +### During Architectural Implementation + +- [ ] **Interface Implementation**: Implement shared interfaces consistently +- [ ] **Error Handling**: Implement graceful fallbacks and error handling +- [ ] **Testing Strategy**: Plan unit tests for services and E2E tests +- [ ] **Human Interaction**: Schedule syncs/reviews/demos as needed + +### After Architectural Implementation + +- [ ] **Interface Validation**: Verify shared interfaces are properly implemented +- [ ] **Testing Execution**: Run unit tests and platform-specific tests +- [ ] **ADR Updates**: Update relevant ADRs and link in PR descriptions +- [ ] **Team Communication**: Share implementation results with team diff --git a/.cursor/rules/app/architectural_patterns.mdc b/.cursor/rules/app/architectural_patterns.mdc new file mode 100644 index 0000000..026a835 --- /dev/null +++ b/.cursor/rules/app/architectural_patterns.mdc @@ -0,0 +1,214 @@ +# Time Safari Architecture — Patterns and Examples + +> **Agent role**: Reference this file for architectural patterns and +> examples when working with TimeSafari architecture design. + +## Architectural Patterns + +### Factory Pattern Implementation + +```typescript +// PlatformServiceFactory.ts +export class PlatformServiceFactory { + private static instance: PlatformServiceFactory; + + static getInstance(): PlatformServiceFactory { + if (!PlatformServiceFactory.instance) { + PlatformServiceFactory.instance = new PlatformServiceFactory(); + } + return PlatformServiceFactory.instance; + } + + getQRScannerService(): QRScannerService { + const platform = process.env.VITE_PLATFORM; + + switch (platform) { + case 'web': + return new WebInlineQRScanner(); + case 'capacitor': + return new CapacitorQRScanner(); + case 'electron': + return new ElectronQRScanner(); + default: + throw new Error(`Unsupported platform: ${platform}`); + } + } +} +``` + +### Service Interface Definition + +```typescript +// interfaces/QRScannerService.ts +export interface QRScannerService { + startScanning(): Promise; + stopScanning(): Promise; + addListener(event: string, callback: Function): void; + removeListener(event: string, callback: Function): void; +} +``` + +### Platform-Specific Implementation + +```typescript +// services/QRScanner/WebInlineQRScanner.ts +export class WebInlineQRScanner implements QRScannerService { + private listeners: Map = new Map(); + + async startScanning(): Promise { + // Web-specific implementation + const stream = await navigator.mediaDevices.getUserMedia({ video: true }); + // Process video stream for QR codes + } + + async stopScanning(): Promise { + // Stop video stream + } + + addListener(event: string, callback: Function): void { + if (!this.listeners.has(event)) { + this.listeners.set(event, []); + } + this.listeners.get(event)!.push(callback); + } + + removeListener(event: string, callback: Function): void { + const callbacks = this.listeners.get(event); + if (callbacks) { + const index = callbacks.indexOf(callback); + if (index > -1) { + callbacks.splice(index, 1); + } + } + } +} +``` + +## Deep Linking Implementation + +### URL Format + +``` +timesafari://[/][?query=value] +``` + +### Web Implementation + +```typescript +// router/index.ts +router.beforeEach((to, from, next) => { + // Parse deep link parameters + if (to.query.deepLink) { + const deepLink = to.query.deepLink as string; + // Process deep link + handleDeepLink(deepLink); + } + next(); +}); + +function handleDeepLink(deepLink: string) { + // Parse and route deep link + const url = new URL(deepLink); + const route = url.pathname; + const params = url.searchParams; + + // Navigate to appropriate route + router.push({ name: route, query: Object.fromEntries(params) }); +} +``` + +### Capacitor Implementation + +```typescript +// main.capacitor.ts +import { App } from '@capacitor/app'; + +App.addListener('appUrlOpen', (data) => { + const url = data.url; + // Parse deep link and navigate + handleDeepLink(url); +}); +``` + +## Platform Detection + +### Feature Detection vs Platform Detection + +```typescript +// ✅ Good: Feature detection +function hasCameraAccess(): boolean { + return 'mediaDevices' in navigator && + 'getUserMedia' in navigator.mediaDevices; +} + +// ❌ Bad: Platform detection +function isWeb(): boolean { + return process.env.VITE_PLATFORM === 'web'; +} +``` + +### Conditional Imports + +```typescript +// services/platforms/index.ts +export async function getPlatformService() { + const platform = process.env.VITE_PLATFORM; + + switch (platform) { + case 'capacitor': + const { CapacitorPlatformService } = + await import('./CapacitorPlatformService'); + return new CapacitorPlatformService(); + case 'electron': + const { ElectronPlatformService } = + await import('./ElectronPlatformService'); + return new ElectronPlatformService(); + default: + const { WebPlatformService } = + await import('./WebPlatformService'); + return new WebPlatformService(); + } +} +``` + +--- + +**See also**: + +- `.cursor/rules/app/architectural_decision_record.mdc` for core + architecture principles +- `.cursor/rules/app/architectural_implementation.mdc` for + implementation details +- `.cursor/rules/app/architectural_examples.mdc` for examples and + testing patterns + +**Status**: Active patterns and examples +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: architectural_decision_record.mdc, + architectural_implementation.mdc +**Stakeholders**: Development team, Architecture team + +## Model Implementation Checklist + +### Before Architectural Patterns + +- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use + case +- [ ] **Platform Analysis**: Identify platform-specific requirements +- [ ] **Service Planning**: Plan service structure and dependencies +- [ ] **Testing Strategy**: Plan testing approach for the pattern + +### During Architectural Patterns + +- [ ] **Pattern Implementation**: Implement chosen architectural pattern +- [ ] **Platform Abstraction**: Use platform abstraction layers appropriately +- [ ] **Service Composition**: Compose services using dependency injection +- [ ] **Interface Design**: Provide clear interfaces and contracts + +### After Architectural Patterns + +- [ ] **Pattern Validation**: Verify pattern is implemented correctly +- [ ] **Platform Testing**: Test across all target platforms +- [ ] **Service Testing**: Test service composition and dependencies +- [ ] **Documentation**: Update architectural patterns documentation diff --git a/.cursor/rules/app/timesafari.mdc b/.cursor/rules/app/timesafari.mdc new file mode 100644 index 0000000..ad8a224 --- /dev/null +++ b/.cursor/rules/app/timesafari.mdc @@ -0,0 +1,173 @@ +--- +alwaysApply: false +--- +# Time Safari Context + +**Author**: Matthew Raymer +**Date**: 2025-08-19 +**Status**: 🎯 **ACTIVE** - Core application context + +## Project Overview + +Time Safari is an application designed to foster community building through +gifts, gratitude, and collaborative projects. The app makes it easy and +intuitive for users of any age and capability to recognize contributions, +build trust networks, and organize collective action. It is built on services +that preserve privacy and data sovereignty. + +## Core Goals + +1. **Connect**: Make it easy, rewarding, and non-threatening for people to + + connect with others who have similar interests, and to initiate activities + together. + +2. **Reveal**: Widely advertise the great support and rewards that are being + + given and accepted freely, especially non-monetary ones, showing the impact + gifts make in people's lives. + +## Technical Foundation + +### Architecture + +- **Privacy-preserving claims architecture** via endorser.ch + +- **Decentralized Identifiers (DIDs)**: User identities based on + + public/private key pairs stored on devices + +- **Cryptographic Verification**: All claims and confirmations are + + cryptographically signed + +- **User-Controlled Visibility**: Users explicitly control who can see their + + identifiers and data + +- **Cross-Platform**: Web (PWA), Mobile (Capacitor), Desktop (Electron) + +### Current Database State + +- **Database**: SQLite via Absurd SQL (browser) and native SQLite + + (mobile/desktop) + +- **Legacy Support**: IndexedDB (Dexie) for backward compatibility + +- **Status**: Modern database architecture fully implemented + +### Core Technologies + +- **Frontend**: Vue 3 + TypeScript + vue-facing-decorator + +- **Styling**: TailwindCSS + +- **Build**: Vite with platform-specific configs + +- **Testing**: Playwright E2E, Jest unit tests + +- **Database**: SQLite (Absurd SQL in browser), IndexedDB (legacy) + +- **State**: Pinia stores + +- **Platform Services**: Abstracted behind interfaces with factory pattern + +## Development Principles + +### Code Organization + +- **Platform Services**: Abstract platform-specific code behind interfaces + +- **Service Factory**: Use `PlatformServiceFactory` for platform selection + +- **Type Safety**: Strict TypeScript, no `any` types, use type guards + +- **Modern Architecture**: Use current platform service patterns + +### Architecture Patterns + +- **Dependency Injection**: Services injected via mixins and factory pattern + +- **Interface Segregation**: Small, focused interfaces over large ones + +- **Composition over Inheritance**: Prefer mixins and composition + +- **Single Responsibility**: Each component/service has one clear purpose + +### Testing Strategy + +- **E2E**: Playwright for critical user journeys + +- **Unit**: Jest with F.I.R.S.T. principles + +- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI + +- **Quality Assurance**: Comprehensive testing and validation + +## Current Development Focus + +### Active Development + +- **Feature Development**: Build new functionality using modern platform + + services + +- **Performance Optimization**: Improve app performance and user experience + +- **Platform Enhancement**: Leverage platform-specific capabilities + +- **Code Quality**: Maintain high standards and best practices + +### Development Metrics + +- **Code Quality**: High standards maintained across all platforms + +- **Performance**: Optimized for all target devices + +- **Testing**: Comprehensive coverage maintained + +- **User Experience**: Focus on intuitive, accessible interfaces + +--- + +**See also**: + +- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details + +- `.cursor/rules/app/timesafari_development.mdc` for + + development workflow details + +**Status**: Active application context +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Product team + +- **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron + +- **Stakeholders**: Development team, Product team + +## Model Implementation Checklist + +### Before TimeSafari Development + +- [ ] **Application Context**: Understand TimeSafari's community-building purpose +- [ ] **Platform Analysis**: Identify target platforms (web, mobile, desktop) +- [ ] **Architecture Review**: Review current platform service patterns +- [ ] **Testing Strategy**: Plan testing approach for all platforms + +### During TimeSafari Development + +- [ ] **Platform Services**: Use abstracted platform services via interfaces +- [ ] **Type Safety**: Implement strict TypeScript with type guards +- **Modern Architecture**: Follow current platform service patterns +- [ ] **Performance Focus**: Ensure performance on all target devices + +### After TimeSafari Development + +- [ ] **Cross-Platform Testing**: Test functionality across all platforms +- [ ] **Performance Validation**: Verify performance meets requirements +- [ ] **Code Quality**: Ensure high standards maintained +- [ ] **Documentation Update**: Update relevant documentation diff --git a/.cursor/rules/app/timesafari_development.mdc b/.cursor/rules/app/timesafari_development.mdc new file mode 100644 index 0000000..e72c68d --- /dev/null +++ b/.cursor/rules/app/timesafari_development.mdc @@ -0,0 +1,174 @@ +# Time Safari Development — Workflow and Processes + +> **Agent role**: Reference this file for development workflow details when + working with TimeSafari development processes. + +## Development Workflow + +### Build Commands + +```bash + +# Web (development) + +npm run build:web + +# Mobile + +npm run build:capacitor +npm run build:native + +# Desktop + +npm run build:electron +npm run build:electron:appimage +npm run build:electron:deb +npm run build:electron:dmg + +``` + +### Testing Commands + +```bash + +# Web E2E + +npm run test:web + +# Mobile + +npm run test:mobile +npm run test:android +npm run test:ios + +# Type checking + +npm run type-check +npm run lint-fix + +``` + +## Development Principles + +### Code Organization + +- **Platform Services**: Abstract platform-specific code behind interfaces + +- **Service Factory**: Use `PlatformServiceFactory` for platform selection + +- **Type Safety**: Strict TypeScript, no `any` types, use type guards + +- **Modern Architecture**: Use current platform service patterns + +### Architecture Patterns + +- **Dependency Injection**: Services injected via mixins and factory pattern + +- **Interface Segregation**: Small, focused interfaces over large ones + +- **Composition over Inheritance**: Prefer mixins and composition + +- **Single Responsibility**: Each component/service has one clear purpose + +### Testing Strategy + +- **E2E**: Playwright for critical user journeys + +- **Unit**: Jest with F.I.R.S.T. principles + +- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI + +- **Quality Assurance**: Comprehensive testing and validation + +## Current Development Focus + +### Active Development + +- **Feature Development**: Build new functionality using modern platform + + services + +- **Performance Optimization**: Improve app performance and user experience + +- **Platform Enhancement**: Leverage platform-specific capabilities + +- **Code Quality**: Maintain high standards and best practices + +### Development Metrics + +- **Code Quality**: High standards maintained across all platforms + +- **Performance**: Optimized for all target devices + +- **Testing**: Comprehensive coverage maintained + +- **User Experience**: Focus on intuitive, accessible interfaces + +## Development Environment + +### Required Tools + +- **Node.js**: LTS version with npm + +- **Git**: Version control with proper branching strategy + +- **IDE**: VS Code with recommended extensions + +- **Platform Tools**: Android Studio, Xcode (for mobile development) + +### Environment Setup + +1. **Clone Repository**: `git clone ` + +2. **Install Dependencies**: `npm install` + +3. **Environment Variables**: Copy `.env.example` to `.env.local` + +4. **Platform Setup**: Follow platform-specific setup guides + +### Quality Assurance + +- **Linting**: ESLint with TypeScript rules + +- **Formatting**: Prettier for consistent code style + +- **Type Checking**: TypeScript strict mode enabled + +- **Testing**: Comprehensive test coverage requirements + +--- + +**See also**: + +- `.cursor/rules/app/timesafari.mdc` for core application context + +- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details + +**Status**: Active development workflow +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: timesafari.mdc, timesafari_platforms.mdc +**Stakeholders**: Development team, DevOps team + +## Model Implementation Checklist + +### Before TimeSafari Development + +- [ ] **Environment Setup**: Verify development environment is ready +- [ ] **Platform Tools**: Ensure platform-specific tools are available +- [ ] **Dependencies**: Check all required dependencies are installed +- [ ] **Environment Variables**: Configure local environment variables + +### During TimeSafari Development + +- [ ] **Platform Services**: Use modern platform service patterns +- [ ] **Code Quality**: Follow ESLint and TypeScript strict rules +- [ ] **Testing**: Implement comprehensive testing strategy +- [ ] **Performance**: Optimize for all target platforms + +### After TimeSafari Development + +- [ ] **Quality Checks**: Run linting, formatting, and type checking +- [ ] **Testing**: Execute comprehensive tests across platforms +- [ ] **Performance Validation**: Verify performance meets requirements +- [ ] **Documentation**: Update development documentation diff --git a/.cursor/rules/app/timesafari_platforms.mdc b/.cursor/rules/app/timesafari_platforms.mdc new file mode 100644 index 0000000..158e61f --- /dev/null +++ b/.cursor/rules/app/timesafari_platforms.mdc @@ -0,0 +1,167 @@ +# Time Safari Platforms — Platform-Specific Considerations + +> **Agent role**: Reference this file for platform-specific details when working + with TimeSafari development across different platforms. + +## Platform-Specific Considerations + +### Web (PWA) + +- **QR Scanning**: WebInlineQRScanner + +- **Deep Linking**: URL parameters + +- **File System**: Limited browser APIs + +- **Build**: `npm run build:web` (development build) + +### Mobile (Capacitor) + +- **QR Scanning**: @capacitor-mlkit/barcode-scanning + +- **Deep Linking**: App URL open events + +- **File System**: Capacitor Filesystem + +- **Build**: `npm run build:capacitor` + +### Desktop (Electron) + +- **File System**: Node.js fs + +- **Build**: `npm run build:electron` + +- **Distribution**: AppImage, DEB, DMG packages + +## Platform Compatibility Requirements + +### Cross-Platform Features + +- **Core functionality** must work identically across all platforms + +- **Platform-specific enhancements** should be additive, not required + +- **Fallback behavior** must be graceful when platform features unavailable + +### Platform-Specific Capabilities + +- **Web**: Browser APIs, PWA features, responsive design + +- **Mobile**: Native device features, offline capability, app store compliance + +- **Desktop**: File system access, system integration, native performance + +## Build and Distribution + +### Build Commands + +```bash + +# Web (development) + +npm run build:web + +# Mobile + +npm run build:capacitor +npm run build:native + +# Desktop + +npm run build:electron +npm run build:electron:appimage +npm run build:electron:deb +npm run build:electron:dmg + +``` + +### Testing Commands + +```bash + +# Web E2E + +npm run test:web + +# Mobile + +npm run test:mobile +npm run test:android +npm run test:ios + +# Type checking + +npm run type-check +npm run lint-fix + +``` + +## Key Constraints + +1. **Privacy First**: User identifiers remain private except when explicitly + + shared + +2. **Platform Compatibility**: Features must work across all target platforms + +3. **Performance**: Must remain performant on older/simpler devices + +4. **Modern Architecture**: New features should use current platform services + +5. **Offline Capability**: Key functionality should work offline when feasible + +## Use Cases to Support + +1. **Community Building**: Tools for finding others with shared interests + +2. **Project Coordination**: Easy proposal and collaboration on projects + +3. **Reputation Building**: Showcasing contributions and reliability + +4. **Governance**: Facilitating decision-making and collective governance + +## Resources + +- **Testing**: `docs/migration-testing/` + +- **Architecture**: `docs/architecture-decisions.md` + +- **Build Context**: `docs/build-modernization-context.md` + +--- + +**See also**: + +- `.cursor/rules/app/timesafari.mdc` for core application context +- `.cursor/rules/app/timesafari_development.mdc` for + + development workflow details + +**Status**: Active platform guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: timesafari.mdc +**Stakeholders**: Development team, Platform teams + +## Model Implementation Checklist + +### Before Platform Development + +- [ ] **Platform Analysis**: Identify all target platforms (web, mobile, desktop) +- [ ] **Feature Requirements**: Understand feature requirements across platforms +- [ ] **Platform Constraints**: Review platform-specific limitations and capabilities +- [ ] **Testing Strategy**: Plan testing approach for all target platforms + +### During Platform Development + +- [ ] **Cross-Platform Implementation**: Implement features across all platforms +- [ ] **Platform Services**: Use current platform services for new features +- [ ] **Performance Optimization**: Ensure performance on older/simpler devices +- [ ] **Offline Capability**: Implement offline functionality where feasible + +### After Platform Development + +- [ ] **Cross-Platform Testing**: Test functionality across all target platforms +- [ ] **Performance Validation**: Verify performance meets requirements +- [ ] **Documentation Update**: Update platform-specific documentation +- [ ] **Team Communication**: Share platform implementation results with team diff --git a/.cursor/rules/architecture/README.md b/.cursor/rules/architecture/README.md new file mode 100644 index 0000000..ac9669d --- /dev/null +++ b/.cursor/rules/architecture/README.md @@ -0,0 +1,75 @@ +# Architecture Rules Directory + +**Author**: Matthew Raymer +**Date**: 2025-08-20 +**Status**: 🎯 **ACTIVE** - Architecture protection guidelines + +## Overview + +This directory contains MDC (Model Directive Configuration) rules that protect +critical architectural components of the TimeSafari project. These rules ensure +that changes to system architecture follow proper review, testing, and +documentation procedures. + +## Available Rules + +### Build Architecture Guard (`build_architecture_guard.mdc`) + +Protects the multi-platform build system including: + +- Vite configuration files +- Build scripts and automation +- Platform-specific configurations (iOS, Android, Electron, Web) +- Docker and deployment infrastructure +- CI/CD pipeline components + +**When to use**: Any time you're modifying build scripts, configuration files, +or deployment processes. + +**Authorization levels**: + +- **Level 1**: Minor changes (review required) +- **Level 2**: Moderate changes (testing required) +- **Level 3**: Major changes (ADR required) + +## Usage Guidelines + +### For Developers + +1. **Check the rule**: Before making architectural changes, review the relevant + rule +2. **Follow the process**: Use the appropriate authorization level +3. **Complete validation**: Run through the required checklist +4. **Update documentation**: Keep BUILDING.md and related docs current + +### For Reviewers + +1. **Verify authorization**: Ensure changes match the required level +2. **Check testing**: Confirm appropriate testing has been completed +3. **Validate documentation**: Ensure BUILDING.md reflects changes +4. **Assess risk**: Consider impact on other platforms and systems + +## Integration with Other Rules + +- **Version Control**: Works with `workflow/version_control.mdc` +- **Research & Diagnostic**: Supports `research_diagnostic.mdc` for + investigations +- **Software Development**: Aligns with development best practices +- **Markdown Automation**: Integrates with `docs/markdown-automation.mdc` for + consistent documentation formatting + +## Emergency Procedures + +If architectural changes cause system failures: + +1. **Immediate rollback** to last known working state +2. **Document the failure** with full error details +3. **Investigate root cause** using diagnostic workflows +4. **Update procedures** to prevent future failures + +--- + +**Status**: Active architecture protection +**Priority**: Critical +**Maintainer**: Development team +**Next Review**: 2025-09-20 diff --git a/.cursor/rules/architecture/build_architecture_guard.mdc b/.cursor/rules/architecture/build_architecture_guard.mdc new file mode 100644 index 0000000..1b07690 --- /dev/null +++ b/.cursor/rules/architecture/build_architecture_guard.mdc @@ -0,0 +1,186 @@ + +# Build Architecture Guard Directive + +**Author**: Matthew Raymer +**Date**: 2025-08-22 +**Status**: 🎯 **ACTIVE** - Build system protection guidelines + +## Purpose + +Protect the TimeSafari building architecture from unauthorized changes that +could break the multi-platform build pipeline, deployment processes, or +development workflow. This directive ensures all build system modifications +follow proper review, testing, and documentation procedures. + +**Note**: Recent Android build system enhancements (2025-08-22) include + sophisticated asset validation, platform-specific API routing, and automatic + resource regeneration. These features require enhanced testing and validation + procedures. + +## Protected Architecture Components + +### Core Build Infrastructure + +- **Vite Configuration Files**: `vite.config.*.mts` files + +- **Build Scripts**: All scripts in `scripts/` directory + +- **Package Scripts**: `package.json` build-related scripts + +- **Platform Configs**: `capacitor.config.ts`, `electron/`, `android/`, + + `ios/` + +- **Docker Configuration**: `Dockerfile`, `docker-compose.yml` + +- **Environment Files**: `.env.*`, `.nvmrc`, `.node-version` + +### Android-Specific Build Validation + +- **Asset Validation Scripts**: + + `validate_android_assets()` function and resource checking + +- **Resource Generation**: `capacitor-assets` integration and verification + +- **Platform-Specific IP Handling**: + + Android emulator vs physical device API routing + +- **Build Mode Validation**: Development/test/production mode handling + +- **Resource Fallback Logic**: + + Automatic regeneration of missing Android resources + +### Critical Build Dependencies + +- **Build Tools**: Vite, Capacitor, Electron, Android SDK, Xcode + +- **Asset Management**: `capacitor-assets.config.json`, asset scripts + +- **Testing Infrastructure**: Playwright, Jest, mobile test scripts + +- **CI/CD Pipeline**: GitHub Actions, build validation scripts + +- **Service Worker Assembly**: `sw_scripts/`, `sw_combine.js`, WASM copy steps + +## Change Authorization Requirements + +### Level 1: Minor Changes (Requires Review) + +- Documentation updates to `BUILDING.md` + +- Non-breaking script improvements + +- Test additions or improvements + +- Asset configuration updates + +**Process**: Code review + basic testing + +### Level 2: Moderate Changes (Requires Testing) + +- New build script additions + +- Environment variable changes + +- Dependency version updates + +- Platform-specific optimizations + +- **Build script argument parsing**: + + New flag handling (--api-ip, --auto-run, --deploy) + +- **Platform-specific environment overrides**: + + Android API server IP customization + +- **Asset regeneration logic**: Automatic fallback for missing Android resources + +**Process**: Code review + platform testing + documentation update + +### Level 3: Major Changes (Requires ADR) + +- Build system architecture changes + +- New platform support + +- Breaking changes to build scripts + +- Major dependency migrations + +**Process**: ADR creation + comprehensive testing + team review + +## Prohibited Actions + +### ❌ Never Allow Without ADR + +- **Delete or rename** core build scripts + +- **Modify** `package.json` build script names + +- **Change** Vite configuration structure + +- **Remove** platform-specific build targets + +- **Alter** Docker build process + +- **Modify** CI/CD pipeline without testing + +### ❌ Never Allow Without Testing + +- **Update** build dependencies + +- **Change** environment configurations + +- **Modify** asset generation scripts + +- **Alter** test infrastructure + +- **Update** platform SDK versions + +--- + +**See also**: + +- `.cursor/rules/architecture/build_validation.mdc` for + + detailed validation procedures + +- `.cursor/rules/architecture/build_testing.mdc` for testing requirements + +**Status**: Active build protection guidelines +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, DevOps team, Build team + +**Estimated Effort**: Ongoing vigilance +**Dependencies**: All build system components +**Stakeholders**: Development team, DevOps, Platform owners +**Next Review**: 2025-09-22 + +## Model Implementation Checklist + +### Before Build Changes + +- [ ] **Change Level**: Determine if change is L1, L2, or L3 +- [ ] **Impact Assessment**: Assess impact on build system architecture +- [ ] **ADR Requirement**: Check if ADR is required for major changes +- [ ] **Testing Planning**: Plan appropriate testing for change level + +### During Build Changes + +- [ ] **Guard Compliance**: Ensure changes comply with build architecture guard +- [ ] **Documentation**: Document changes according to level requirements +- [ ] **Testing**: Execute appropriate testing for change level +- [ ] **Review Process**: Follow required review process for change level + +### After Build Changes + +- [ ] **Validation**: Verify build system still functions correctly +- [ ] **Documentation Update**: Update relevant documentation +- [ ] **Team Communication**: Communicate changes to affected teams +- [ ] **Monitoring**: Monitor for any build system issues diff --git a/.cursor/rules/architecture/build_testing.mdc b/.cursor/rules/architecture/build_testing.mdc new file mode 100644 index 0000000..4d0301d --- /dev/null +++ b/.cursor/rules/architecture/build_testing.mdc @@ -0,0 +1,248 @@ +# Build Testing — Requirements and Emergency Procedures + +> **Agent role**: Reference this file for testing requirements and + emergency procedures when working with build architecture changes. + +## Emergency Procedures + +### Build System Broken + +1. **Immediate**: Revert to last known working commit + +2. **Investigation**: Create issue with full error details + +3. **Testing**: Verify all platforms work after revert + +4. **Documentation**: Update `BUILDING.md` with failure notes + +### Platform-Specific Failure + +1. **Isolate**: Identify which platform is affected + +2. **Test Others**: Verify other platforms still work + +3. **Rollback**: Revert platform-specific changes + +4. **Investigation**: Debug in isolated environment + +## Rollback Playbook + +### Immediate Rollback + +1. `git revert` or `git reset --hard `; restore prior `scripts/` or config + + files + +2. Rebuild affected targets; verify old behavior returns + +3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found + +### Rollback Verification + +- **Web**: `npm run build:web:dev` and `npm run build:web:prod` + +- **Mobile**: `npm run build:android:test` and `npm run build:ios:test` + +- **Desktop**: `npm run build:electron:dev` and packaging commands + +- **Clean**: Run relevant `clean:*` scripts and verify re-build works + +### Android-Specific Rollback Verification + +- **Asset Generation**: `npm run build:android --assets` - + + verify resources regenerate + +- **API Routing**: Test both `--dev` and `--dev --api-ip ` modes + +- **Resource Validation**: + + Check `android/app/src/main/res/` for all required assets + +- **Build Modes**: Verify development, test, and production modes all work + +- **Resource Fallback**: + + Confirm missing resources trigger automatic regeneration + +## Integration Points + +### With Version Control + +- **Branch Protection**: Require reviews for build script changes + +- **Commit Messages**: Must reference ADR for major changes + +- **Testing**: All build changes must pass CI/CD pipeline + +### With Documentation + +- **BUILDING.md**: Must be updated for any script changes + +- **README.md**: Must reflect new build requirements + +- **CHANGELOG.md**: Must document breaking build changes + +### With Testing + +- **Pre-commit**: Run basic build validation + +- **CI/CD**: Full platform build testing + +- **Manual Testing**: Human verification of critical paths + +## Competence Hooks + +### Why This Works + +- **Prevents Build Failures**: Catches issues before they reach production + +- **Maintains Consistency**: Ensures all platforms build identically + +- **Reduces Debugging Time**: Prevents build system regressions + +### Common Pitfalls + +- **Silent Failures**: Changes that work on one platform but break others + +- **Dependency Conflicts**: Updates that create version incompatibilities + +- **Documentation Drift**: Build scripts that don't match documentation + +### Next Skill Unlock + +- Learn to test build changes across all platforms simultaneously + +### Teach-back + +- "What three platforms must I test before committing a build script change?" + +## Collaboration Hooks + +### Team Review Requirements + +- **Platform Owners**: iOS, Android, Electron, Web specialists + +- **DevOps**: CI/CD pipeline maintainers + +- **QA**: Testing infrastructure owners + +### Discussion Prompts + +- "Which platforms will be affected by this build change?" + +- "How can we test this change without breaking existing builds?" + +- "What's our rollback plan if this change fails?" + +## Self-Check (Before Allowing Changes) + +- [ ] **Authorization Level**: Is this change appropriate for the level? + +- [ ] **Testing Plan**: Is there a comprehensive testing strategy? + +- [ ] **Documentation**: Will BUILDING.md be updated? + +- [ ] **Rollback**: Is there a safe rollback mechanism? + +- [ ] **Team Review**: Have appropriate stakeholders been consulted? + +- [ ] **CI/CD**: Will this pass the build pipeline? + +## Continuous Improvement & Feedback + +### Feedback Collection + +The Build Architecture Guard system includes feedback mechanisms to continuously + improve its effectiveness: + +- **User Feedback**: Script includes feedback prompts for guard improvements + +- **Pattern Analysis**: + + Monitor which file patterns trigger false positives/negatives + +- **Documentation Gaps**: Track which changes lack proper documentation + +- **Testing Effectiveness**: Measure how often guard catches actual issues + +### Feedback Integration Process + +1. **Collect Feedback**: Monitor guard execution logs and user reports + +2. **Analyze Patterns**: Identify common false positives or missed patterns + +3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback + +4. **Enhance Script**: Update `build-arch-guard.sh` with new validations + +5. **Test Changes**: Verify guard improvements don't introduce new issues + +6. **Document Updates**: Update guard documentation with new patterns + +### Feedback Categories + +- **False Positives**: Files flagged as sensitive that shouldn't be + +- **False Negatives**: Sensitive files that weren't caught + +- **Missing Patterns**: New file types that should be protected + +- **Overly Strict**: Patterns that are too restrictive + +- **Documentation Gaps**: Missing guidance for specific change types + +- **Testing Improvements**: Better validation procedures + +### Feedback Reporting + +When reporting guard issues, include: + +- **File patterns** that triggered false positives/negatives + +- **Build system changes** that weren't properly caught + +- **Documentation gaps** in current guard rules + +- **Testing procedures** that could be improved + +- **User experience** issues with guard enforcement + +--- + +**See also**: + +- `.cursor/rules/architecture/build_architecture_guard.mdc` for + + core protection guidelines + +- `.cursor/rules/architecture/build_validation.mdc` for validation procedures + +**Status**: Active testing requirements +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: build_architecture_guard.mdc, build_validation.mdc +**Stakeholders**: Development team, DevOps team, Build team + +## Model Implementation Checklist + +### Before Build Testing + +- [ ] **Test Planning**: Plan comprehensive testing strategy for build changes +- [ ] **Platform Coverage**: Identify all platforms that need testing +- [ ] **Risk Assessment**: Assess testing risks and mitigation strategies +- [ ] **Resource Planning**: Plan testing resources and time requirements + +### During Build Testing + +- [ ] **Test Execution**: Execute planned tests across all platforms +- [ ] **Issue Tracking**: Track and document any issues found +- [ ] **Feedback Collection**: Collect feedback on testing effectiveness +- [ ] **Documentation**: Document testing procedures and results + +### After Build Testing + +- [ ] **Result Analysis**: Analyze testing results and identify patterns +- [ ] **Feedback Integration**: Integrate feedback into testing procedures +- [ ] **Process Improvement**: Update testing procedures based on feedback +- [ ] **Team Communication**: Share testing results and improvements with team diff --git a/.cursor/rules/architecture/build_validation.mdc b/.cursor/rules/architecture/build_validation.mdc new file mode 100644 index 0000000..da78c63 --- /dev/null +++ b/.cursor/rules/architecture/build_validation.mdc @@ -0,0 +1,224 @@ +# Build Validation — Procedures and Requirements + +> **Agent role**: Reference this file for + detailed validation procedures when working with build architecture changes. + +## Required Validation Checklist + +### Before Any Build System Change + +- [ ] **Impact Assessment**: Which platforms are affected? + +- [ ] **Testing Plan**: How will this be tested across platforms? + +- [ ] **Rollback Plan**: How can this be reverted if it breaks? + +- [ ] **Documentation**: Will `BUILDING.md` need updates? + +- [ ] **Dependencies**: Are all required tools available? + +### After Build System Change + +- [ ] **Web Platform**: Does `npm run build:web:dev` work? + +- [ ] **Mobile Platforms**: Do iOS/Android builds succeed? + +- [ ] **Desktop Platform**: Does Electron build and run? + +- [ ] **Tests Pass**: Do all build-related tests pass? + +- [ ] **Documentation Updated**: Is `BUILDING.md` current? + +## Specific Test Commands (Minimum Required) + +### Web Platform + +- **Development**: `npm run build:web:dev` - serve and load app + +- **Production**: `npm run build:web:prod` - verify SW and WASM present + +### Mobile Platforms + +- **Android**: `npm run build:android:test` or `:prod` - confirm assets copied + +- **iOS**: `npm run build:ios:test` or `:prod` - verify build succeeds + +### Android Platform (Enhanced) + +- **Development Mode**: `npm run build:android --dev` - + + verify 10.0.2.2 API routing + +- **Custom IP Mode**: `npm run build:android --dev --api-ip 192.168.1.100` - + + verify custom IP + +- **Asset Validation**: `npm run build:android --assets` - + + verify resource generation + +- **Deploy Mode**: `npm run build:android --deploy` - verify device deployment + +### Desktop Platform + +- **Electron**: `npm run build:electron:dev` and packaging for target OS + +- **Verify**: Single-instance behavior and app boot + +### Auto-run (if affected) + +- **Test Mode**: `npm run auto-run:test` and platform variants + +- **Production Mode**: `npm run auto-run:prod` and platform variants + +### Clean and Rebuild + +- Run relevant `clean:*` scripts and ensure re-build works + +## Risk Matrix & Required Validation + +### Environment Handling + +- **Trigger**: Change to `.env.*` loading / variable names + +- **Validation**: Prove `dev/test/prod` builds; show environment echo in logs + +### Script Flow + +- **Trigger**: Reorder steps (prebuild → build → package), new flags + +- **Validation**: Dry-run + normal run, show exit codes & timing + +### Platform Packaging + +- **Trigger**: Electron NSIS/DMG/AppImage, Android/iOS bundle + +- **Validation**: Produce installer/artifact and open it; + + verify single-instance, + icons, signing + +### Service Worker / WASM + +- **Trigger**: `sw_combine.js`, WASM copy path + +- **Validation**: Verify combined SW exists and is injected; page loads offline; + + WASM present + +### Docker + +- **Trigger**: New base image, build args + +- **Validation**: Build image locally; run container; list produced `/dist` + +### Android Asset Management + +- **Trigger**: Changes to `validate_android_assets()` function or resource paths + +- **Validation**: + + Run `npm run build:android --assets` and verify all mipmap/drawable resources + +- **Risk**: Missing splash screens or app icons causing build failures + +### Android API Routing + +- **Trigger**: Changes to Android-specific API server IP logic + +- **Validation**: Test both emulator (10.0.2.2) and custom IP modes + +- **Risk**: API connectivity failures on different device types + +### Signing/Notarization + +- **Trigger**: Cert path/profiles + +- **Validation**: Show signing logs + verify on target OS + +## PR Template (Paste into Description) + +- [ ] **Level**: L1 / L2 / L3 + justification + +- [ ] **Files & platforms touched**: + +- [ ] **Risk triggers & mitigations**: + +- [ ] **Commands run (paste logs)**: + +- [ ] **Artifacts (names + sha256)**: + +- [ ] **Docs updated (sections/links)**: + +- [ ] **Rollback steps verified**: + +- [ ] **CI**: Jobs passing and artifacts uploaded + +## ADR Trigger List + +Raise an ADR when you propose any of: + +- **New build stage** or reorder of canonical stages + +- **Replacement of packager** / packaging format + +- **New environment model** or secure secret handling scheme + +- **New service worker assembly** strategy or cache policy + +- **New Docker base** or multi-stage pipeline + +- **Relocation of build outputs** or directory conventions + +- **New Android build modes** or argument parsing logic + +- **Changes to asset validation** or resource generation strategy + +- **Modifications to platform-specific API routing** ( + + Android emulator vs physical) + +- **New Android deployment strategies** or device management + +**ADR must include**: + motivation, alternatives, risks, validation plan, rollback, + doc diffs. + +--- + +**See also**: + +- `.cursor/rules/architecture/build_architecture_guard.mdc` for + + core protection guidelines + +- `.cursor/rules/architecture/build_testing.mdc` for testing requirements + +**Status**: Active validation procedures +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: build_architecture_guard.mdc +**Stakeholders**: Development team, DevOps team, Build team + +## Model Implementation Checklist + +### Before Build Changes + +- [ ] **Level Assessment**: Determine build validation level (L1/L2/L3) +- [ ] **Platform Analysis**: Identify all platforms affected by changes +- [ ] **Risk Assessment**: Identify risk triggers and mitigation strategies +- [ ] **Rollback Planning**: Plan rollback steps for build failures + +### During Build Implementation + +- [ ] **Validation Commands**: Run appropriate validation commands for level +- [ ] **Platform Testing**: Test changes across all affected platforms +- [ ] **Risk Mitigation**: Implement identified risk mitigation strategies +- [ ] **Documentation**: Document all commands run and their outputs + +### After Build Implementation + +- [ ] **Artifact Validation**: Verify build artifacts are correct and accessible +- [ ] **CI Verification**: Ensure CI jobs pass and artifacts are uploaded +- [ ] **Documentation Update**: Update relevant documentation sections +- [ ] **Team Communication**: Share build validation results with team diff --git a/.cursor/rules/core/base_context.mdc b/.cursor/rules/core/base_context.mdc new file mode 100644 index 0000000..a1ad4bc --- /dev/null +++ b/.cursor/rules/core/base_context.mdc @@ -0,0 +1,217 @@ +--- +alwaysApply: false +--- +```json + +{ + "coaching_level": "standard", + "socratic_max_questions": 7, + "verbosity": "normal", + "timebox_minutes": null, + "format_enforcement": "strict" +} + +``` + +# Base Context — Human Competence First + +**Author**: Matthew Raymer +**Date**: 2025-08-19 +**Status**: 🎯 **ACTIVE** - Core interaction guidelines + +## Purpose + +All interactions must *increase the human's competence over time* while +completing the task efficiently. The model may handle menial work and memory +extension, but must also promote learning, autonomy, and healthy work habits. +The model should also **encourage human interaction and collaboration** rather +than replacing it — outputs should be designed to **facilitate human discussion, +decision-making, and creativity**, not to atomize tasks into isolated, purely +machine-driven steps. + +## Principles + +1. Competence over convenience: finish the task *and* leave the human more + + capable next time. + +2. Mentorship, not lectures: be concise, concrete, and immediately applicable. + +3. Transparency: show assumptions, limits, and uncertainty; cite when + + non-obvious. + +4. Optional scaffolding: include small, skimmable learning hooks that do not + + bloat output. + +5. Time respect: default to **lean output**; offer opt-in depth via toggles. + +6. Psychological safety: encourage, never condescend; no medical/clinical + advice. No censorship! +7. Reusability: structure outputs so they can be saved, searched, reused, and + repurposed. +8. **Collaborative Bias**: Favor solutions that invite human review, + discussion, and iteration. When in doubt, ask "Who should this be shown + to?" or "Which human input would improve this?" + +## Toggle Definitions + +### coaching_level + +Determines the depth of learning support: `light` (short hooks), +`standard` (balanced), `deep` (detailed). + +### socratic_max_questions + +The number of clarifying questions the model may ask before proceeding. +If >0, questions should be targeted, minimal, and followed by reasonable +assumptions if unanswered. + +### verbosity + +'terse' (just a sentence), `concise` (minimum commentary), `normal` +(balanced explanation), or other project-defined levels. + +### timebox_minutes + +*integer or null* — When set to a positive integer (e.g., `5`), this acts +as a **time budget** guiding the model to prioritize delivering the most +essential parts of the task within that constraint. + +Behavior when set: + +1. **Prioritize Core Output** — Deliver the minimum viable solution or + + result first. + +2. **Limit Commentary** — Competence Hooks and Collaboration Hooks must be + + shorter than normal. + +3. **Signal Skipped Depth** — Omitted details should be listed under + + *Deferred for depth*. + +4. **Order by Value** — Start with blocking or high-value items, then + + proceed to nice-to-haves if budget allows. + +If `null`, there is no timebox — the model can produce full-depth +responses. + +### format_enforcement + +`strict` (reject outputs with format drift) or `relaxed` (minor deviations +acceptable). + +## Modes (select or combine) + +- **Doer**: produce the artifact fast, minimal commentary. + +- **Mentor**: add short "why/how" notes + next-step pointers. + +- **Socratic**: ask up to N targeted questions when requirements are + + ambiguous. + +- **Pair-Programmer/Pair-Writer**: explain tradeoffs as you implement. + +- **Facilitator**: structure output to be reviewable, commentable, and + + ready for group discussion. + +Default: Doer + short Mentor notes. + +## Competence & Collaboration Levers (keep lightweight) + +- "Why this works" (≤3 bullets) + +- "Common pitfalls" (≤3 bullets) + +- "Next skill unlock" (1 tiny action or reading) + +- "Teach-back" (1 sentence prompt the human can answer to self-check) + +- "Discussion prompts" (≤2 short questions for peers/stakeholders) + +## Output Contract (apply to every deliverable) + +- Clear **Objective** (1 line) + +- **Result** (artifact/code/answer) + +- **Use/Run** (how to apply/test) + +- **Competence Hooks** (the 4 learning levers above, kept terse) + +- **Collaboration Hooks** (discussion prompts or group review steps) + +- **Assumptions & Limits** + +- **References** (if used; links or titles) + +## Do-Not + +- No filler, hedging, or moralizing. + +- No medical/mental-health advice; keep "healthy habits" to general work + + practices. + +- No invented facts; mark uncertainty plainly. + +- No censorship. + +- Avoid outputs that bypass human review when such review is valuable. + +## Related Rulesets + +- **software_development.mdc**: For software-specific development practices + +- **research_diagnostic.mdc**: For investigation and research workflows + +## Model Implementation Checklist + +### Before Responding + +- [ ] **Toggle Review**: Check coaching_level, socratic_max_questions, verbosity, + timebox_minutes +- [ ] **Mode Selection**: Choose appropriate mode(s) for the task +- [ ] **Scope Understanding**: Clarify requirements and constraints +- [ ] **Context Analysis**: Review relevant rulesets and dependencies + +### During Response Creation + +- [ ] **Output Contract**: Include all required sections (Objective, Result, + Use/Run, etc.) +- [ ] **Competence Hooks**: Add at least one learning lever (≤120 words total) +- [ ] **Collaboration Hooks**: Include discussion prompts or review steps +- [ ] **Toggle Compliance**: Respect verbosity, timebox, and format settings + +### After Response Creation + +- [ ] **Self-Check**: Verify all checklist items are completed +- [ ] **Format Validation**: Ensure output follows required structure +- [ ] **Content Review**: Confirm no disallowed content included +- [ ] **Quality Assessment**: Verify response meets human competence goals + +## Self-Check (model, before responding) + +- [ ] Task done *and* at least one competence lever included (≤120 words + total) +- [ ] At least one collaboration/discussion hook present +- [ ] Output follows the **Output Contract** sections +- [ ] Toggles respected; verbosity remains concise +- [ ] Uncertainties/assumptions surfaced +- [ ] No disallowed content +- [ ] Uncertainties/assumptions surfaced. +- [ ] No disallowed content. + +--- + +**Status**: Active core guidelines +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: None (base ruleset) +**Stakeholders**: All AI interactions diff --git a/.cursor/rules/core/harbor_pilot_universal.mdc b/.cursor/rules/core/harbor_pilot_universal.mdc new file mode 100644 index 0000000..4f1da0f --- /dev/null +++ b/.cursor/rules/core/harbor_pilot_universal.mdc @@ -0,0 +1,202 @@ +```json + +{ + "coaching_level": "standard", + "socratic_max_questions": 2, + "verbosity": "concise", + "timebox_minutes": 10, + "format_enforcement": "strict" +} + +``` + +# Harbor Pilot Universal — Technical Guide Standards + +> **Agent role**: When creating technical guides, reference documents, or +> implementation plans, apply these universal directives to ensure consistent +> quality and structure. + +## Purpose + +- **Purpose fit**: Prioritizes human competence and collaboration while + delivering reproducible artifacts. + +- **Output Contract**: This directive **adds universal constraints** for any + technical topic while **inheriting** the Base Context contract sections. + +- **Toggles honored**: Uses the same toggle semantics; defaults above can be + overridden by the caller. + +## Core Directive + +Produce a **developer-grade, reproducible guide** for any technical topic +that onboards a competent practitioner **without meta narration** and **with +evidence-backed steps**. + +## Required Elements + +### 1. Time & Date Standards + +- Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid + "today/yesterday". + +- Include at least **one diagram** (Mermaid preferred). Choose the most + fitting type: + + - `sequenceDiagram` (protocols/flows), `flowchart`, `stateDiagram`, + `gantt` (timelines), or `classDiagram` (schemas). + +### 2. Evidence Requirements + +- **Reproducible Steps**: Every claim must have copy-paste commands + +- **Verifiable Outputs**: Include expected results, status codes, or + error messages + +- **Cite evidence** for *Works/Doesn't* items (timestamps, filenames, + line numbers, IDs/status codes, or logs). + +## Required Sections + +Follow this exact order **after** the Base Contract's **Objective → Result +→ Use/Run** headers: + +1. **Artifacts & Links** - Repos/PRs, design docs, datasets/HARs/pcaps, + scripts/tools, dashboards. + +2. **Environment & Preconditions** - OS/runtime, versions/build IDs, + services/endpoints/URLs, credentials/auth mode. + +3. **Architecture / Process Overview** - Short prose + **one diagram** + selected from the list above. + +4. **Interfaces & Contracts** - Choose one: API-based (endpoint table), + Data/Files (I/O contract), or Systems/Hardware (interfaces). + +5. **Repro: End-to-End Procedure** - Minimal copy-paste steps with + code/commands and **expected outputs**. +6. **What Works (with Evidence)** - Each item: **Time (UTC)** • + **Artifact/Req IDs** • **Status/Result** • **Where to verify**. +7. **What Doesn't (Evidence & Hypotheses)** - Each failure: locus, + evidence snippet; short hypothesis and **next probe**. +8. **Risks, Limits, Assumptions** - SLOs/limits, rate/size caps, + security boundaries, retries/backoff/idempotency patterns. +9. **Next Steps (Owner • Exit Criteria • Target Date)** - Actionable, + assigned, and time-bound. + +## Quality Standards + +### Do + +- **Do** quantify progress only against a defined scope with acceptance + criteria. + +- **Do** include minimal sample payloads/headers or I/O schemas; redact + sensitive values. + +- **Do** keep commentary lean; if timeboxed, move depth to **Deferred + for depth**. + +- **Do** use specific, actionable language that guides implementation. + +### Don't + +- **Don't** use marketing language or meta narration ("Perfect!", + "tool called", "new chat"). + +- **Don't** include IDE-specific chatter or internal rules unrelated to + the task. + +- **Don't** assume reader knowledge; provide context for all technical + decisions. + +## Model Implementation Checklist + +### Before Creating Technical Guides + +- [ ] **Scope Definition**: Clearly define problem, audience, and scope +- [ ] **Evidence Collection**: Gather specific timestamps, file references, and logs +- [ ] **Diagram Planning**: Plan appropriate diagram type for the technical process +- [ ] **Template Selection**: Choose relevant sections from required sections list + +### During Guide Creation + +- [ ] **Evidence Integration**: Include UTC timestamps and verifiable evidence +- [ ] **Diagram Creation**: Create Mermaid diagram that illustrates the process +- [ ] **Repro Steps**: Write copy-paste ready commands with expected outputs +- [ ] **Section Completion**: Fill in all required sections completely + +### After Guide Creation + +- [ ] **Validation**: Run through the validation checklist below +- [ ] **Evidence Review**: Verify all claims have supporting evidence +- [ ] **Repro Testing**: Test reproduction steps to ensure they work +- [ ] **Peer Review**: Share with technical leads for feedback + +## Validation Checklist + +Before publishing, verify: + +- [ ] **Diagram included** and properly formatted (Mermaid syntax valid) +- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for + each endpoint +- [ ] **Environment section** includes all required dependencies and + versions +- [ ] Every Works/Doesn't item has **UTC timestamp**, **status/result**, + and **verifiable evidence** +- [ ] **Repro steps** are copy-paste ready with expected outputs +- [ ] Base **Output Contract** sections satisfied + (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References) + +## Integration Points + +### Base Context Integration + +- Apply historical comment management rules (see + + `.cursor/rules/development/historical_comment_management.mdc`) + +- Apply realistic time estimation rules (see + + `.cursor/rules/development/realistic_time_estimation.mdc`) + +### Competence Hooks + +- **Why this works**: Structured approach ensures completeness and + reproducibility + +- **Common pitfalls**: Skipping evidence requirements, vague language + +- **Next skill unlock**: Practice creating Mermaid diagrams for different + use cases + +- **Teach-back**: Explain how you would validate this guide's + reproducibility + +### Collaboration Hooks + +- **Reviewers**: Technical leads, subject matter experts + +- **Stakeholders**: Development teams, DevOps, QA teams + +--- + +**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human +Competence First* + +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: base_context.mdc +**Stakeholders**: All AI interactions, Development teams + +## Example Diagram Template + +```mermaid + + + +``` + +**Note**: Replace the placeholder with an actual diagram that illustrates +the technical process, architecture, or workflow being documented. diff --git a/.cursor/rules/core/less_complex.mdc b/.cursor/rules/core/less_complex.mdc new file mode 100644 index 0000000..6c5ca71 --- /dev/null +++ b/.cursor/rules/core/less_complex.mdc @@ -0,0 +1,99 @@ + +alwaysApply: false + +--- + +# Minimalist Solution Principle (Cursor MDC) + +role: Engineering assistant optimizing for least-complex changes +focus: Deliver the smallest viable diff that fully resolves the current +bug/feature. Defer generalization unless justified with evidence. +language: Match repository languages and conventions + +## Rules + +1. **Default to the least complex solution.** Fix the problem directly + where it occurs; avoid new layers, indirection, or patterns unless + strictly necessary. +2. **Keep scope tight.** Implement only what is needed to satisfy the + acceptance criteria and tests for *this* issue. +3. **Avoid speculative abstractions.** Use the **Rule of Three**: + don't extract helpers/patterns until the third concrete usage proves + the shape. +4. **No drive-by refactors.** Do not rename, reorder, or reformat + unrelated code in the same change set. +5. **Minimize surface area.** Prefer local changes over cross-cutting + rewires; avoid new public APIs unless essential. +6. **Be dependency-frugal.** Do not add packages or services for + single, simple needs unless there's a compelling, documented reason. +7. **Targeted tests only.** Add the smallest set of tests that prove + the fix and guard against regression; don't rewrite suites. +8. **Document the "why enough."** Include a one-paragraph note + explaining why this minimal solution is sufficient *now*. + +## Future-Proofing Requires Evidence + Discussion + +Any added complexity "for the future" **must** include: + +- A referenced discussion/ADR (or issue link) summarizing the decision. +- **Substantial evidence**, e.g.: + - Recurring incidents or tickets that this prevents (list IDs). + - Benchmarks or profiling showing a real bottleneck. + - Concrete upcoming requirements with dates/owners, not hypotheticals. + - Risk assessment comparing maintenance cost vs. expected benefit. +- A clear trade-off table showing why minimal won't suffice. + +If this evidence is not available, **ship the minimal fix** and open a +follow-up discussion item. + +## PR / Change Checklist (enforced by reviewer + model) + +- [ ] Smallest diff that fully fixes the issue (attach `git diff --stat` + if useful). +- [ ] No unrelated refactors or formatting. +- [ ] No new dependencies, or justification + ADR link provided. +- [ ] Abstractions only if ≥3 call sites or strong evidence says + otherwise (cite). +- [ ] Targeted tests proving the fix/regression guard. +- [ ] Short "Why this is enough now" note in the PR description. +- [ ] Optional: "Future Work (non-blocking)" section listing deferred + ideas. + +## Assistant Output Contract + +When proposing a change, provide: + +1. **Minimal Plan**: 3–6 bullet steps scoped to the immediate fix. +2. **Patch Sketch**: Focused diffs/snippets touching only necessary + files. +3. **Risk & Rollback**: One paragraph each on risk, quick rollback, + and test points. +4. **(If proposing complexity)**: Link/inline ADR summary + evidence + + trade-offs; otherwise default to minimal. + + One paragraph each on risk, quick rollback, and test points. +5. **(If proposing complexity)**: Link/inline ADR summary + evidence + + trade-offs; otherwise default to minimal. + +## Model Implementation Checklist + +### Before Proposing Changes + +- [ ] **Problem Analysis**: Clearly understand the specific issue scope +- [ ] **Evidence Review**: Gather evidence that justifies the change +- [ ] **Complexity Assessment**: Evaluate if change requires added complexity +- [ ] **Alternative Research**: Consider simpler solutions first + +### During Change Design + +- [ ] **Minimal Scope**: Design solution that addresses only the current issue +- [ ] **Evidence Integration**: Include specific evidence for any complexity +- [ ] **Dependency Review**: Minimize new dependencies and packages +- [ ] **Testing Strategy**: Plan minimal tests that prove the fix + +### After Change Design + +- [ ] **Self-Review**: Verify solution follows minimalist principles +- [ ] **Evidence Validation**: Confirm all claims have supporting evidence +- [ ] **Complexity Justification**: Document why minimal approach suffices +- [ ] **Future Work Planning**: Identify deferred improvements for later diff --git a/.cursor/rules/database/absurd-sql.mdc b/.cursor/rules/database/absurd-sql.mdc new file mode 100644 index 0000000..9f959df --- /dev/null +++ b/.cursor/rules/database/absurd-sql.mdc @@ -0,0 +1,273 @@ +--- +globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts, + **/src/registerSQLWorker.js, **/ +services/AbsurdSqlDatabaseService.ts +alwaysApply: false +--- + +# Absurd SQL - Cursor Development Guide + +**Author**: Matthew Raymer +**Date**: 2025-08-19 +**Status**: 🎯 **ACTIVE** - Database development guidelines + +## Project Overview + +Absurd SQL is a backend implementation for sql.js that enables persistent +SQLite databases in the browser by using IndexedDB as a block storage system. +This guide provides rules and best practices for developing with this project +in Cursor. + +## Project Structure + +``` + +absurd-sql/ +├── src/ # Source code +├── dist/ # Built files +├── package.json # Dependencies and scripts +├── rollup.config.js # Build configuration +└── jest.config.js # Test configuration + +``` + +## Development Rules + +### 1. Worker Thread Requirements + +- All SQL operations MUST be performed in a worker thread + +- Main thread should only handle worker initialization and communication + +- Never block the main thread with database operations + +### 2. Code Organization + +- Keep worker code in separate files (e.g., `*.worker.js`) + +- Use ES modules for imports/exports + +- Follow the project's existing module structure + +### 3. Required Headers + +When developing locally or deploying, ensure these headers are set: + +``` + +Cross-Origin-Opener-Policy: same-origin +Cross-Origin-Embedder-Policy: require-corp + +``` + +### 4. Browser Compatibility + +- Primary target: Modern browsers with SharedArrayBuffer support + +- Fallback mode: Safari (with limitations) + +- Always test in both modes + +### 5. Database Configuration + +Recommended database settings: + +```sql + +PRAGMA journal_mode=MEMORY; +PRAGMA page_size=8192; -- Optional, but recommended + +``` + +### 6. Development Workflow + +1. Install dependencies: + + ```bash + + yarn add @jlongster/sql.js absurd-sql + + ``` + +2. Development commands: + + - `yarn build` - Build the project + + - `yarn jest` - Run tests + + - `yarn serve` - Start development server + +### 7. Testing Guidelines + +- Write tests for both SharedArrayBuffer and fallback modes + +- Use Jest for testing + +- Include performance benchmarks for critical operations + +### 8. Performance Considerations + +- Use bulk operations when possible + +- Monitor read/write performance + +- Consider using transactions for multiple operations + +- Avoid unnecessary database connections + +### 9. Error Handling + +- Implement proper error handling for: + + - Worker initialization failures + + - Database connection issues + + - Concurrent access conflicts (in fallback mode) + + - Storage quota exceeded scenarios + +### 10. Security Best Practices + +- Never expose database operations directly to the client + +- Validate all SQL queries + +- Implement proper access controls + +- Handle sensitive data appropriately + +### 11. Code Style + +- Follow ESLint configuration + +- Use async/await for asynchronous operations + +- Document complex database operations + +- Include comments for non-obvious optimizations + +### 12. Debugging + +- Use `jest-debug` for debugging tests + +- Monitor IndexedDB usage in browser dev tools + +- Check worker communication in console + +- Use performance monitoring tools + +## Common Patterns + +### Worker Initialization + +```javascript + +// Main thread +import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread'; + +function init() { + let worker = new Worker(new URL('./index.worker.js', import.meta.url)); + initBackend(worker); +} + +``` + +### Database Setup + +```javascript + +// Worker thread +import initSqlJs from '@jlongster/sql.js'; +import { SQLiteFS } from 'absurd-sql'; +import IndexedDBBackend from 'absurd-sql/dist/indexeddb-backend'; + +async function setupDatabase() { + let SQL = await initSqlJs({ locateFile: file => file }); + let sqlFS = new SQLiteFS(SQL.FS, new IndexedDBBackend()); + SQL.register_for_idb(sqlFS); + + SQL.FS.mkdir('/sql'); + SQL.FS.mount(sqlFS, {}, '/sql'); + + return new SQL.Database('/sql/db.sqlite', { filename: true }); +} + +``` + +## Troubleshooting + +### Common Issues + +1. SharedArrayBuffer not available + + - Check COOP/COEP headers + + - Verify browser support + + - Test fallback mode + +2. Worker initialization failures + + - Check file paths + + - Verify module imports + + - Check browser console for errors + +3. Performance issues + + - Monitor IndexedDB usage + + - Check for unnecessary operations + + - Verify transaction usage + +## Resources + +- [Project Demo](https://priceless-keller-d097e5.netlify.app/) + +- [Example Project](https://github.com/jlongster/absurd-example-project) + +- [Blog Post](https://jlongster.com/future-sql-web) + +- [SQL.js Documentation](https://github.com/sql-js/sql.js/) + +--- + +**Status**: Active database development guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: Absurd SQL, SQL.js, IndexedDB +**Stakeholders**: Development team, Database team + +- [Project Demo](https://priceless-keller-d097e5.netlify.app/) + +- [Example Project](https://github.com/jlongster/absurd-example-project) + +- [Blog Post](https://jlongster.com/future-sql-web) + +- [SQL.js Documentation](https://github.com/sql-js/sql.js/) + +## Model Implementation Checklist + +### Before Absurd SQL Implementation + +- [ ] **Browser Support**: Verify SharedArrayBuffer and COOP/COEP support +- [ ] **Worker Setup**: Plan worker thread initialization and communication +- [ ] **Database Planning**: Plan database schema and initialization +- [ ] **Performance Planning**: Plan performance monitoring and optimization + +### During Absurd SQL Implementation + +- [ ] **Worker Initialization**: Set up worker threads with proper communication +- [ ] **Database Setup**: Initialize SQLite database with IndexedDB backend +- [ ] **File System**: Configure SQLiteFS with proper mounting +- [ ] **Error Handling**: Implement proper error handling for worker failures + +### After Absurd SQL Implementation + +- [ ] **Cross-Browser Testing**: Test across different browsers and devices +- [ ] **Performance Validation**: Monitor IndexedDB usage and performance +- [ ] **Worker Validation**: Verify worker communication and database operations +- [ ] **Documentation**: Update Absurd SQL implementation documentation diff --git a/.cursor/rules/database/legacy_dexie.mdc b/.cursor/rules/database/legacy_dexie.mdc new file mode 100644 index 0000000..ffb9e8f --- /dev/null +++ b/.cursor/rules/database/legacy_dexie.mdc @@ -0,0 +1,62 @@ +# Legacy Dexie Database — Migration Guidelines + +> **Agent role**: Reference this file when working with legacy Dexie +> database code or migration patterns. + +## Overview + +All references in the codebase to Dexie apply only to migration from +IndexedDb to Absurd SQL. Dexie is no longer used for new development. + +## Migration Status + +- **Legacy Code**: Existing Dexie implementations being migrated +- **Target**: Absurd SQL with IndexedDB backend +- **Timeline**: Gradual migration as features are updated + +## Key Principles + +- **No New Dexie**: All new database operations use Absurd SQL +- **Migration Path**: Legacy code should be migrated when updated +- **Backward Compatibility**: Maintain existing functionality during + migration + +## Integration Points + +- Apply these rules when updating database-related code +- Use during feature development and refactoring +- Include in database architecture decisions + +--- + +**Status**: Legacy migration guidelines +**Priority**: Low +**Estimated Effort**: Ongoing reference +**Dependencies**: absurd-sql.mdc +**Stakeholders**: Database team, Development team + +All references in the codebase to Dexie apply only to migration from IndexedDb +to Sqlite and will be deprecated in future versions. + +## Model Implementation Checklist + +### Before Legacy Dexie Work + +- [ ] **Migration Analysis**: Identify legacy Dexie code that needs migration +- [ ] **Target Planning**: Plan migration to Absurd SQL with IndexedDB backend +- [ ] **Backward Compatibility**: Plan to maintain existing functionality +- [ ] **Testing Strategy**: Plan testing approach for migration + +### During Legacy Dexie Migration + +- [ ] **No New Dexie**: Ensure no new Dexie code is introduced +- [ ] **Migration Implementation**: Implement migration to Absurd SQL +- [ ] **Functionality Preservation**: Maintain existing functionality during migration +- [ ] **Error Handling**: Implement proper error handling for migration + +### After Legacy Dexie Migration + +- [ ] **Functionality Testing**: Verify all functionality still works correctly +- [ ] **Performance Validation**: Ensure performance meets or exceeds legacy +- [ ] **Documentation Update**: Update database documentation +- [ ] **Legacy Cleanup**: Remove deprecated Dexie code diff --git a/.cursor/rules/development/asset_configuration.mdc b/.cursor/rules/development/asset_configuration.mdc new file mode 100644 index 0000000..a53e9ff --- /dev/null +++ b/.cursor/rules/development/asset_configuration.mdc @@ -0,0 +1,105 @@ +--- +description: when doing anything with capacitor assets +alwaysApply: false +--- + +# Asset Configuration Directive + +**Author**: Matthew Raymer +**Date**: 2025-08-19 +**Status**: 🎯 **ACTIVE** - Asset management guidelines + +*Scope: Assets Only (icons, splashes, image pipelines) — not overall build +orchestration* + +## Intent + +- Version **asset configuration files** (optionally dev-time generated). + +- **Do not** version platform asset outputs (Android/iOS/Electron); generate + + them **at build-time** with standard tools. + +- Keep existing per-platform build scripts unchanged. + +## Source of Truth + +- **Preferred (Capacitor default):** `resources/` as the single master source. + +- **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is + + explicitly configured to read from it. + +- **Never** maintain both `resources/` and `assets/` as parallel sources. + + Migrate and delete the redundant folder. + +## Config Files + +- Live under: `config/assets/` (committed). + +- Examples: + + - `config/assets/capacitor-assets.config.json` (or the path the tool + + expects) + + - `config/assets/android.assets.json` + + - `config/assets/ios.assets.json` + + - `config/assets/common.assets.yaml` (optional shared layer) + +- **Dev-time generation allowed** for these configs; **build-time + + generation is forbidden**. + +## Build-Time Behavior + +- Build generates platform assets (not configs) using the standard chain: + +```bash + +npm run build:capacitor # web build via Vite (.mts) +npx cap sync +npx capacitor-assets generate # produces platform assets; not committed + +# then platform-specific build steps + +``` + +--- + +**Status**: Active asset management directive +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: capacitor-assets toolchain +**Stakeholders**: Development team, Build team + + npx capacitor-assets generate # produces platform assets; not committed + +# then platform-specific build steps + +## Model Implementation Checklist + +### Before Asset Configuration + +- [ ] **Source Review**: Identify current asset source location (`resources/` or + `assets/`) +- [ ] **Tool Assessment**: Verify capacitor-assets toolchain is available +- [ ] **Config Planning**: Plan configuration file structure and location +- [ ] **Platform Analysis**: Understand asset requirements for all target platforms + +### During Asset Configuration + +- [ ] **Source Consolidation**: Ensure single source of truth (prefer `resources/`) +- [ ] **Config Creation**: Create platform-specific asset configuration files +- [ ] **Tool Integration**: Configure capacitor-assets to read from correct source +- [ ] **Build Integration**: Integrate asset generation into build pipeline + +### After Asset Configuration + +- [ ] **Build Testing**: Verify assets generate correctly at build time +- [ ] **Platform Validation**: Test asset generation across all platforms +- [ ] **Documentation**: Update build documentation with asset generation steps +- [ ] **Team Communication**: Communicate asset workflow changes to team diff --git a/.cursor/rules/development/complexity_assessment.mdc b/.cursor/rules/development/complexity_assessment.mdc new file mode 100644 index 0000000..02b9756 --- /dev/null +++ b/.cursor/rules/development/complexity_assessment.mdc @@ -0,0 +1,177 @@ +# Complexity Assessment — Evaluation Frameworks + +> **Agent role**: Reference this file for + complexity evaluation frameworks when assessing project complexity. + +## 📊 Complexity Assessment Framework + +### **Technical Complexity Factors** + +#### **Code Changes** + +- **Simple**: Text, styling, configuration updates + +- **Medium**: New components, refactoring existing code + +- **Complex**: Architecture changes, new patterns, integrations + +- **Unknown**: New technologies, APIs, or approaches + +#### **Platform Impact** + +- **Single platform**: Web-only or mobile-only changes + +- **Two platforms**: Web + mobile or web + desktop + +- **Three platforms**: Web + mobile + desktop + +- **Cross-platform consistency**: Ensuring behavior matches across all platforms + +#### **Testing Requirements** + +- **Basic**: Unit tests for new functionality + +- **Comprehensive**: Integration tests, cross-platform testing + +- **User acceptance**: User testing, feedback integration + +- **Performance**: Load testing, optimization validation + +### **Dependency Complexity** + +#### **Internal Dependencies** + +- **Low**: Self-contained changes, no other components affected + +- **Medium**: Changes affect related components or services + +- **High**: Changes affect core architecture or multiple systems + +- **Critical**: Changes affect data models or core business logic + +#### **External Dependencies** + +- **None**: No external services or APIs involved + +- **Low**: Simple API calls or service integrations + +- **Medium**: Complex integrations with external systems + +- **High**: Third-party platform dependencies or complex APIs + +#### **Infrastructure Dependencies** + +- **None**: No infrastructure changes required + +- **Low**: Configuration updates or environment changes + +- **Medium**: New services or infrastructure components + +- **High**: Platform migrations or major infrastructure changes + +## 🔍 Complexity Evaluation Process + +### **Step 1: Technical Assessment** + +1. **Identify scope of changes** - what files/components are affected + +2. **Assess platform impact** - which platforms need updates + +3. **Evaluate testing needs** - what testing is required + +4. **Consider performance impact** - will this affect performance + +### **Step 2: Dependency Mapping** + +1. **Map internal dependencies** - what other components are affected + +2. **Identify external dependencies** - what external services are involved + +3. **Assess infrastructure needs** - what infrastructure changes are required + +4. **Evaluate risk factors** - what could go wrong + +### **Step 3: Complexity Classification** + +1. **Assign complexity levels** to each factor + +2. **Identify highest complexity** areas that need attention + +3. **Plan mitigation strategies** for high-complexity areas + +4. **Set realistic expectations** based on complexity assessment + +## 📋 Complexity Assessment Checklist + +- [ ] Technical scope identified and mapped + +- [ ] Platform impact assessed across all targets + +- [ ] Testing requirements defined and planned + +- [ ] Internal dependencies mapped and evaluated + +- [ ] External dependencies identified and assessed + +- [ ] Infrastructure requirements evaluated + +- [ ] Risk factors identified and mitigation planned + +- [ ] Complexity levels assigned to all factors + +- [ ] Realistic expectations set based on assessment + +## 🎯 Complexity Reduction Strategies + +### **Scope Reduction** + +- Break large features into smaller, manageable pieces + +- Focus on core functionality first, add polish later + +- Consider phased rollout to reduce initial complexity + +### **Dependency Management** + +- Minimize external dependencies when possible + +- Use abstraction layers to isolate complex integrations + +- Plan for dependency failures and fallbacks + +### **Testing Strategy** + +- Start with basic testing and expand coverage + +- Use automated testing to reduce manual testing complexity + +- Plan for iterative testing and feedback cycles + +## **See also** + +- `.cursor/rules/development/realistic_time_estimation.mdc` for the core principles + +- `.cursor/rules/development/planning_examples.mdc` for planning examples + +## Model Implementation Checklist + +### Before Complexity Assessment + +- [ ] **Problem Scope**: Clearly define the problem to be assessed +- [ ] **Stakeholder Identification**: Identify all parties affected by complexity +- [ ] **Context Analysis**: Understand technical and business context +- [ ] **Assessment Criteria**: Define what factors determine complexity + +### During Complexity Assessment + +- [ ] **Technical Mapping**: Map technical scope and platform impact +- [ ] **Dependency Analysis**: Identify internal and external dependencies +- [ ] **Risk Evaluation**: Assess infrastructure needs and risk factors +- [ ] **Complexity Classification**: Assign complexity levels to all factors + +### After Complexity Assessment + +- [ ] **Mitigation Planning**: Plan strategies for high-complexity areas +- [ ] **Expectation Setting**: Set realistic expectations based on assessment +- [ ] **Documentation**: Document assessment process and findings +- [ ] **Stakeholder Communication**: Share results and recommendations diff --git a/.cursor/rules/development/dependency_management.mdc b/.cursor/rules/development/dependency_management.mdc new file mode 100644 index 0000000..a92f070 --- /dev/null +++ b/.cursor/rules/development/dependency_management.mdc @@ -0,0 +1,177 @@ +# Dependency Management — Best Practices + +> **Agent role**: Reference this file for dependency management strategies and + best practices when working with software projects. + +## Dependency Management Best Practices + +### Pre-build Validation + +- **Check Critical Dependencies**: + + Validate essential tools before executing build + scripts + +- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to + + avoid PATH issues + +- **Environment Consistency**: Ensure all team members have identical dependency + + versions + +### Common Pitfalls + +- **Missing npm install**: Team members cloning without running `npm install` + +- **PATH Issues**: Direct command execution vs. npm script execution differences + +- **Version Mismatches**: Different Node.js/npm versions across team members + +### Validation Strategies + +- **Dependency Check Scripts**: Implement pre-build validation for critical + + dependencies + +- **Environment Requirements**: + + Document and enforce minimum Node.js/npm versions + +- **Onboarding Checklist**: Standardize team member setup procedures + +### Error Messages and Guidance + +- **Specific Error Context**: + + Provide clear guidance when dependency issues occur + +- **Actionable Solutions**: Direct users to specific commands (`npm install`, + + `npm run check:dependencies`) + +- **Environment Diagnostics**: Implement comprehensive environment validation + + tools + +### Build Script Enhancements + +- **Early Validation**: Check dependencies before starting build processes + +- **Graceful Degradation**: Continue builds when possible but warn about issues + +- **Helpful Tips**: Remind users about dependency management best practices + +## Environment Setup Guidelines + +### Required Tools + +- **Node.js**: Minimum version requirements and LTS recommendations + +- **npm**: Version compatibility and global package management + +- **Platform-specific tools**: Android SDK, Xcode, etc. + +### Environment Variables + +- **NODE_ENV**: Development, testing, production environments + +- **PATH**: Ensure tools are accessible from command line + +- **Platform-specific**: Android SDK paths, Xcode command line tools + +### Validation Commands + +```bash + +# Check Node.js version + +node --version + +# Check npm version + +npm --version + +# Check global packages + +npm list -g --depth=0 + +# Validate platform tools + +npx capacitor doctor + +``` + +## Dependency Troubleshooting + +### Common Issues + +1. **Permission Errors**: Use `sudo` sparingly, prefer `npm config set prefix` + +2. **Version Conflicts**: Use `npm ls` to identify dependency conflicts + +3. **Cache Issues**: Clear npm cache with `npm cache clean --force` + +4. **Lock File Issues**: Delete `package-lock.json` and `node_modules`, + + then reinstall + +### Resolution Strategies + +- **Dependency Audit**: Run `npm audit` to identify security issues + +- **Version Pinning**: Use exact versions for critical dependencies + +- **Peer Dependency Management**: Ensure compatible versions across packages + +- **Platform-specific Dependencies**: Handle different requirements per platform + +## Best Practices for Teams + +### Onboarding + +- **Environment Setup Script**: Automated setup for new team members + +- **Version Locking**: Use `package-lock.json` and `yarn.lock` consistently + +- **Documentation**: Clear setup instructions with troubleshooting steps + +### Maintenance + +- **Regular Updates**: Schedule dependency updates and security patches + +- **Testing**: Validate changes don't break existing functionality + +- **Rollback Plan**: Maintain ability to revert to previous working versions + +**See also**: + `.cursor/rules/development/software_development.mdc` for core development principles. + +**Status**: Active dependency management guidelines +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: software_development.mdc +**Stakeholders**: Development team, DevOps team + +## Model Implementation Checklist + +### Before Dependency Changes + +- [ ] **Current State Review**: Check current dependency versions and status +- [ ] **Impact Analysis**: Assess impact of dependency changes on codebase +- [ ] **Compatibility Check**: Verify compatibility with existing code +- [ ] **Security Review**: Review security implications of dependency changes + +### During Dependency Management + +- [ ] **Version Selection**: Choose appropriate dependency versions +- [ ] **Testing**: Test with new dependency versions +- [ ] **Documentation**: Update dependency documentation +- [ ] **Team Communication**: Communicate changes to team members + +### After Dependency Changes + +- [ ] **Comprehensive Testing**: Test all functionality with new dependencies +- [ ] **Documentation Update**: Update all relevant documentation +- [ ] **Deployment Planning**: Plan and execute deployment strategy +- [ ] **Monitoring**: Monitor for issues after deployment diff --git a/.cursor/rules/development/development_guide.mdc b/.cursor/rules/development/development_guide.mdc new file mode 100644 index 0000000..092ffb9 --- /dev/null +++ b/.cursor/rules/development/development_guide.mdc @@ -0,0 +1,33 @@ +--- +globs: **/src/**/* +alwaysApply: false +--- +✅ use system date command to timestamp all interactions with accurate date and + time +✅ python script files must always have a blank line at their end +✅ remove whitespace at the end of lines +✅ use npm run lint-fix to check for warnings +✅ do not use npm run dev let me handle running and supplying feedback + +## Model Implementation Checklist + +### Before Development Work + +- [ ] **System Date Check**: Use system date command for accurate timestamps +- [ ] **Environment Setup**: Verify development environment is ready +- [ ] **Linting Setup**: Ensure npm run lint-fix is available +- [ ] **Code Standards**: Review project coding standards and requirements + +### During Development + +- [ ] **Timestamp Usage**: Include accurate timestamps in all interactions +- [ ] **Code Quality**: Use npm run lint-fix to check for warnings +- [ ] **File Standards**: Ensure Python files have blank line at end +- [ ] **Whitespace**: Remove trailing whitespace from all lines + +### After Development + +- [ ] **Linting Check**: Run npm run lint-fix to verify code quality +- [ ] **File Validation**: Confirm Python files end with blank line +- [ ] **Whitespace Review**: Verify no trailing whitespace remains +- [ ] **Documentation**: Update relevant documentation with changes diff --git a/.cursor/rules/development/historical_comment_management.mdc b/.cursor/rules/development/historical_comment_management.mdc new file mode 100644 index 0000000..9634e9d --- /dev/null +++ b/.cursor/rules/development/historical_comment_management.mdc @@ -0,0 +1,119 @@ +# Historical Comment Management — Code Clarity Guidelines + +> **Agent role**: When encountering historical comments about removed +> methods, deprecated patterns, or architectural changes, apply these +> guidelines to maintain code clarity and developer guidance. + +## Overview + +Historical comments should either be **removed entirely** or **transformed +into actionable guidance** for future developers. Avoid keeping comments +that merely state what was removed without explaining why or what to do +instead. + +## Decision Framework + +### When to Remove Comments + +- **Obsolete Information**: Comment describes functionality that no + longer exists +- **Outdated Context**: Comment refers to old patterns that are no + longer relevant +- **No Actionable Value**: Comment doesn't help future developers + make decisions + +### When to Transform Comments + +- **Migration Guidance**: Future developers might need to understand + the evolution +- **Alternative Approaches**: The comment can guide future + implementation choices +- **Historical Context**: Understanding the change helps with + current decisions + +## Transformation Patterns + +### 1. **Removed Method** → **Alternative Approach** + +```typescript +// Before: Historical comment +// turnOffNotifyingFlags method removed - notification state is now +// managed by NotificationSection component + +// After: Actionable guidance +// Note: Notification state management has been migrated to +// NotificationSection component +``` + +### 2. **Deprecated Pattern** → **Current Best Practice** + +```typescript +// Before: Historical comment +// Database access has been migrated from direct IndexedDB calls to +// PlatformServiceMixin + +// After: Actionable guidance +// This provides better platform abstraction and consistent error +// handling across web/mobile/desktop + +// When adding new database operations, use this.$getContact(), +// this.$saveSettings(), etc. +``` + +## Best Practices + +### 1. **Use Actionable Language**: Guide future decisions, not just + +document history + +### 2. **Provide Alternatives**: Always suggest what to use instead + +### 3. **Update Related Docs**: If removing from code, consider + +adding to documentation + +### 4. **Keep Context**: Include enough information to understand + +why the change was made + +## Integration Points + +- Apply these rules when reviewing code changes +- Use during code cleanup and refactoring +- Include in code review checklists + +--- + +**See also**: + +- `.cursor/rules/development/historical_comment_patterns.mdc` for detailed + transformation examples and patterns + +**Status**: Active comment management guidelines +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Code reviewers + +## Model Implementation Checklist + +### Before Comment Review + +- [ ] **Code Analysis**: Review code for historical or outdated comments +- [ ] **Context Understanding**: Understand the current state of the codebase +- [ ] **Pattern Identification**: Identify comments that need transformation or removal +- [ ] **Documentation Planning**: Plan where to move important historical context + +### During Comment Management + +- [ ] **Transformation**: Convert historical comments to actionable guidance +- [ ] **Alternative Provision**: Suggest current best practices and alternatives +- [ ] **Context Preservation**: Maintain enough information to understand changes +- [ ] **Documentation Update**: Move important context to appropriate documentation + +### After Comment Management + +- [ ] **Code Review**: Ensure transformed comments provide actionable value +- [ ] **Documentation Sync**: Verify related documentation is updated +- [ ] **Team Communication**: Share comment transformation patterns with team +- [ ] **Process Integration**: Include comment management in code review checklists diff --git a/.cursor/rules/development/historical_comment_patterns.mdc b/.cursor/rules/development/historical_comment_patterns.mdc new file mode 100644 index 0000000..47dc60b --- /dev/null +++ b/.cursor/rules/development/historical_comment_patterns.mdc @@ -0,0 +1,139 @@ +# Historical Comment Patterns — Transformation Examples + +> **Agent role**: Reference this file for specific patterns and + examples when transforming historical comments into actionable guidance. + +## 🔄 Transformation Patterns + +### 1. From Removal Notice to Migration Note + +```typescript + +// ❌ REMOVE THIS +// turnOffNotifyingFlags method removed - + notification state is now managed by NotificationSection component + +// ✅ TRANSFORM TO THIS +// Note: Notification state management has been migrated to NotificationSection + component +// which handles its own lifecycle and persistence via PlatformServiceMixin + +``` + +### 2. From Deprecation Notice to Implementation Guide + +```typescript + +// ❌ REMOVE THIS +// This will be handled by the NewComponent now +// No need to call oldMethod() as it's no longer needed + +// ✅ TRANSFORM TO THIS +// Note: This functionality has been migrated to NewComponent +// which provides better separation of concerns and testability + +``` + +### 3. From Historical Note to Architectural Context + +```typescript + +// ❌ REMOVE THIS +// Old approach: used direct database calls +// New approach: uses service layer + +// ✅ TRANSFORM TO THIS +// Note: Database access has been abstracted through service layer +// for better testability and platform independence + +``` + +## 🚫 Anti-Patterns to Remove + +- Comments that only state what was removed + +- Comments that don't explain the current approach + +- Comments that reference non-existent methods + +- Comments that are self-evident from the code + +- Comments that don't help future decision-making + +## 📚 Examples + +### Good Historical Comment (Keep & Transform) + +```typescript + +// Note: Database access has been migrated from direct IndexedDB calls to + PlatformServiceMixin +// This provides better platform abstraction and + consistent error handling across web/mobile/desktop +// When adding new database operations, use this.$getContact(), + this.$saveSettings(), etc. + +``` + +### Bad Historical Comment (Remove) + +```typescript + +// Old method getContactFromDB() removed - now handled by PlatformServiceMixin +// No need to call the old method anymore + +``` + +## 🎯 When to Use Each Pattern + +### Migration Notes + +- Use when functionality has moved to a different component/service + +- Explain the new location and why it's better + +- Provide guidance on how to use the new approach + +### Implementation Guides + +- Use when patterns have changed significantly + +- Explain the architectural benefits + +- Show how to implement the new pattern + +### Architectural Context + +- Use when the change represents a system-wide improvement + +- Explain the reasoning behind the change + +- Help future developers understand the evolution + +--- + +**See also**: `.cursor/rules/development/historical_comment_management.mdc` for + the core decision framework and best practices. + +## Model Implementation Checklist + +### Before Comment Review + +- [ ] **Code Analysis**: Review code for historical or outdated comments +- [ ] **Pattern Identification**: Identify comments that need transformation or removal +- [ ] **Context Understanding**: Understand the current state of the codebase +- [ ] **Transformation Planning**: Plan how to transform or remove comments + +### During Comment Transformation + +- [ ] **Pattern Selection**: Choose appropriate transformation pattern +- [ ] **Content Creation**: Create actionable guidance for future developers +- [ ] **Alternative Provision**: Suggest current best practices and approaches +- [ ] **Context Preservation**: Maintain enough information to understand changes + +### After Comment Transformation + +- [ ] **Code Review**: Ensure transformed comments provide actionable value +- [ ] **Pattern Documentation**: Document transformation patterns for team use +- [ ] **Team Communication**: Share comment transformation patterns with team +- [ ] **Process Integration**: Include comment patterns in code review checklists diff --git a/.cursor/rules/development/investigation_report_example.mdc b/.cursor/rules/development/investigation_report_example.mdc new file mode 100644 index 0000000..8014105 --- /dev/null +++ b/.cursor/rules/development/investigation_report_example.mdc @@ -0,0 +1,178 @@ +# Investigation Report Example + +**Author**: Matthew Raymer +**Date**: 2025-08-19 +**Status**: 🎯 **ACTIVE** - Investigation methodology example + +## Investigation — Registration Dialog Test Flakiness + +## Objective + +Identify root cause of flaky tests related to registration dialogs in contact +import scenarios. + +## System Map + +- User action → ContactInputForm → ContactsView.addContact() → + + handleRegistrationPrompt() + +- setTimeout(1000ms) → Modal dialog → User response → Registration API call + +- Test execution → Wait for dialog → Assert dialog content → Click response + + button + +## Findings (Evidence) + +- **1-second timeout causes flakiness** — evidence: + + `src/views/ContactsView.vue:971-1000`; setTimeout(..., 1000) in + handleRegistrationPrompt() + +- **Import flow bypasses dialogs** — evidence: + + `src/views/ContactImportView.vue:500-520`; importContacts() calls + $insertContact() directly, no handleRegistrationPrompt() + +- **Dialog only appears in direct add flow** — evidence: + + `src/views/ContactsView.vue:774-800`; addContact() calls + handleRegistrationPrompt() after database insert + +## Hypotheses & Failure Modes + +- H1: 1-second timeout makes dialog appearance unpredictable; would fail when + + tests run faster than 1000ms + +- H2: Test environment timing differs from development; watch for CI vs local + + test differences + +## Corrections + +- Updated: "Multiple dialogs interfere with imports" → "Import flow never + + triggers dialogs - they only appear in direct contact addition" + +- Updated: "Complex batch registration needed" → "Simple timeout removal and + + test mode flag sufficient" + +## Diagnostics (Next Checks) + +- [ ] Repro on CI environment vs local + +- [ ] Measure actual dialog appearance timing + +- [ ] Test with setTimeout removed + +- [ ] Verify import flow doesn't call handleRegistrationPrompt + +## Risks & Scope + +- Impacted: Contact addition tests, registration workflow tests; Data: None; + + Users: Test suite reliability + +## Decision / Next Steps + +- Owner: Development Team; By: 2025-01-28 + +- Action: Remove 1-second timeout + add test mode flag; Exit criteria: Tests + + pass consistently + +## References + +- `src/views/ContactsView.vue:971-1000` + +- `src/views/ContactImportView.vue:500-520` + +- `src/views/ContactsView.vue:774-800` + +## Competence Hooks + +- Why this works: Code path tracing revealed separate execution flows, + + evidence disproved initial assumptions + +- Common pitfalls: Assuming related functionality without tracing execution + + paths, over-engineering solutions to imaginary problems + +- Next skill: Learn to trace code execution before proposing architectural + + changes + +- Teach-back: "What evidence shows that contact imports bypass registration + + dialogs?" + +## Key Learning Points + +### Evidence-First Approach + +This investigation demonstrates the importance of: + +1. **Tracing actual code execution** rather than making assumptions + +2. **Citing specific evidence** with file:line references + +3. **Validating problem scope** before proposing solutions + +4. **Considering simpler alternatives** before complex architectural changes + +### Code Path Tracing Value + +By tracing the execution paths, we discovered: + +- Import flow and direct add flow are completely separate + +- The "multiple dialog interference" problem didn't exist + +- A simple timeout removal would solve the actual issue + +### Prevention of Over-Engineering + +The investigation prevented: + +- Unnecessary database schema changes + +- Complex batch registration systems + +- Migration scripts for non-existent problems + +- Architectural changes based on assumptions + +--- + +**Status**: Active investigation methodology +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: software_development.mdc +**Stakeholders**: Development team, QA team + +## Model Implementation Checklist + +### Before Investigation + +- [ ] **Problem Definition**: Clearly define the problem to investigate +- [ ] **Scope Definition**: Determine investigation scope and boundaries +- [ ] **Methodology Planning**: Plan investigation approach and methods +- [ ] **Resource Assessment**: Identify required resources and tools + +### During Investigation + +- [ ] **Evidence Collection**: Gather relevant evidence and data systematically +- [ ] **Code Path Tracing**: Map execution flow for software investigations +- [ ] **Analysis**: Analyze evidence using appropriate methods +- [ ] **Documentation**: Document investigation process and findings + +### After Investigation + +- [ ] **Synthesis**: Synthesize findings into actionable insights +- [ ] **Report Creation**: Create comprehensive investigation report +- [ ] **Recommendations**: Provide clear, actionable recommendations +- [ ] **Team Communication**: Share findings and next steps with team diff --git a/.cursor/rules/development/logging_migration.mdc b/.cursor/rules/development/logging_migration.mdc new file mode 100644 index 0000000..bbb0c97 --- /dev/null +++ b/.cursor/rules/development/logging_migration.mdc @@ -0,0 +1,358 @@ +--- +alwaysApply: false +--- + +# Logging Migration — Patterns and Examples + +> **Agent role**: Reference this file for specific migration patterns and + examples when converting console.* calls to logger usage. + +## Migration — Auto‑Rewrites (Apply Every Time) + +### Exact Transforms + +- `console.debug(...)` → `logger.debug(...)` + +- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when + + clearly stateful) + +- `console.info(...)` → `logger.info(...)` + +- `console.warn(...)` → `logger.warn(...)` + +- `console.error(...)` → `logger.error(...)` + +### Multi-arg Handling + +- First arg becomes `message` (stringify safely if non-string). + +- Remaining args map 1:1 to `...args`: + + `console.info(msg, a, b)` → `logger.info(String(msg), a, b)` + +### Sole `Error` + +- `console.error(err)` → `logger.error(err.message, err)` + +### Object-wrapping Cleanup + +Replace `{{ userId, meta }}` wrappers with separate args: +`logger.info('User signed in', userId, meta)` + +## Level Guidelines with Examples + +### DEBUG Examples + +```typescript + +logger.debug('[HomeView] reloadFeedOnChange() called'); +logger.debug('[HomeView] Current filter settings', + settings.filterFeedByVisible, + settings.filterFeedByNearby, + settings.searchBoxes?.length ?? 0); +logger.debug('[FeedFilters] Toggling nearby filter', + this.isNearby, this.settingChanged, this.activeDid); + +``` + +**Avoid**: Vague messages (`'Processing data'`). + +### INFO Examples + +```typescript + +logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); +logger.info('[StartView] User selected new seed generation'); +logger.info('[SearchAreaView] Search box stored', + searchBox.name, searchBox.bbox); +logger.info('[ContactQRScanShowView] Contact registration OK', + contact.did); + +``` + +**Avoid**: Diagnostic details that belong in `debug`. + +### WARN Examples + +```typescript + +logger.warn('[ContactQRScanShowView] Invalid scan result – no value', + resultType); +logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); +logger.warn('[ContactQRScanShowView] JWT missing "own" field'); + +``` + +**Avoid**: Hard failures (those are `error`). + +### ERROR Examples + +```typescript + +logger.error('[HomeView Settings] initializeIdentity() failed', err); +logger.error('[StartView] Failed to load initialization data', error); +logger.error('[ContactQRScanShowView] Error processing contact QR', + error, rawValue); + +``` + +**Avoid**: Expected user cancels (use `info`/`debug`). + +## Context Hygiene Examples + +### Component Context + +```typescript + +const log = logger.withContext('UserService'); +log.info('User created', userId); +log.error('Failed to create user', error); + +``` + +If not using `withContext`, prefix message with `[ComponentName]`. + +### Emoji Guidelines + +Recommended set for visual scanning: + +- Start/finish: 🚀 / ✅ + +- Retry/loop: 🔄 + +- External call: 📡 + +- Data/metrics: 📊 + +- Inspection: 🔍 + +## Quick Before/After + +### **Before** + +```typescript + +console.log('User signed in', user.id, meta); +console.error('Failed to update profile', err); +console.info('Filter toggled', this.hasVisibleDid); + +``` + +### **After** + +```typescript + +import { logger } from '@/utils/logger'; + +logger.info('User signed in', user.id, meta); +logger.error('Failed to update profile', err); +logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); + +``` + +## Checklist (for every PR) + +- [ ] No `console.*` (or properly pragma'd in the allowed locations) + +- [ ] Correct import path for `logger` + +- [ ] Rest-parameter call shape (`message, ...args`) + +- [ ] Right level chosen (debug/info/warn/error) + +- [ ] No secrets / oversized payloads / throwaway context objects + +- [ ] Component context provided (scoped logger or `[Component]` prefix) + +**See also**: + `.cursor/rules/development/logging_standards.mdc` for the core standards and rules. + +# Logging Migration — Patterns and Examples + +> **Agent role**: Reference this file for specific migration patterns and + examples when converting console.* calls to logger usage. + +## Migration — Auto‑Rewrites (Apply Every Time) + +### Exact Transforms + +- `console.debug(...)` → `logger.debug(...)` + +- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when + + clearly stateful) + +- `console.info(...)` → `logger.info(...)` + +- `console.warn(...)` → `logger.warn(...)` + +- `console.error(...)` → `logger.error(...)` + +### Multi-arg Handling + +- First arg becomes `message` (stringify safely if non-string). + +- Remaining args map 1:1 to `...args`: + + `console.info(msg, a, b)` → `logger.info(String(msg), a, b)` + +### Sole `Error` + +- `console.error(err)` → `logger.error(err.message, err)` + +### Object-wrapping Cleanup + +Replace `{{ userId, meta }}` wrappers with separate args: +`logger.info('User signed in', userId, meta)` + +## Level Guidelines with Examples + +### DEBUG Examples + +```typescript + +logger.debug('[HomeView] reloadFeedOnChange() called'); +logger.debug('[HomeView] Current filter settings', + settings.filterFeedByVisible, + settings.filterFeedByNearby, + settings.searchBoxes?.length ?? 0); +logger.debug('[FeedFilters] Toggling nearby filter', + this.isNearby, this.settingChanged, this.activeDid); + +``` + +**Avoid**: Vague messages (`'Processing data'`). + +### INFO Examples + +```typescript + +logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); +logger.info('[StartView] User selected new seed generation'); +logger.info('[SearchAreaView] Search box stored', + searchBox.name, searchBox.bbox); +logger.info('[ContactQRScanShowView] Contact registration OK', + contact.did); + +``` + +**Avoid**: Diagnostic details that belong in `debug`. + +### WARN Examples + +```typescript + +logger.warn('[ContactQRScanShowView] Invalid scan result – no value', + resultType); +logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); +logger.warn('[ContactQRScanShowView] JWT missing "own" field'); + +``` + +**Avoid**: Hard failures (those are `error`). + +### ERROR Examples + +```typescript + +logger.error('[HomeView Settings] initializeIdentity() failed', err); +logger.error('[StartView] Failed to load initialization data', error); +logger.error('[ContactQRScanShowView] Error processing contact QR', + error, rawValue); + +``` + +**Avoid**: Expected user cancels (use `info`/`debug`). + +## Context Hygiene Examples + +### Component Context + +```typescript + +const log = logger.withContext('UserService'); +log.info('User created', userId); +log.error('Failed to create user', error); + +``` + +If not using `withContext`, prefix message with `[ComponentName]`. + +### Emoji Guidelines + +Recommended set for visual scanning: + +- Start/finish: 🚀 / ✅ + +- Retry/loop: 🔄 + +- External call: 📡 + +- Data/metrics: 📊 + +- Inspection: 🔍 + +## Quick Before/After + +### **Before** + +```typescript + +console.log('User signed in', user.id, meta); +console.error('Failed to update profile', err); +console.info('Filter toggled', this.hasVisibleDid); + +``` + +### **After** + +```typescript + +import { logger } from '@/utils/logger'; + +logger.info('User signed in', user.id, meta); +logger.error('Failed to update profile', err); +logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); + +``` + +## Checklist (for every PR) + +- [ ] No `console.*` (or properly pragma'd in the allowed locations) + +- [ ] Correct import path for `logger` + +- [ ] Rest-parameter call shape (`message, ...args`) + +- [ ] Right level chosen (debug/info/warn/error) + +- [ ] No secrets / oversized payloads / throwaway context objects + +- [ ] Component context provided (scoped logger or `[Component]` prefix) + +**See also**: + `.cursor/rules/development/logging_standards.mdc` for the core standards and rules. + +## Model Implementation Checklist + +### Before Logging Migration + +- [ ] **Code Review**: Identify all `console.*` calls in the codebase +- [ ] **Logger Import**: Verify logger utility is available and accessible +- [ ] **Context Planning**: Plan component context for each logging call +- [ ] **Level Assessment**: Determine appropriate log levels for each call + +### During Logging Migration + +- [ ] **Import Replacement**: Replace `console.*` with `logger.*` calls +- [ ] **Context Addition**: Add component context using scoped logger or prefix +- [ ] **Level Selection**: Choose appropriate log level (debug/info/warn/error) +- [ ] **Parameter Format**: Use rest-parameter call shape (`message, ...args`) + +### After Logging Migration + +- [ ] **Console Check**: Ensure no `console.*` methods remain (unless pragma'd) +- [ ] **Context Validation**: Verify all logging calls have proper context +- [ ] **Level Review**: Confirm log levels are appropriate for each situation +- [ ] **Testing**: Test logging functionality across all platforms diff --git a/.cursor/rules/development/logging_standards.mdc b/.cursor/rules/development/logging_standards.mdc new file mode 100644 index 0000000..5086567 --- /dev/null +++ b/.cursor/rules/development/logging_standards.mdc @@ -0,0 +1,176 @@ +# Agent Contract — TimeSafari Logging (Unified, MANDATORY) + +**Author**: Matthew Raymer +**Date**: 2025-08-19 +**Status**: 🎯 **ACTIVE** - Mandatory logging standards + +## Overview + +This document defines unified logging standards for the TimeSafari project, +ensuring consistent, rest-parameter logging style using the project logger. +No `console.*` methods are allowed in production code. + +## Scope and Goals + +**Scope**: Applies to all diffs and generated code in this workspace unless +explicitly exempted below. + +**Goal**: One consistent, rest-parameter logging style using the project +logger; no `console.*` in production code. + +## Non‑Negotiables (DO THIS) + +- You **MUST** use the project logger; **DO NOT** use any `console.*` + + methods. + +- Import exactly as: + + - `import { logger } from '@/utils/logger'` + + - If `@` alias is unavailable, compute the correct relative path (do not + + fail). + +- Call signatures use **rest parameters**: `logger.info(message, ...args)` + +- Prefer primitives/IDs and small objects in `...args`; **never build a + + throwaway object** just to "wrap context". + +- Production defaults: Web = `warn+`, Electron = `error`, Dev/Capacitor = + + `info+` (override via `VITE_LOG_LEVEL`). + +- **Database persistence**: `info|warn|error` are persisted; `debug` is not. + + Use `logger.toDb(msg, level?)` for DB-only. + +## Available Logger API (Authoritative) + +- `logger.debug(message, ...args)` — verbose internals, timings, input/output + + shapes + +- `logger.log(message, ...args)` — synonym of `info` for general info + +- `logger.info(message, ...args)` — lifecycle, state changes, success paths + +- `logger.warn(message, ...args)` — recoverable issues, retries, degraded mode + +- `logger.error(message, ...args)` — failures, thrown exceptions, aborts + +- `logger.toDb(message, level?)` — DB-only entry (default level = `info`) + +- `logger.toConsoleAndDb(message, isError)` — console + DB (use sparingly) + +- `logger.withContext(componentName)` — returns a scoped logger + +## Level Guidelines (Use These Heuristics) + +### DEBUG + +Use for method entry/exit, computed values, filters, loops, retries, and +external call payload sizes. + +### INFO + +Use for user-visible lifecycle and completed operations. + +### WARN + +Use for recoverable issues, fallbacks, unexpected-but-handled conditions. + +### ERROR + +Use for unrecoverable failures, data integrity issues, and thrown +exceptions. + +## Context Hygiene (Consistent, Minimal, Helpful) + +- **Component context**: Prefer scoped logger. + +- **Emojis**: Optional and minimal for visual scanning. + +- **Sensitive data**: Never log secrets (tokens, keys, passwords) or + payloads >10KB. Prefer IDs over objects; redact/hash when needed. + +## DB Logging Rules + +- `debug` **never** persists automatically. + +- `info|warn|error` persist automatically. + +- For DB-only events (no console), call `logger.toDb('Message', + 'info'|'warn'|'error')`. + +## Exceptions (Tightly Scoped) + +Allowed paths (still prefer logger): + +- `**/*.test.*`, `**/*.spec.*` + +- `scripts/dev/**`, `scripts/migrate/**` + +To intentionally keep `console.*`, add a pragma on the previous line: + +```typescript + +// cursor:allow-console reason="short justification" +console.log('temporary output'); + +``` + +## CI & Diff Enforcement + +- Do not introduce `console.*` anywhere outside allowed, pragma'd spots. + +- If an import is missing, insert it and resolve alias/relative path + correctly. + +- Enforce rest-parameter call shape in reviews; replace object-wrapped + context. + +- Ensure environment log level rules remain intact (`VITE_LOG_LEVEL` + respected). + +--- + +**See also**: + `.cursor/rules/development/logging_migration.mdc` for migration patterns and examples. + +**Status**: Active and enforced +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: TimeSafari logger utility +**Stakeholders**: Development team, Code review team + +## Model Implementation Checklist + +### Before Adding Logging + +- [ ] **Logger Import**: Import logger as `import { logger } from + '@/utils/logger'` +- [ ] **Log Level Selection**: Determine appropriate log level + (debug/info/warn/error) +- [ ] **Context Planning**: Plan what context information to include +- [ ] **Sensitive Data Review**: Identify any sensitive data that needs redaction + +### During Logging Implementation + +- [ ] **Rest Parameters**: Use `logger.info(message, ...args)` format, not object + wrapping +- [ ] **Context Addition**: Include relevant IDs, primitives, or small objects in + args +- [ ] **Level Appropriateness**: Use correct log level for the situation +- [ ] **Scoped Logger**: Use `logger.withContext(componentName)` for + component-specific logging + +### After Logging Implementation + +- [ ] **Console Check**: Ensure no `console.*` methods are used (unless in + allowed paths) +- [ ] **Performance Review**: Verify logging doesn't impact performance +- [ ] **DB Persistence**: Use `logger.toDb()` for database-only logging if needed +- [ ] **Environment Compliance**: Respect `VITE_LOG_LEVEL` environment + variable diff --git a/.cursor/rules/development/planning_examples.mdc b/.cursor/rules/development/planning_examples.mdc new file mode 100644 index 0000000..310d73c --- /dev/null +++ b/.cursor/rules/development/planning_examples.mdc @@ -0,0 +1,160 @@ +# Planning Examples — No Time Estimates + +> **Agent role**: Reference this file for detailed planning examples and + anti-patterns when creating project plans. + +## 🎯 Example Planning (No Time Estimates) + +### **Example 1: Simple Feature** + +``` + +Phase 1: Core implementation + +- Basic functionality + +- Single platform support + +- Unit tests + +Phase 2: Platform expansion + +- Multi-platform support + +- Integration tests + +Phase 3: Polish + +- User testing + +- Edge case handling + +``` + +### **Example 2: Complex Cross-Platform Feature** + +``` + +Phase 1: Foundation + +- Architecture design + +- Core service implementation + +- Basic web platform support + +Phase 2: Platform Integration + +- Mobile platform support + +- Desktop platform support + +- Cross-platform consistency + +Phase 3: Testing & Polish + +- Comprehensive testing + +- Error handling + +- User experience refinement + +``` + +## 🚫 Anti-Patterns to Avoid + +- **"This should take X days"** - Red flag for time estimation + +- **"Just a few hours"** - Ignores complexity and testing + +- **"Similar to X"** - Without considering differences + +- **"Quick fix"** - Nothing is ever quick in software + +- **"No testing needed"** - Testing always takes effort + +## ✅ Best Practices + +### **When Planning:** + +1. **Break down everything** - no work is too small to plan + +2. **Consider all platforms** - web, mobile, desktop differences + +3. **Include testing strategy** - unit, integration, and user testing + +4. **Account for unknowns** - there are always surprises + +5. **Focus on dependencies** - what blocks what + +### **When Presenting Plans:** + +1. **Show the phases** - explain the logical progression + +2. **Highlight dependencies** - what could block progress + +3. **Define milestones** - clear success criteria + +4. **Identify risks** - what could go wrong + +5. **Suggest alternatives** - ways to reduce scope or complexity + +## 🔄 Continuous Improvement + +### **Track Progress** + +- Record planned vs. actual phases completed + +- Identify what took longer than expected + +- Learn from complexity misjudgments + +- Adjust planning process based on experience + +### **Learn from Experience** + +- **Underestimated complexity**: Increase complexity categories + +- **Missed dependencies**: Improve dependency mapping + +- **Platform surprises**: Better platform research upfront + +## 🎯 Integration with Harbor Pilot + +This rule works in conjunction with: + +- **Project Planning**: Focuses on phases and milestones + +- **Resource Allocation**: Based on complexity, not time + +- **Risk Management**: Identifies blockers and dependencies + +- **Stakeholder Communication**: Sets progress-based expectations + +--- + +**See also**: `.cursor/rules/development/realistic_time_estimation.mdc` for + the core principles and framework. + +## Model Implementation Checklist + +### Before Planning + +- [ ] **Requirements Review**: Understand all requirements completely +- [ ] **Stakeholder Input**: Gather input from all stakeholders +- [ ] **Complexity Assessment**: Evaluate technical and business complexity +- [ ] **Platform Analysis**: Consider requirements across all target platforms + +### During Planning + +- [ ] **Phase Definition**: Define clear phases and milestones +- [ ] **Dependency Mapping**: Map dependencies between tasks +- [ ] **Risk Identification**: Identify potential risks and challenges +- [ ] **Testing Strategy**: Plan comprehensive testing approach + +### After Planning + +- [ ] **Stakeholder Review**: Review plan with stakeholders +- [ ] **Documentation**: Document plan clearly with phases and milestones +- [ ] **Team Communication**: Communicate plan to team +- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms diff --git a/.cursor/rules/development/realistic_time_estimation.mdc b/.cursor/rules/development/realistic_time_estimation.mdc new file mode 100644 index 0000000..f08a439 --- /dev/null +++ b/.cursor/rules/development/realistic_time_estimation.mdc @@ -0,0 +1,128 @@ +# Realistic Time Estimation — Development Guidelines + +> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, +> milestones, and complexity levels. Time estimates are consistently wrong +> and create unrealistic expectations. + +## Purpose + +Development time estimates are consistently wrong and create unrealistic +expectations. This rule ensures we focus on phases, milestones, and +complexity rather than trying to predict specific timeframes. + +## Critical Rule + +**NEVER provide specific time estimates** (hours, days, weeks) for +development tasks. Instead, use: + +- **Complexity levels** (Low, Medium, High, Critical) + +- **Phases and milestones** with clear acceptance criteria + +- **Platform-specific considerations** (Web, Mobile, Desktop) + +- **Testing requirements** and validation steps + +## Planning Framework + +### Complexity Assessment + +- **Low**: Simple changes, existing patterns, minimal testing + +- **Medium**: New features, moderate testing, some integration + +- **High**: Complex features, extensive testing, multiple platforms + +- **Critical**: Core architecture changes, full regression testing + +### Platform Categories + +- **Web**: Browser compatibility, responsive design, accessibility + +- **Mobile**: Native APIs, platform-specific testing, deployment + +- **Desktop**: Electron integration, system APIs, distribution + +### Testing Strategy + +- **Unit tests**: Core functionality validation + +- **Integration tests**: Component interaction testing + +- **E2E tests**: User workflow validation + +- **Platform tests**: Cross-platform compatibility + +## Process Guidelines + +### Planning Phase + +1. **Scope Definition**: Clear requirements and acceptance criteria + +2. **Complexity Assessment**: Evaluate technical and business complexity + +3. **Phase Breakdown**: Divide into logical, testable phases + +4. **Milestone Definition**: Define success criteria for each phase + +### Execution Phase + +1. **Phase 1**: Foundation and core implementation + +2. **Phase 2**: Feature completion and integration + +3. **Phase 3**: Testing, refinement, and documentation + +4. **Phase 4**: Deployment and validation + +### Validation Phase + +1. **Acceptance Testing**: Verify against defined criteria + +2. **Platform Testing**: Validate across target platforms + +3. **Performance Testing**: Ensure performance requirements met + +4. **Documentation**: Update relevant documentation + +## Remember + +**Your first estimate is wrong. Your second estimate is probably still +wrong. Focus on progress, not deadlines.** + +--- + +**See also**: + +- `.cursor/rules/development/planning_examples.mdc` for detailed planning examples + +- `.cursor/rules/development/complexity_assessment.mdc` for complexity evaluation + +**Status**: Active development guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Project managers + +## Model Implementation Checklist + +### Before Time Estimation + +- [ ] **Requirements Analysis**: Understand all requirements and acceptance criteria +- [ ] **Complexity Assessment**: Evaluate technical and business complexity +- [ ] **Platform Review**: Identify requirements across all target platforms +- [ ] **Stakeholder Input**: Gather input from all affected parties + +### During Time Estimation + +- [ ] **Phase Breakdown**: Divide work into logical, testable phases +- [ ] **Complexity Classification**: Assign complexity levels (Low/Medium/High/Critical) +- [ ] **Platform Considerations**: Account for platform-specific requirements +- [ ] **Testing Strategy**: Plan comprehensive testing approach + +### After Time Estimation + +- [ ] **Milestone Definition**: Define success criteria for each phase +- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms +- [ ] **Documentation**: Document estimation process and assumptions +- [ ] **Stakeholder Communication**: Share estimation approach and progress focus diff --git a/.cursor/rules/development/research_diagnostic.mdc b/.cursor/rules/development/research_diagnostic.mdc new file mode 100644 index 0000000..9d3c31a --- /dev/null +++ b/.cursor/rules/development/research_diagnostic.mdc @@ -0,0 +1,262 @@ +--- +description: Use this workflow when doing **pre-implementation research, defect + investigations with uncertain repros, or clarifying system architecture and + behaviors**. +alwaysApply: false +--- + +```json + +{ + "coaching_level": "light", + "socratic_max_questions": 2, + "verbosity": "concise", + "timebox_minutes": null, + "format_enforcement": "strict" +} + +``` + +# Research & Diagnostic Workflow (R&D) + +## Purpose + +Provide a **repeatable, evidence-first** workflow to investigate features and +defects **before coding**. Outputs are concise reports, hypotheses, and next +steps—**not** code changes. + +## When to Use + +- Pre-implementation research for new features + +- Defect investigations (repros uncertain, user-specific failures) + +- Architecture/behavior clarifications (e.g., auth flows, merges, migrations) + +--- + +## Enhanced with Software Development Ruleset + +When investigating software issues, also apply: + +- **Code Path Tracing**: Required for technical investigations + +- **Evidence Validation**: Ensure claims are code-backed + +- **Solution Complexity Assessment**: Justify architectural changes + +--- + +## Output Contract (strict) + +1) **Objective** — 1–2 lines +2) **System Map (if helpful)** — short diagram or bullet flow (≤8 bullets) +3) **Findings (Evidence-linked)** — bullets; each with file/function refs +4) **Hypotheses & Failure Modes** — short list, each testable +5) **Corrections** — explicit deltas from earlier assumptions (if any) +6) **Diagnostics** — what to check next (logs, DB, env, repro steps) +7) **Risks & Scope** — what could break; affected components +8) **Decision/Next Steps** — what we'll do, who's involved, by when +9) **References** — code paths, ADRs, docs +10) **Competence & Collaboration Hooks** — brief, skimmable + +> Keep total length lean. Prefer links and bullets over prose. + +--- + +## Quickstart Template + +Copy/paste and fill: + +```md + +# Investigation — + +## Objective + + + +## System Map + +- → → + +- → → + +## Findings (Evidence) + +- — + + evidence: `src/path/file.ts:function` (lines X–Y); log snippet/trace id + +- — evidence: `...` + +## Hypotheses & Failure Modes + +- H1: ; would fail when + +- H2: ; watch for + +## Corrections + +- Updated: → + +## Diagnostics (Next Checks) + +- [ ] Repro on + +- [ ] Inspect for + +- [ ] Capture + +## Risks & Scope + +- Impacted: ; Data: ; Users: + +## Decision / Next Steps + +- Owner: ; By: (YYYY-MM-DD) + +- Action: ; Exit criteria: + +## References + +- `src/...` + +- ADR: `docs/adr/xxxx-yy-zz-something.md` + +- Design: `docs/...` + +## Competence Hooks + +- Why this works: <≤3 bullets> + +- Common pitfalls: <≤3 bullets> + +- Next skill: <≤1 item> + +- Teach-back: "" + +``` + +--- + +## Evidence Quality Bar + +- **Cite the source** (file:func, line range if possible). + +- **Prefer primary evidence** (code, logs) over inference. + +- **Disambiguate platform** (Web/Capacitor/Electron) and **state** (migration, + + auth). + +- **Note uncertainty** explicitly. + +--- + +## Code Path Tracing (Required for Software Investigations) + +Before proposing solutions, trace the actual execution path: + +- [ ] **Entry Points**: + + Identify where the flow begins (user action, API call, etc.) + +- [ ] **Component Flow**: Map which components/methods are involved + +- [ ] **Data Path**: Track how data moves through the system + +- [ ] **Exit Points**: Confirm where the flow ends and what results + +- [ ] **Evidence Collection**: Gather specific code citations for each step + +--- + +## Collaboration Hooks + +- **Syncs:** 10–15m with QA/Security/Platform owners for high-risk areas. + +- **ADR:** Record major decisions; link here. + +- **Review:** Share repro + diagnostics checklist in PR/issue. + +--- + +## Integration with Other Rulesets + +### With software_development.mdc + +- **Enhanced Evidence Validation**: + + Use code path tracing for technical investigations + +- **Architecture Assessment**: + + Apply complexity justification to proposed solutions + +- **Impact Analysis**: Assess effects on existing systems before recommendations + +### With base_context.mdc + +- **Competence Building**: Focus on technical investigation skills + +- **Collaboration**: Structure outputs for team review and discussion + +--- + +## Self-Check (model, before responding) + +- [ ] Output matches the **Output Contract** sections. + +- [ ] Each claim has **evidence** or **uncertainty** is flagged. + +- [ ] Hypotheses are testable; diagnostics are actionable. + +- [ ] Competence + collaboration hooks present (≤120 words total). + +- [ ] Respect toggles; keep it concise. + +- [ ] **Code path traced** (for software investigations). + +- [ ] **Evidence validated** against actual code execution. + +--- + +## Optional Globs (examples) + +> Uncomment `globs` in the header if you want auto-attach behavior. + +- `src/platforms/**`, `src/services/**` — + + attach during service/feature investigations + +- `docs/adr/**` — attach when editing ADRs + +## Referenced Files + +- Consider including templates as context: `@adr_template.mdc`, + + `@investigation_report_example.mdc` + +## Model Implementation Checklist + +### Before Investigation + +- [ ] **Problem Definition**: Clearly define the research question or issue +- [ ] **Scope Definition**: Determine investigation scope and boundaries +- [ ] **Methodology Planning**: Plan investigation approach and methods +- [ ] **Resource Assessment**: Identify required resources and tools + +### During Investigation + +- [ ] **Evidence Collection**: Gather relevant evidence and data systematically +- [ ] **Code Path Tracing**: Map execution flow for software investigations +- [ ] **Analysis**: Analyze evidence using appropriate methods +- [ ] **Documentation**: Document investigation process and findings + +### After Investigation + +- [ ] **Synthesis**: Synthesize findings into actionable insights +- [ ] **Report Creation**: Create comprehensive investigation report +- [ ] **Recommendations**: Provide clear, actionable recommendations +- [ ] **Team Communication**: Share findings and next steps with team diff --git a/.cursor/rules/development/software_development.mdc b/.cursor/rules/development/software_development.mdc new file mode 100644 index 0000000..bbf3da4 --- /dev/null +++ b/.cursor/rules/development/software_development.mdc @@ -0,0 +1,227 @@ + +--- + +alwaysApply: false +--- + +# Software Development Ruleset + +**Author**: Matthew Raymer +**Date**: 2025-08-19 +**Status**: 🎯 **ACTIVE** - Core development guidelines + +## Purpose + +Specialized guidelines for software development tasks including code review, +debugging, architecture decisions, and testing. + +## Core Principles + +### 1. Evidence-First Development + +- **Code Citations Required**: Always cite specific file:line references when + + making claims + +- **Execution Path Tracing**: Trace actual code execution before proposing + + architectural changes + +- **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based" + +### 2. Code Review Standards + +- **Trace Before Proposing**: Always trace execution paths before suggesting + + changes + +- **Evidence Over Inference**: Prefer code citations over logical deductions + +- **Scope Validation**: Confirm the actual scope of problems before proposing + + solutions + +### 3. Problem-Solution Validation + +- **Problem Scope**: Does the solution address the actual problem? + +- **Evidence Alignment**: Does the solution match the evidence? + +- **Complexity Justification**: Is added complexity justified by real needs? + +- **Alternative Analysis**: What simpler solutions were considered? + +### 4. Dependency Management & Environment Validation + +- **Pre-build Validation**: + + Always validate critical dependencies before executing + build scripts + +- **Environment Consistency**: Ensure team members have identical development + + environments + +- **Dependency Verification**: Check that required packages are installed and + + accessible + +- **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues + +## Required Workflows + +### Before Proposing Changes + +- [ ] **Code Path Tracing**: Map execution flow from entry to exit + +- [ ] **Evidence Collection**: Gather specific code citations and logs + +- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred + +- [ ] **Scope Validation**: Confirm the actual extent of the problem + +- [ ] **Dependency Validation**: Verify all required dependencies are available + + and accessible + +### During Solution Design + +- [ ] **Evidence Alignment**: Ensure solution addresses proven problems + +- [ ] **Complexity Assessment**: Justify any added complexity + +- [ ] **Alternative Evaluation**: Consider simpler approaches first + +- [ ] **Impact Analysis**: Assess effects on existing systems + +- [ ] **Environment Impact**: Assess how changes affect team member setups + +## Software-Specific Competence Hooks + +### Evidence Validation + +- **"What code path proves this claim?"** + +- **"How does data actually flow through the system?"** + +- **"What am I assuming vs. what can I prove?"** + +### Code Tracing + +- **"What's the execution path from user action to system response?"** + +- **"Which components actually interact in this scenario?"** + +- **"Where does the data originate and where does it end up?"** + +### Architecture Decisions + +- **"What evidence shows this change is necessary?"** + +- **"What simpler solution could achieve the same goal?"** + +- **"How does this change affect the existing system architecture?"** + +### Dependency & Environment Management + +- **"What dependencies does this feature require and are they properly + + declared?"** + +- **"How will this change affect team member development environments?"** + +- **"What validation can we add to catch dependency issues early?"** + +## Integration with Other Rulesets + +### With base_context.mdc + +- Inherits generic competence principles + +- Adds software-specific evidence requirements + +- Maintains collaboration and learning focus + +### With research_diagnostic.mdc + +- Enhances investigation with code path tracing + +- Adds evidence validation to diagnostic workflow + +- Strengthens problem identification accuracy + +## Usage Guidelines + +### When to Use This Ruleset + +- Code reviews and architectural decisions + +- Bug investigation and debugging + +- Performance optimization + +- Feature implementation planning + +- Testing strategy development + +### When to Combine with Others + +- **base_context + software_development**: General development tasks + +- **research_diagnostic + software_development**: Technical investigations + +- **All three**: Complex architectural decisions or major refactoring + +## Self-Check (model, before responding) + +- [ ] Code path traced and documented + +- [ ] Evidence cited with specific file:line references + +- [ ] Assumptions clearly flagged as proven vs. inferred + +- [ ] Solution complexity justified by evidence + +- [ ] Simpler alternatives considered and documented + +- [ ] Impact on existing systems assessed + +- [ ] Dependencies validated and accessible + +- [ ] Environment impact assessed for team members + +- [ ] Pre-build validation implemented where appropriate + +--- + +**See also**: `.cursor/rules/development/dependency_management.mdc` for + detailed dependency management practices. + +**Status**: Active development guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: base_context.mdc, research_diagnostic.mdc +**Stakeholders**: Development team, Code review team + +## Model Implementation Checklist + +### Before Development Work + +- [ ] **Code Path Tracing**: Map execution flow from entry to exit +- [ ] **Evidence Collection**: Gather specific code citations and logs +- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred +- [ ] **Scope Validation**: Confirm the actual extent of the problem + +### During Development + +- [ ] **Evidence Alignment**: Ensure solution addresses proven problems +- [ ] **Complexity Assessment**: Justify any added complexity +- [ ] **Alternative Evaluation**: Consider simpler approaches first +- [ ] **Impact Analysis**: Assess effects on existing systems + +### After Development + +- [ ] **Code Path Validation**: Verify execution paths are correct +- [ ] **Evidence Documentation**: Document all code citations and evidence +- [ ] **Assumption Review**: Confirm all assumptions are documented +- [ ] **Environment Impact**: Assess how changes affect team member setups diff --git a/.cursor/rules/development/time.mdc b/.cursor/rules/development/time.mdc new file mode 100644 index 0000000..9aeb172 --- /dev/null +++ b/.cursor/rules/development/time.mdc @@ -0,0 +1,146 @@ +# Time Handling in Development Workflow + +**Author**: Matthew Raymer +**Date**: 2025-08-17 +**Status**: 🎯 **ACTIVE** - Production Ready + +## Overview + +This guide establishes **how time should be referenced and used** across the +development workflow. It is not tied to any one project, but applies to **all +feature development, issue investigations, ADRs, and documentation**. + +## General Principles + +- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over + + relative references like "last week." + +- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in + + docs, issues, ADRs, and commits. + +- **Time zones**: Default to **UTC** unless explicitly tied to user-facing + + behavior. + +- **Precision**: Only specify as much precision as needed (date vs. datetime vs. + + timestamp). + +- **Consistency**: Align time references across ADRs, commits, and investigation + + reports. + +## In Documentation & ADRs + +- Record decision dates using **absolute ISO dates**. + +- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` → + + `2025-08-17`). + +- Avoid ambiguous terms like *recently*, *last month*, or *soon*. + +- For time-based experiments (e.g., A/B tests), always include: + + - Start date + + - Expected duration + + - Review date checkpoint + +## In Code & Commits + +- Use **UTC timestamps** in logs, DB migrations, and serialized formats. + +- In commits, link changes to **date-bound ADRs or investigation docs**. + +- For migrations, include both **applied date** and **intended version window**. + +- Use constants for known fixed dates; avoid hardcoding arbitrary strings. + +## In Investigations & Research + +- Capture **when** an issue occurred (absolute time or version tag). + +- When describing failures: note whether they are **time-sensitive** (e.g., + + after + migrations, cache expirations). + +- Record diagnostic timelines in ISO format (not relative). + +- For performance regressions, annotate both **baseline timeframe** and + + **measurement timeframe**. + +## Collaboration Hooks + +- During reviews, verify **time references are clear, absolute, and + + standardized**. + +- In syncs, reframe relative terms ("this week") into shared absolute + + references. + +- Tag ADRs with both **date created** and **review by** checkpoints. + +## Self-Check Before Submitting + +- [ ] Did I check the time using the **developer's actual system time and + + timezone**? + +- [ ] Am I using absolute ISO dates? + +- [ ] Is UTC assumed unless specified otherwise? + +- [ ] Did I avoid ambiguous relative terms? + +- [ ] If duration matters, did I specify both start and end? + +- [ ] For future work, did I include a review/revisit date? + +--- + +**See also**: + +- `.cursor/rules/development/time_implementation.mdc` for + + detailed implementation instructions + +- `.cursor/rules/development/time_examples.mdc` for practical examples and patterns + +**Status**: Active time handling guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Documentation team + +**Maintainer**: Matthew Raymer +**Next Review**: 2025-09-17 + +## Model Implementation Checklist + +### Before Time-Related Work + +- [ ] **Time Context**: Understand what time information is needed +- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) +- [ ] **Platform Check**: Identify platform-specific time requirements +- [ ] **User Context**: Consider user's timezone and preferences + +### During Time Implementation + +- [ ] **UTC Usage**: Use UTC for all system and log timestamps +- [ ] **Format Consistency**: Apply consistent time formatting patterns +- [ ] **Timezone Handling**: Properly handle timezone conversions +- [ ] **User Display**: Format times appropriately for user display + +### After Time Implementation + +- [ ] **Validation**: Verify time formats are correct and consistent +- [ ] **Testing**: Test time handling across different scenarios +- [ ] **Documentation**: Update relevant documentation with time patterns +- [ ] **Review**: Confirm implementation follows time standards diff --git a/.cursor/rules/development/time_examples.mdc b/.cursor/rules/development/time_examples.mdc new file mode 100644 index 0000000..f8a3d56 --- /dev/null +++ b/.cursor/rules/development/time_examples.mdc @@ -0,0 +1,243 @@ +# Time Examples — Practical Patterns + +> **Agent role**: Reference this file for practical examples and + patterns when working with time handling in development. + +## Examples + +### Good + +- "Feature flag rollout started on `2025-08-01` and will be reviewed on + + `2025-08-21`." + +- "Migration applied on `2025-07-15T14:00Z`." + +- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` / + + `2025-08-17T14:00Z (UTC)`." + +### Bad + +- "Feature flag rolled out last week." + +- "Migration applied recently." + +- "Now is August, so we assume this was last month." + +### More Examples + +#### Issue Reports + +- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue + + persisted until `2025-08-17T15:45:00Z`." + +- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a + + while." + +#### Release Planning + +- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing + + window: `2025-08-20` to `2025-08-24`." + +- ❌ **Bad**: "Feature X will be released next week after testing." + +#### Performance Monitoring + +- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`. + + Regression detected on `2025-08-15T14:00:00Z`." + +- ❌ **Bad**: "Performance was good last week but got worse this week." + +## Technical Implementation Examples + +### Database Storage + +```sql + +-- ✅ Good: Store in UTC +created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, +updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP + +-- ❌ Bad: Store in local time +created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, +updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP + +``` + +### API Responses + +```json + +// ✅ Good: Include both UTC and local time +{ + "eventTime": "2025-08-17T14:00:00Z", + "localTime": "2025-08-17T10:00:00-04:00", + "timezone": "America/New_York" +} + +// ❌ Bad: Only local time +{ + "eventTime": "2025-08-17T10:00:00-04:00" +} + +``` + +### Logging + +```python + +# ✅ Good: Log in UTC with timezone info + +logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)") + +# ❌ Bad: Log in local time + +logger.info(f"User action at {datetime.now()}") + +``` + +## Timezone Handling Examples + +### Good Timezone Usage + +```typescript + +// ✅ Good: Store UTC, convert for display +const eventTime = new Date().toISOString(); // Store in UTC +const localTime = new Date().toLocaleString('en-US', { + timeZone: 'America/New_York' +}); // Convert for display + +// ✅ Good: Include timezone context +const timestamp = { + utc: "2025-08-17T14:00:00Z", + local: "2025-08-17T10:00:00-04:00", + timezone: "America/New_York" +}; + +``` + +### Bad Timezone Usage + +```typescript + +// ❌ Bad: Assume timezone +const now = new Date(); // Assumes system timezone + +// ❌ Bad: Mix formats +const timestamp = "2025-08-17 10:00 AM"; // Ambiguous format + +``` + +## Common Patterns + +### Date Range References + +```typescript + +// ✅ Good: Explicit date ranges +const dateRange = { + start: "2025-08-01T00:00:00Z", + end: "2025-08-31T23:59:59Z" +}; + +// ❌ Bad: Relative ranges +const dateRange = { + start: "beginning of month", + end: "end of month" +}; + +``` + +### Duration References + +```typescript + +// ✅ Good: Specific durations +const duration = { + value: 30, + unit: "days", + startDate: "2025-08-01T00:00:00Z" +}; + +// ❌ Bad: Vague durations +const duration = "about a month"; + +``` + +### Version References + +```typescript + +// ✅ Good: Version with date +const version = { + number: "1.2.3", + releaseDate: "2025-08-17T10:00:00Z", + buildDate: "2025-08-17T09:30:00Z" +}; + +// ❌ Bad: Version without context +const version = "latest"; + +``` + +## References + +- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601) + +- [IANA Timezone Database](https://www.iana.org/time-zones) + +- [ADR Template](./adr_template.md) + +- [Research & Diagnostic Workflow](./research_diagnostic.mdc) + +--- + +**Rule of Thumb**: Every time reference in development artifacts should be +**clear in 6 months without context**, and aligned to the **developer's actual +current time**. + +**Technical Rule of Thumb**: **Store in UTC, display in local time, always +include timezone context.** + +--- + +**See also**: + +- `.cursor/rules/development/time.mdc` for core principles + +- `.cursor/rules/development/time_implementation.mdc` for implementation instructions + +**Status**: Active examples and patterns +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: time.mdc, time_implementation.mdc +**Stakeholders**: Development team, Documentation team + +## Model Implementation Checklist + +### Before Time Implementation + +- [ ] **Time Context**: Understand what time information needs to be implemented +- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) +- [ ] **Platform Check**: Identify platform-specific time requirements +- [ ] **User Context**: Consider user's timezone and display preferences + +### During Time Implementation + +- [ ] **UTC Storage**: Use UTC for all system and log timestamps +- [ ] **Format Consistency**: Apply consistent time formatting patterns +- [ ] **Timezone Handling**: Properly handle timezone conversions +- [ ] **User Display**: Format times appropriately for user display + +### After Time Implementation + +- [ ] **Format Validation**: Verify time formats are correct and consistent +- [ ] **Cross-Platform Testing**: Test time handling across different platforms +- [ ] **Documentation**: Update relevant documentation with time patterns +- [ ] **User Experience**: Confirm time display is clear and user-friendly diff --git a/.cursor/rules/development/time_implementation.mdc b/.cursor/rules/development/time_implementation.mdc new file mode 100644 index 0000000..f5c2da2 --- /dev/null +++ b/.cursor/rules/development/time_implementation.mdc @@ -0,0 +1,285 @@ +# Time Implementation — Technical Instructions + +> **Agent role**: Reference this file for detailed implementation instructions + when working with time handling in development. + +## Real-Time Context in Developer Interactions + +- The model must always resolve **"current time"** using the **developer's + + actual system time and timezone**. + +- When generating timestamps (e.g., in investigation logs, ADRs, or examples), + + the model should: + + - Use the **developer's current local time** by default. + + - Indicate the timezone explicitly (e.g., `2025-08-17T10:32-05:00`). + + - Optionally provide UTC alongside if context requires cross-team clarity. + +- When interpreting relative terms like *now*, *today*, *last week*: + + - Resolve them against the **developer's current time**. + + - Convert them into **absolute ISO-8601 values** in the output. + +## LLM Time Checking Instructions + +**CRITICAL**: The LLM must actively query the system for current time rather +than assuming or inventing times. + +### How to Check Current Time + +#### 1. **Query System Time (Required)** + +- **Always start** by querying the current system time using available tools + +- **Never assume** what the current time is + +- **Never use** placeholder values like "current time" or "now" + +#### 2. **Available Time Query Methods** + +- **System Clock**: Use `date` command or equivalent system time function + +- **Programming Language**: Use language-specific time functions (e.g., + + `Date.now()`, `datetime.now()`) + +- **Environment Variables**: Check for time-related environment variables + +- **API Calls**: Use time service APIs if available + +#### 3. **Required Time Information** + +When querying time, always obtain: + +- **Current Date**: YYYY-MM-DD format + +- **Current Time**: HH:MM:SS format (24-hour) + +- **Timezone**: Current system timezone or UTC offset + +- **UTC Equivalent**: Convert local time to UTC for cross-team clarity + +#### 4. **Time Query Examples** + +```bash + +# Example: Query system time + +$ date + +# Expected output: Mon Aug 17 10:32:45 EDT 2025 + +# Example: Query UTC time + +$ date -u + +# Expected output: Mon Aug 17 14:32:45 UTC 2025 + +``` + +```python + +# Example: Python time query + +import datetime +current_time = datetime.datetime.now() +utc_time = datetime.datetime.utcnow() +print(f"Local: {current_time}") +print(f"UTC: {utc_time}") + +``` + +```javascript + +// Example: JavaScript time query +const now = new Date(); +const utc = new Date().toISOString(); +console.log(`Local: ${now}`); +console.log(`UTC: ${utc}`); + +``` + +#### 5. **LLM Time Checking Workflow** + +1. **Query**: Actively query system for current time + +2. **Validate**: Confirm time data is reasonable and current + +3. **Format**: Convert to ISO 8601 format + +4. **Context**: Provide both local and UTC times when helpful + +5. **Document**: Show the source of time information + +#### 6. **Error Handling for Time Queries** + +- **If time query fails**: Ask user for current time or use "unknown time" + + with explanation + +- **If timezone unclear**: Default to UTC and ask for clarification + +- **If time seems wrong**: Verify with user before proceeding + +- **Always log**: Record when and how time was obtained + +#### 7. **Time Query Verification** + +Before using queried time, verify: + +- [ ] Time is recent (within last few minutes) + +- [ ] Timezone information is available + +- [ ] UTC conversion is accurate + +- [ ] Format follows ISO 8601 standard + +## Model Behavior Rules + +- **Never invent a "fake now"**: All "current time" references must come from + + the real system clock available at runtime. + +- **Check developer time zone**: If ambiguous, ask for clarification (e.g., + + "Should I use UTC or your local timezone?"). + +- **Format for clarity**: + + - Local time: `YYYY-MM-DDTHH:mm±hh:mm` + + - UTC equivalent (if needed): `YYYY-MM-DDTHH:mmZ` + +## Technical Implementation Notes + +### UTC Storage Principle + +- **Store all timestamps in UTC** in databases, logs, and serialized formats + +- **Convert to local time only for user display** + +- **Use ISO 8601 format** for all storage: `YYYY-MM-DDTHH:mm:ss.sssZ` + +### Common Implementation Patterns + +#### Database Storage + +```sql + +-- ✅ Good: Store in UTC +created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, +updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP + +``` + +#### API Responses + +```json + +// ✅ Good: Include both UTC and local time +{ + "eventTime": "2025-08-17T14:00:00Z", + "localTime": "2025-08-17T10:00:00-04:00", + "timezone": "America/New_York" +} + +``` + +#### Logging + +```python + +# ✅ Good: Log in UTC with timezone info + +logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)") + +``` + +### Timezone Handling Best Practices + +#### 1. Always Store Timezone Information + +- Include IANA timezone identifier (e.g., `America/New_York`) + +- Store UTC offset at time of creation + +- Handle daylight saving time transitions automatically + +#### 2. User Display Considerations + +- Convert UTC to user's preferred timezone + +- Show timezone abbreviation when helpful + +- Use relative time for recent events ("2 hours ago") + +#### 3. Edge Case Handling + +- **Daylight Saving Time**: Use timezone-aware libraries + +- **Leap Seconds**: Handle gracefully (rare but important) + +- **Invalid Times**: Validate before processing + +### Common Mistakes to Avoid + +#### 1. Timezone Confusion + +- ❌ **Don't**: Assume server timezone is user timezone + +- ✅ **Do**: Always convert UTC to user's local time for display + +#### 2. Format Inconsistency + +- ❌ **Don't**: Mix different time formats in the same system + +- ✅ **Do**: Standardize on ISO 8601 for all storage + +#### 3. Relative Time References + +- ❌ **Don't**: Use relative terms in persistent storage + +- ✅ **Do**: Convert relative terms to absolute timestamps immediately + +--- + +**See also**: + +- `.cursor/rules/development/time.mdc` for core principles + +- `.cursor/rules/development/time_examples.mdc` for practical examples + +**Status**: Active implementation guidelines +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: time.mdc +**Stakeholders**: Development team, DevOps team + +## Model Implementation Checklist + +### Before Time Implementation + +- [ ] **Time Context**: Understand what time information needs to be implemented +- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) +- [ ] **Platform Check**: Identify platform-specific time requirements +- [ ] **User Context**: Consider user's timezone and display preferences + +### During Time Implementation + +- [ ] **UTC Storage**: Use UTC for all system and log timestamps +- [ ] **Format Consistency**: Apply consistent time formatting patterns +- [ ] **Timezone Handling**: Properly handle timezone conversions +- [ ] **User Display**: Format times appropriately for user display + +### After Time Implementation + +- [ ] **Format Validation**: Verify time formats are correct and consistent +- [ ] **Cross-Platform Testing**: Test time handling across different platforms +- [ ] **Documentation**: Update relevant documentation with time patterns +- [ ] **User Experience**: Confirm time display is clear and user-friendly diff --git a/.cursor/rules/development/type_safety_guide.mdc b/.cursor/rules/development/type_safety_guide.mdc new file mode 100644 index 0000000..4fa17ee --- /dev/null +++ b/.cursor/rules/development/type_safety_guide.mdc @@ -0,0 +1,212 @@ +--- +description: when dealing with types and Typesript +alwaysApply: false +--- + +```json + +{ + "coaching_level": "light", + "socratic_max_questions": 7, + "verbosity": "concise", + "timebox_minutes": null, + "format_enforcement": "strict" +} + +``` + +# TypeScript Type Safety Guidelines + +**Author**: Matthew Raymer +**Date**: 2025-08-19 +**Status**: 🎯 **ACTIVE** - Type safety enforcement + +## Overview + +Practical rules to keep TypeScript strict and predictable. Minimize exceptions. + +## Core Rules + +1. **No `any`** + + - Use explicit types. If unknown, use `unknown` and **narrow** via guards. + +2. **Error handling uses guards** + + - Reuse guards from `src/interfaces/**` (e.g., `isDatabaseError`, + + `isApiError`). + + - Catch with `unknown`; never cast to `any`. + +3. **Dynamic property access is type‑safe** + + - Use `keyof` + `in` checks: + + ```ts + + obj[k as keyof typeof obj] + + ``` + + - Avoid `(obj as any)[k]`. + +## Type Safety Enforcement + +### Core Type Safety Rules + +- **No `any` Types**: Use explicit types or `unknown` with proper type guards + +- **Error Handling Uses Guards**: + + Implement and reuse type guards from `src/interfaces/**` + +- **Dynamic Property Access**: + + Use `keyof` + `in` checks for type-safe property access + +### Type Guard Patterns + +- **API Errors**: Use `isApiError(error)` guards for API error handling + +- **Database Errors**: + + Use `isDatabaseError(error)` guards for database operations + +- **Axios Errors**: + + Implement `isAxiosError(error)` guards for HTTP error handling + +### Implementation Guidelines + +- **Avoid Type Assertions**: + + Replace `as any` with proper type guards and interfaces + +- **Narrow Types Properly**: Use type guards to narrow `unknown` types safely + +- **Document Type Decisions**: Explain complex type structures and their purpose + +## Minimal Special Cases (document in PR when used) + +- **Vue refs / instances**: Use `ComponentPublicInstance` or specific + + component types for dynamic refs. + +- **3rd‑party libs without types**: Narrow immediately to a **known + + interface**; do not leave `any` hanging. + +## Patterns (short) + +### Database errors + +```ts + +try { await this.$addContact(contact); } +catch (e: unknown) { + if (isDatabaseError(e) && e.message.includes("Key already exists")) { + /* handle duplicate */ + } +} + +``` + +### API errors + +```ts + +try { await apiCall(); } +catch (e: unknown) { + if (isApiError(e)) { + const msg = e.response?.data?.error?.message; + } +} + +``` + +### Dynamic keys + +```ts + +const keys = Object.keys(newSettings).filter( +k => k in newSettings && newSettings[k as keyof typeof newSettings] !== + undefined +); + +``` + +## Checklists + +**Before commit** + +- [ ] No `any` (except documented, justified cases) + +- [ ] Errors handled via guards + +- [ ] Dynamic access uses `keyof`/`in` + +- [ ] Imports point to correct interfaces/types + +**Code review** + +- [ ] Hunt hidden `as any` + +- [ ] Guard‑based error paths verified + +- [ ] Dynamic ops are type‑safe + +- [ ] Prefer existing types over re‑inventing + +## Tools + +- `npm run lint-fix` — lint & auto‑fix + +- `npm run type-check` — strict type compilation (CI + pre‑release) + +- IDE: enable strict TS, ESLint/TS ESLint, Volar (Vue 3) + +## References + +- TS Handbook — + +- TS‑ESLint — + +- Vue 3 + TS — + +--- + +**Status**: Active type safety guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: TypeScript, ESLint, Vue 3 +**Stakeholders**: Development team + +- TS Handbook — + +- TS‑ESLint — + +- Vue 3 + TS — + +## Model Implementation Checklist + +### Before Type Implementation + +- [ ] **Type Analysis**: Understand current type definitions and usage +- [ ] **Interface Review**: Review existing interfaces and types +- [ ] **Error Handling**: Plan error handling with type guards +- [ ] **Dynamic Access**: Identify dynamic access patterns that need type safety + +### During Type Implementation + +- [ ] **Type Safety**: Ensure types provide meaningful safety guarantees +- [ ] **Error Guards**: Implement proper error handling with type guards +- [ ] **Dynamic Operations**: Use `keyof`/`in` for dynamic access +- [ ] **Import Validation**: Verify imports point to correct interfaces/types + +### After Type Implementation + +- [ ] **Linting Check**: Run `npm run lint-fix` to verify code quality +- [ ] **Type Check**: Run `npm run type-check` for strict type compilation +- [ ] **Code Review**: Hunt for hidden `as any` and type safety issues +- [ ] **Documentation**: Update type documentation and examples diff --git a/.cursor/rules/docs/documentation.mdc b/.cursor/rules/docs/documentation.mdc new file mode 100644 index 0000000..e6e57ba --- /dev/null +++ b/.cursor/rules/docs/documentation.mdc @@ -0,0 +1,37 @@ +--- +alwaysApply: false +--- +# Directive for Documentation Generation + +1. Produce a **small, focused set of documents** rather than an overwhelming volume. +2. Ensure the content is **maintainable and worth preserving**, so that humans + are motivated to keep it up to date. +3. Prioritize **educational value**: the documents must clearly explain the + workings of the system. +4. Avoid **shallow, generic, or filler explanations** often found in AI-generated + documentation. +5. Aim for **clarity, depth, and usefulness**, so readers gain genuine understanding. +6. Always check the local system date to determine current date. + +## Model Implementation Checklist + +### Before Documentation Creation + +- [ ] **Scope Definition**: Define what needs to be documented +- [ ] **Audience Analysis**: Identify target readers and their needs +- [ ] **Content Planning**: Plan focused, educational content structure +- [ ] **Maintenance Planning**: Ensure content will be worth preserving + +### During Documentation Creation + +- [ ] **Educational Focus**: Clearly explain how the system works +- [ ] **Depth and Clarity**: Provide genuine understanding, not surface explanations +- [ ] **Focused Content**: Keep documents small and focused on specific topics +- [ ] **Current Date**: Check local system date for time-sensitive content + +### After Documentation Creation + +- [ ] **Quality Review**: Ensure content is clear, deep, and useful +- [ ] **Maintainability Check**: Verify content motivates humans to keep it updated +- [ ] **Audience Validation**: Confirm content meets target reader needs +- [ ] **Integration**: Integrate with existing documentation structure diff --git a/.cursor/rules/docs/markdown_core.mdc b/.cursor/rules/docs/markdown_core.mdc new file mode 100644 index 0000000..74024bf --- /dev/null +++ b/.cursor/rules/docs/markdown_core.mdc @@ -0,0 +1,210 @@ +# Markdown Core Standards & Automation + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Core markdown standards and automation + +## Overview + +This file combines core markdown formatting standards with automation +guidelines. AI agents must follow these rules DURING content generation, +not apply them after the fact. + +**Primary Focus**: Create educational content that increases human +competence, not just technical descriptions. + +## AI Generation Guidelines + +### **MANDATORY**: Follow These Rules While Writing + +When generating markdown content, you MUST: + +1. **Line Length**: Never exceed 80 characters per line +2. **Blank Lines**: Always add blank lines around headings, lists, and + code blocks +3. **Structure**: Use proper heading hierarchy and document templates +4. **Formatting**: Apply consistent formatting patterns immediately +5. **Educational Value**: Focus on increasing reader competence and + understanding + +### **DO NOT**: Generate content that violates these rules + +- ❌ Generate long lines that need breaking +- ❌ Create content without proper blank line spacing +- ❌ Use inconsistent formatting patterns +- ❌ Assume post-processing will fix violations +- ❌ Focus only on technical details without educational context +- ❌ Assume reader has extensive prior knowledge + +### **DO**: Generate compliant content from the start + +- ✅ Write within 80-character limits +- ✅ Add blank lines around all structural elements +- ✅ Use established templates and patterns +- ✅ Apply formatting standards immediately +- ✅ Explain concepts before implementation details +- ✅ Provide context and motivation for technical choices +- ✅ Include examples that illustrate key concepts + +## Core Formatting Standards + +### Line Length + +- **Maximum line length**: 80 characters +- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line + length enforcement +- **Rationale**: Ensures readability across different screen sizes and + terminal widths + +### Blank Lines + +- **Headings**: Must be surrounded by blank lines above and below +- **Lists**: Must be surrounded by blank lines above and below +- **Code blocks**: Must be surrounded by blank lines above and below +- **Maximum consecutive blank lines**: 1 (no multiple blank lines) +- **File start**: No blank lines at the beginning of the file +- **File end**: Single newline character at the end + +### Whitespace + +- **No trailing spaces**: Remove all trailing whitespace from lines +- **No tabs**: Use spaces for indentation +- **Consistent indentation**: 2 spaces for list items and nested content + +## Heading Standards + +### Format + +- **Style**: ATX-style headings (`#`, `##`, `###`, etc.) +- **Case**: Title case for general headings +- **Code references**: Use backticks for file names and technical terms + - ✅ `### Current package.json Scripts` + - ❌ `### Current Package.json Scripts` + +### Hierarchy + +- **H1 (#)**: Document title only +- **H2 (##)**: Major sections +- **H3 (###)**: Subsections +- **H4 (####)**: Sub-subsections +- **H5+**: Avoid deeper nesting + +## List Standards + +### Unordered Lists + +- **Marker**: Use `-` (hyphen) consistently +- **Indentation**: 2 spaces for nested items +- **Blank lines**: Surround lists with blank lines + +### Ordered Lists + +- **Format**: `1.`, `2.`, `3.` (sequential numbering) +- **Indentation**: 2 spaces for nested items +- **Blank lines**: Surround lists with blank lines + +### Task Lists + +- **Format**: `- [ ]` for incomplete, `- [x]` for complete +- **Indentation**: 2 spaces for nested items +- **Blank lines**: Surround lists with blank lines + +## Educational Content Standards + +### **Content Structure for Learning** + +- **Concept First**: Explain what something is before how to use it +- **Context Matters**: Explain why and when to use a feature +- **Progressive Disclosure**: Start simple, add complexity gradually +- **Real Examples**: Use concrete, relatable scenarios +- **Common Questions**: Anticipate and answer reader questions + +### **Writing for Understanding** + +- **Conversational Tone**: Write as if explaining to a colleague +- **Active Voice**: "You can do this" not "This can be done" +- **Question Format**: "What happens when..." to engage thinking +- **Analogies**: Use familiar concepts to explain complex ideas +- **Limitations**: Clearly state what solutions don't do + +## Code Block Standards + +### Inline Code + +- **Format**: Single backticks for inline code +- **Use cases**: File names, commands, variables, technical terms +- **Examples**: `package.json`, `npm run build`, `VITE_PLATFORM` + +### Code Blocks + +- **Format**: Triple backticks with language specification +- **Language**: Always specify the language for syntax highlighting +- **Blank lines**: Surround with blank lines above and below + +## Automation System + +### Available Commands + +- **`npm run markdown:fix`** - Fix formatting in all markdown files + using markdownlint-cli2 --fix +- **`npm run markdown:check`** - Validate formatting without fixing + using markdownlint-cli2 + +### How It Works + +1. **AI Agent Compliance** (Primary): AI follows markdown rules during + generation +2. **Pre-commit Hooks** (Backup): Catches any remaining formatting + issues +3. **GitHub Actions** (Pre-merge): Validates formatting before merge + +### Benefits + +- **No more manual fixes** - AI generates compliant content from start +- **Consistent style** - All files follow same standards +- **Faster development** - No need to fix formatting manually + +## Model Implementation Checklist + +### Before Generating Markdown Content + +- [ ] **Line Length**: Ensure no line exceeds 80 characters +- [ ] **Blank Lines**: Add blank lines around headings, lists, and code blocks +- [ ] **Whitespace**: Remove all trailing spaces, use 2-space indentation +- [ ] **Headings**: Use ATX-style with proper hierarchy (H1 for title only) +- [ ] **Lists**: Use consistent markers (- for unordered, 1. for ordered) +- [ ] **Code**: Specify language for fenced blocks, use backticks for inline +- [ ] **Educational Focus**: Plan content structure for learning progression +- [ ] **Audience Consideration**: Identify target reader knowledge level + +### After Generating Markdown Content + +- [ ] **Validation**: Run `npm run markdown:check` to verify compliance +- [ ] **Auto-fix**: Use `npm run markdown:fix` if any issues found +- [ ] **Review**: Confirm content follows established templates and patterns +- [ ] **Cross-reference**: Link to related documentation and templates +- [ ] **Educational Review**: Verify content increases reader competence +- [ ] **Example Validation**: Ensure examples illustrate key concepts clearly + +### Quality Assurance + +- [ ] **Readability**: Content is clear and follows project conventions +- [ ] **Consistency**: Formatting matches existing documentation style +- [ ] **Completeness**: All required sections and information included +- [ ] **Accuracy**: Technical details are correct and up-to-date +- [ ] **Educational Value**: Content increases reader understanding and competence +- [ ] **Context Clarity**: Reader understands when and why to use the information + +--- + +**See also**: + +- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow +- `.cursor/rules/docs/markdown_templates.mdc` for document templates +- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows + +**Status**: Active core standards and automation +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Documentation team, Development team diff --git a/.cursor/rules/docs/markdown_templates.mdc b/.cursor/rules/docs/markdown_templates.mdc new file mode 100644 index 0000000..eacb672 --- /dev/null +++ b/.cursor/rules/docs/markdown_templates.mdc @@ -0,0 +1,314 @@ +# Markdown Templates & Examples + +> **Agent role**: Reference this file for document templates, structure, +> and examples when creating new documentation. +> +> **Focus**: Create educational content that increases human competence, +> not just technical descriptions. + +## Document Templates + +### Standard Document Template + +```markdown +# Document Title + +**Author**: Matthew Raymer +**Date**: YYYY-MM-DD +**Status**: 🎯 **STATUS** - Brief description + +## Overview + +Brief description of the document's purpose and scope. + +**Educational Goal**: What will the reader learn and how will it increase +their competence? + +## Current State + +Description of current situation or problem. + +**Why This Matters**: Explain the business value and user benefit of +addressing this situation. + +## Implementation Plan + +### Phase 1: Foundation + +- [ ] Task 1 +- [ ] Task 2 + +**Learning Context**: What concepts should the reader understand before +proceeding with implementation? + +## Next Steps + +1. **Review and approve plan** +2. **Begin implementation** +3. **Test and validate** + +**Continued Learning**: Where can the reader go next to deepen their +understanding? + +--- + +**Status**: Ready for implementation +**Priority**: Medium +**Estimated Effort**: X days +**Dependencies**: None +**Stakeholders**: Development team +``` + +### Technical Specification Template + +```markdown +# Technical Specification: [Feature Name] + +**Author**: Matthew Raymer +**Date**: YYYY-MM-DD +**Status**: 🎯 **DRAFT** - Under Review + +## Overview + +Brief description of the technical specification. + +**Business Context**: Why is this specification needed and what problem +does it solve for users? + +## Requirements + +### Functional Requirements + +- [ ] Requirement 1 +- [ ] Requirement 2 + +### Non-Functional Requirements + +- [ ] Performance requirement +- [ ] Security requirement + +## Technical Design + +### Architecture + +Description of the technical architecture. + +**Design Rationale**: Why was this architecture chosen over alternatives? +What are the trade-offs and benefits? + +### Data Models + +```typescript +interface ExampleModel { + id: string; + name: string; + createdAt: Date; +} +``` + +### API Design + +```typescript +interface APIResponse { + success: boolean; + data: T; + error?: string; +} +``` + +## Testing Strategy + +- [ ] Unit tests + +**Learning from Testing**: What insights does testing provide about the +system's behavior and design? + +--- + +## Educational Documentation Template + +### **Concept Explanation Template** + +```markdown +## What is [Concept Name]? + +Brief, clear definition of the concept. + +## Why Does [Concept Name] Matter? + +Explain the business value and user benefit. + +## How Does [Concept Name] Work? + +High-level explanation of the mechanism. + +## When Would You Use [Concept Name]? + +Real-world scenarios and use cases. + +## Common Misconceptions + +Address typical misunderstandings. + +## Examples + +Concrete examples that illustrate the concept. + +## Next Steps + +Where to learn more about related concepts. +``` + +### **Tutorial Template** + +```markdown +## Learning Objective + +What the reader will accomplish by the end. + +## Prerequisites + +What the reader should know before starting. + +## Step-by-Step Guide + +1. **Step 1**: What to do and why +2. **Step 2**: What to do and why +3. **Step 3**: What to do and why + +## Verification + +How to confirm the tutorial was successful. + +## Troubleshooting + +Common issues and how to resolve them. + +## What You've Learned + +Summary of key concepts and skills. + +## Next Steps + +Where to apply this knowledge next. +``` +- [ ] Integration tests +- [ ] E2E tests + +--- + +**Status**: Draft +**Priority**: High +**Estimated Effort**: X days +**Dependencies**: None +**Stakeholders**: Development team + +``` + +## Content Examples + +### JSON Examples + +```json +{ + "property": "value", + "nested": { + "property": "value" + } +} +``` + +### Shell Commands + +```bash +# Command with comment +npm run build:web + +# Multi-line command +VITE_GIT_HASH=`git log -1 --pretty=format:%h` \ + vite build --config vite.config.web.mts +``` + +### TypeScript Examples + +```typescript +// Function with JSDoc +const getEnvironmentConfig = (env: string) => { + switch (env) { + case 'prod': + return { /* production settings */ }; + default: + return { /* development settings */ }; + } +}; +``` + +## File Structure Standards + +### Document Header + +```markdown +# Document Title + +**Author**: Matthew Raymer +**Date**: YYYY-MM-DD +**Status**: 🎯 **STATUS** - Brief description + +## Overview + +Brief description of the document's purpose and scope. +``` + +### Section Organization + +Standard sections: Overview, Current State, Implementation Plan, +Technical Details, Testing & Validation, Next Steps + +## Common Patterns + +Standard implementation plans follow Phase 1 (Foundation), Phase 2 +(Features), Phase 3 (Testing & Polish) structure. + +## Model Implementation Checklist + +### Before Using Templates + +- [ ] **Template Selection**: Choose appropriate template for document type +- [ ] **Structure Review**: Understand required sections and organization +- [ ] **Content Planning**: Plan what information goes in each section +- [ ] **Audience Analysis**: Ensure template matches target audience needs + +### During Template Usage + +- [ ] **Section Completion**: Fill in all required sections completely +- [ ] **Example Integration**: Include relevant code examples and patterns +- [ ] **Formatting Consistency**: Apply markdown standards from core rules +- [ ] **Cross-references**: Link to related documentation and resources + +### After Template Usage + +- [ ] **Content Review**: Verify all sections contain appropriate content +- [ ] **Formatting Check**: Run `npm run markdown:check` for compliance +- [ ] **Template Validation**: Confirm document follows template structure +- [ ] **Quality Assessment**: Ensure content meets project standards + +### Template-Specific Requirements + +- [ ] **Standard Documents**: Include all required metadata and sections +- [ ] **Technical Specs**: Complete all requirement and design sections +- [ ] **Implementation Plans**: Define clear phases and milestones +- [ ] **Examples**: Provide relevant, working code examples + +--- + +**See also**: + +- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow +- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards +- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows + +**Status**: Active templates and examples +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: markdown_core.mdc +**Stakeholders**: Documentation team, Development team diff --git a/.cursor/rules/docs/markdown_workflow.mdc b/.cursor/rules/docs/markdown_workflow.mdc new file mode 100644 index 0000000..0afadd2 --- /dev/null +++ b/.cursor/rules/docs/markdown_workflow.mdc @@ -0,0 +1,168 @@ +# Markdown Workflow & Validation + +> **Agent role**: Reference this file for markdown validation rules, +> enforcement procedures, and workflow management. + +## Markdownlint Configuration + +### Core Rules + +```json +{ + "MD013": { "line_length": 80, "code_blocks": false }, + "MD012": true, + "MD022": true, + "MD031": true, + "MD032": true, + "MD047": true, + "MD009": true, + "MD004": { "style": "dash" } +} +``` + +### Rule Explanations + +- **MD013**: Line length (80 chars, disabled for code blocks) +- **MD012**: No multiple consecutive blank lines +- **MD022**: Headings should be surrounded by blank lines +- **MD031**: Fenced code blocks should be surrounded by blank lines +- **MD032**: Lists should be surrounded by blank lines +- **MD047**: Files should end with a single newline +- **MD009**: No trailing spaces +- **MD004**: Consistent list markers (dash style) + +## Validation Commands + +### Check All MDC Files + +```bash +npm run markdown:check +``` + +### Auto-fix Formatting Issues + +```bash +npm run markdown:fix +``` + +### Check Single File + +```bash +npx markdownlint-cli2 .cursor/rules/filename.mdc +``` + +## Enforcement Workflow + +### Pre-commit Hooks + +- **Automatic**: `lint-staged` runs `markdownlint-cli2 --fix` on all + staged `.mdc` files +- **Result**: Files are automatically formatted before commit +- **Blocking**: Commits with unfixable violations are blocked + +### CI/CD Integration + +- **Build Pipeline**: Include markdownlint in automated builds +- **Quality Reports**: Generate documentation quality metrics +- **Build Failure**: Fail builds with critical violations + +### Team Guidelines + +- **PR Requirements**: All documentation PRs must pass markdownlint +- **Templates**: Use provided templates for new documents +- **Patterns**: Follow established patterns for consistency +- **Auto-fixing**: Let automation handle formatting, focus on content + +## Quality Assurance + +### Validation Checklist + +- [ ] All files pass `npm run markdown:check` +- [ ] Line length under 80 characters +- [ ] Proper blank line spacing around elements +- [ ] No trailing spaces +- [ ] Consistent list markers +- [ ] Proper heading hierarchy +- [ ] Code blocks have language specification + +### Common Issues & Fixes + +#### Trailing Spaces + +```bash +# Remove trailing spaces +sed -i 's/[[:space:]]*$//' .cursor/rules/**/*.mdc +``` + +#### Multiple Blank Lines + +```bash +# Remove multiple blank lines +sed -i '/^$/N;/^\n$/D' .cursor/rules/**/*.mdc +``` + +#### Missing Newlines + +```bash +# Add newline at end if missing +find .cursor/rules -name "*.mdc" -exec sed -i -e '$a\' {} \; +``` + +## Integration Points + +### Git Workflow + +1. **Edit**: Make changes to MDC files +2. **Stage**: `git add .cursor/rules/filename.mdc` +3. **Auto-fix**: `lint-staged` runs `markdownlint-cli2 --fix` +4. **Commit**: Changes are committed with perfect formatting + +### Development Workflow + +1. **Create/Edit**: Use templates from `markdown_templates.mdc` +2. **Validate**: Run `npm run markdown:check` before committing +3. **Auto-fix**: Use `npm run markdown:fix` for bulk fixes +4. **Review**: Ensure content quality, not just formatting + +## Model Implementation Checklist + +### Before Starting Workflow + +- [ ] **Configuration Review**: Understand markdownlint rules and settings +- [ ] **Tool Availability**: Ensure markdownlint-cli2 is installed and working +- [ ] **File Scope**: Identify which files need validation or fixing +- [ ] **Backup Strategy**: Consider backing up files before bulk operations + +### During Workflow Execution + +- [ ] **Validation First**: Run `npm run markdown:check` to identify issues +- [ ] **Issue Analysis**: Review and understand each validation error +- [ ] **Auto-fix Application**: Use `npm run markdown:fix` for automatic fixes +- [ ] **Manual Review**: Check files that couldn't be auto-fixed + +### After Workflow Completion + +- [ ] **Final Validation**: Confirm all files pass `npm run markdown:check` +- [ ] **Quality Review**: Verify formatting meets project standards +- [ ] **Documentation Update**: Update any related documentation or guides +- [ ] **Team Communication**: Share workflow results and any manual fixes needed + +### Workflow-Specific Requirements + +- [ ] **Pre-commit Hooks**: Ensure lint-staged configuration is working +- [ ] **CI/CD Integration**: Verify build pipeline includes markdown validation +- [ ] **Team Guidelines**: Confirm all team members understand the workflow +- [ ] **Error Resolution**: Document common issues and their solutions + +--- + +**See also**: + +- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards +- `.cursor/rules/docs/markdown_templates.mdc` for document templates + +**Status**: Active workflow and validation +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: markdown_core.mdc, markdown_templates.mdc +**Stakeholders**: Development team, Documentation team diff --git a/.cursor/rules/documentation.mdc b/.cursor/rules/documentation.mdc deleted file mode 100644 index 4b02917..0000000 --- a/.cursor/rules/documentation.mdc +++ /dev/null @@ -1,19 +0,0 @@ ---- -globs: *.md -alwaysApply: false ---- - -INITIAL_PLAN.md is unique to projects built inhouse and must never be deleted. -Maintain traditional files (README, CHANGELOG, BUILDING, etc.) -Any ad hoc files must always be put into docs folder -The docs folder must use sub-folders to classify documents by -There must never be more than seven folders at any sub-folder of the docs tree -Keep documents no more than seven in number for a folder. -If you need more documents than seven, make sub-folders to classify or re-classify documents. -Re-use documents by ammending or editing but always version them in git. -put documentation at the file, classs, and method heads - -Documents themselves must: - -Headings should be surrounded by blank lines -Lists should be surrounded by blank \ No newline at end of file diff --git a/.cursor/rules/features/camera-implementation.mdc b/.cursor/rules/features/camera-implementation.mdc new file mode 100644 index 0000000..78c90e5 --- /dev/null +++ b/.cursor/rules/features/camera-implementation.mdc @@ -0,0 +1,163 @@ +# Camera Implementation Documentation + +## Overview + +This document describes how camera functionality is implemented across the +TimeSafari application. The application uses cameras for two main purposes: + +1. QR Code scanning + +2. Photo capture + +## Components + +### QRScannerDialog.vue + +Primary component for QR code scanning in web browsers. + +**Key Features:** + +- Uses `qrcode-stream` for web-based QR scanning + +- Supports both front and back cameras + +- Provides real-time camera status feedback + +- Implements error handling with user-friendly messages + +- Includes camera switching functionality + +**Camera Access Flow:** + +1. Checks for camera API availability + +2. Enumerates available video devices + +3. Requests camera permissions + +4. Initializes camera stream with preferred settings + +5. Handles various error conditions with specific messages + +### PhotoDialog.vue + +Component for photo capture and selection. + +**Key Features:** + +- Cross-platform photo capture interface + +- Image cropping capabilities + +- File selection fallback + +- Unified interface for different platforms + +## Services + +### QRScanner Services + +#### WebDialogQRScanner + +Web-based implementation of QR scanning. + +**Key Methods:** + +- `checkPermissions()`: Verifies camera permission status + +- `requestPermissions()`: Requests camera access + +- `isSupported()`: Checks for camera API support + +- Handles various error conditions with specific messages + +#### CapacitorQRScanner + +Native implementation using Capacitor's MLKit. + +**Key Features:** + +- Uses `@capacitor-mlkit/barcode-scanning` + +- Supports both front and back cameras + +- Implements permission management + +- Provides continuous scanning capability + +### Platform Services + +#### WebPlatformService + +Web-specific implementation of platform features. + +**Camera Capabilities:** + +- Uses HTML5 file input with capture attribute + +- Falls back to file selection if camera unavailable + +- Processes captured images for consistent format + +#### CapacitorPlatformService + +Native implementation using Capacitor. + +**Camera Features:** + +- Uses `Camera.getPhoto()` for native camera access + +- Supports image editing + +- Configures high-quality image capture + +- Handles base64 image processing + +#### ElectronPlatformService + +Desktop implementation (currently unimplemented). + +--- + +**See also**: + +- `.cursor/rules/features/camera_technical.mdc` for + + detailed technical implementation + +- `.cursor/rules/features/camera_platforms.mdc` for platform-specific details + +**Status**: Active camera implementation overview +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Camera feature team + +- iOS and Android devices + +- Desktop platforms + +- Various network conditions + +## Model Implementation Checklist + +### Before Camera Implementation + +- [ ] **Platform Analysis**: Understand camera requirements across all platforms +- [ ] **Feature Planning**: Plan QR scanning and photo capture features +- [ ] **Service Planning**: Plan camera service architecture +- [ ] **Testing Strategy**: Plan testing across web, mobile, and desktop + +### During Camera Implementation + +- [ ] **Component Development**: Implement QRScannerDialog and PhotoDialog +- [ ] **Service Implementation**: Implement platform-specific camera services +- [ ] **Permission Handling**: Implement proper camera permission management +- [ ] **Error Handling**: Implement graceful error handling for camera failures + +### After Camera Implementation + +- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms +- [ ] **Feature Validation**: Verify QR scanning and photo capture work correctly +- [ ] **Performance Testing**: Ensure camera performance meets requirements +- [ ] **Documentation Update**: Update camera implementation documentation diff --git a/.cursor/rules/features/camera_platforms.mdc b/.cursor/rules/features/camera_platforms.mdc new file mode 100644 index 0000000..a7a3566 --- /dev/null +++ b/.cursor/rules/features/camera_platforms.mdc @@ -0,0 +1,225 @@ +# Camera Platform-Specific Implementation + +> **Agent role**: + Reference this file for platform-specific camera implementation details. + +## Web Platform + +### Implementation Details + +- Uses `getUserMedia` API for camera access + +- Implements fallback to file input if camera unavailable + +- Handles browser compatibility issues + +- Requires HTTPS for camera access + +### Browser Support + +- Chrome: Full support + +- Firefox: Full support + +- Safari: Limited support + +- Edge: Full support + +### Fallback Mechanisms + +1. Camera access via getUserMedia + +2. File input for image upload + +3. Drag and drop support + +4. Clipboard paste support + +## Mobile Platform (Capacitor) + +### iOS Implementation + +- Uses `@capacitor-mlkit/barcode-scanning` + +- Implements proper permission handling + +- Supports both front and back cameras + +- Handles camera switching + +### Android Implementation + +- Uses `@capacitor-mlkit/barcode-scanning` + +- Implements proper permission handling + +- Supports both front and back cameras + +- Handles camera switching + +### Permission Handling + +- Camera permissions requested at runtime + +- Permission state tracked and cached + +- Graceful handling of denied permissions + +- Clear user guidance for enabling permissions + +## Desktop Platform (Electron) + +### Current Status + +- Camera implementation pending + +- Will use platform-specific APIs + +- Requires proper permission handling + +- Will support both built-in and external cameras + +### Planned Implementation + +- Native camera access via Electron + +- Platform-specific camera APIs + +- Proper permission handling + +- Camera switching support + +## Platform Detection + +### Implementation + +- Uses `PlatformServiceFactory` for platform detection + +- Implements platform-specific camera services + +- Handles platform-specific error conditions + +- Provides platform-specific user guidance + +### Service Selection + +- Web: `WebPlatformService` + +- Mobile: `CapacitorPlatformService` + +- Desktop: `ElectronPlatformService` + +## Cross-Platform Compatibility + +### Common Interface + +- Unified camera service interface + +- Platform-specific implementations + +- Consistent error handling + +- Unified user experience + +### Feature Parity + +- Core camera functionality across platforms + +- Platform-specific optimizations + +- Consistent user interface + +- Unified error messages + +## Platform-Specific Features + +### Web + +- Browser-based camera access + +- File upload fallback + +- Drag and drop support + +- Clipboard paste support + +### Mobile + +- Native camera access + +- Barcode scanning + +- Photo capture + +- Camera switching + +### Desktop + +- Native camera access (planned) + +- External camera support (planned) + +- Advanced camera controls (planned) + +## Testing Strategy + +### Platform Coverage + +- Web: Multiple browsers + +- Mobile: iOS and Android devices + +- Desktop: Windows, macOS, Linux + +### Test Scenarios + +- Permission handling + +- Camera access + +- Error conditions + +- Platform compatibility + +- Performance metrics + +--- + +**See also**: + +- `.cursor/rules/features/camera-implementation.mdc` for + + core implementation overview + +- `.cursor/rules/features/camera_technical.mdc` for + + technical implementation details + +**Status**: Active platform-specific implementation guide +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: camera-implementation.mdc +**Stakeholders**: Development team, Platform team + +## Model Implementation Checklist + +### Before Camera Platform Implementation + +- [ ] **Platform Analysis**: Identify target platforms and their camera capabilities +- [ ] **Feature Planning**: Plan platform-specific camera features +- [ ] **Integration Planning**: Plan integration with existing camera systems +- [ ] **Testing Strategy**: Plan testing across all target platforms + +### During Camera Platform Implementation + +- [ ] **Platform Services**: Implement platform-specific camera functionality +- [ ] **Feature Development**: Implement planned camera features for each platform +- [ ] **Integration**: Integrate with existing camera infrastructure +- [ ] **Performance Optimization**: Optimize camera performance for each platform + +### After Camera Platform Implementation + +- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms +- [ ] **Feature Validation**: Verify all planned features work correctly +- [ ] **Performance Testing**: Ensure camera performance meets requirements +- [ ] **Documentation Update**: Update platform-specific camera documentation diff --git a/.cursor/rules/features/camera_technical.mdc b/.cursor/rules/features/camera_technical.mdc new file mode 100644 index 0000000..4f69a3d --- /dev/null +++ b/.cursor/rules/features/camera_technical.mdc @@ -0,0 +1,203 @@ +# Camera Technical Implementation — Details and Best Practices + +> **Agent role**: Reference this file for + detailed technical implementation when working with camera features. + +## Platform-Specific Considerations + +### iOS + +- Requires `NSCameraUsageDescription` in Info.plist + +- Supports both front and back cameras + +- Implements proper permission handling + +### Android + +- Requires camera permissions in manifest + +- Supports both front and back cameras + +- Handles permission requests through Capacitor + +### Web + +- Requires HTTPS for camera access + +- Implements fallback mechanisms + +- Handles browser compatibility issues + +## Error Handling + +### Common Error Scenarios + +1. No camera found + +2. Permission denied + +3. Camera in use by another application + +4. HTTPS required + +5. Browser compatibility issues + +### Error Response + +- User-friendly error messages + +- Troubleshooting tips + +- Clear instructions for resolution + +- Platform-specific guidance + +## Security Considerations + +### Permission Management + +- Explicit permission requests + +- Permission state tracking + +- Graceful handling of denied permissions + +### Data Handling + +- Secure image processing + +- Proper cleanup of camera resources + +- No persistent storage of camera data + +## Best Practices + +### Camera Access + +1. Always check for camera availability + +2. Request permissions explicitly + +3. Handle all error conditions + +4. Provide clear user feedback + +5. Implement proper cleanup + +### Performance + +1. Optimize camera resolution + +2. Implement proper resource cleanup + +3. Handle camera switching efficiently + +4. Manage memory usage + +### User Experience + +1. Clear status indicators + +2. Intuitive camera controls + +3. Helpful error messages + +4. Smooth camera switching + +5. Responsive UI feedback + +## Future Improvements + +### Planned Enhancements + +1. Implement Electron camera support + +2. Add advanced camera features + +3. Improve error handling + +4. Enhance user feedback + +5. Optimize performance + +### Known Issues + +1. Electron camera implementation pending + +2. Some browser compatibility limitations + +3. Platform-specific quirks to address + +## Dependencies + +### Key Packages + +- `@capacitor-mlkit/barcode-scanning` + +- `qrcode-stream` + +- `vue-picture-cropper` + +- Platform-specific camera APIs + +## Testing + +### Test Scenarios + +1. Permission handling + +2. Camera switching + +3. Error conditions + +4. Platform compatibility + +5. Performance metrics + +### Test Environment + +- Multiple browsers + +- iOS and Android devices + +- Desktop platforms + +--- + +**See also**: + +- `.cursor/rules/features/camera-implementation.mdc` for + + core implementation overview + +- `.cursor/rules/features/camera_platforms.mdc` for platform-specific details + +**Status**: Active technical implementation guide +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: camera-implementation.mdc +**Stakeholders**: Development team, Camera feature team + +## Model Implementation Checklist + +### Before Camera Implementation + +- [ ] **Platform Analysis**: Identify target platforms and camera capabilities +- [ ] **Permission Planning**: Plan permission handling for camera access +- [ ] **Dependency Review**: Review required camera packages and APIs +- [ ] **Testing Strategy**: Plan testing across multiple platforms + +### During Camera Implementation + +- [ ] **Platform Services**: Implement platform-specific camera services +- [ ] **Permission Handling**: Implement proper camera permission handling +- [ ] **Error Handling**: Implement graceful error handling for camera failures +- [ ] **Performance Optimization**: Optimize camera performance and responsiveness + +### After Camera Implementation + +- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms +- [ ] **Permission Testing**: Test permission handling and user feedback +- [ ] **Performance Validation**: Verify camera performance meets requirements +- [ ] **Documentation Update**: Update camera technical documentation diff --git a/.cursor/rules/general_development.mdc b/.cursor/rules/general_development.mdc deleted file mode 100644 index 3dca909..0000000 --- a/.cursor/rules/general_development.mdc +++ /dev/null @@ -1,3 +0,0 @@ ---- -alwaysApply: true ---- diff --git a/.cursor/rules/logging.mdc b/.cursor/rules/logging.mdc deleted file mode 100644 index 777f159..0000000 --- a/.cursor/rules/logging.mdc +++ /dev/null @@ -1,6 +0,0 @@ ---- -alwaysApply: true ---- -Always use structlog with rich contextual annotation -All logs should go to rsyslog -Logs showing in console should be set to whatever is needed at that time. diff --git a/.cursor/rules/meta_bug_diagnosis.mdc b/.cursor/rules/meta_bug_diagnosis.mdc new file mode 100644 index 0000000..2231934 --- /dev/null +++ b/.cursor/rules/meta_bug_diagnosis.mdc @@ -0,0 +1,288 @@ +# Meta-Rule: Bug Diagnosis Workflow + +**Author**: Matthew Raymer +**Date**: August 24, 2025 +**Status**: 🎯 **ACTIVE** - Core workflow for all bug investigation + +## Purpose + +This meta-rule defines the systematic approach for investigating and diagnosing +bugs, defects, and unexpected behaviors in the TimeSafari application. It ensures +consistent, thorough, and efficient problem-solving workflows. + +## Workflow Constraints + +**This meta-rule enforces DIAGNOSIS MODE for all bundled sub-rules:** + +```json +{ + "workflowMode": "diagnosis", + "constraints": { + "mode": "read_only", + "forbidden": ["modify", "create", "build", "commit"], + "required": "complete_investigation_before_fixing" + } +} +``` + +**All bundled sub-rules automatically inherit these constraints.** + +## Workflow State Update + +**When this meta-rule is invoked, update the workflow state file:** + +```json +{ + "currentMode": "diagnosis", + "lastInvoked": "meta_bug_diagnosis.mdc", + "timestamp": "2025-01-27T15:30:00Z", + "constraints": { + "mode": "read_only", + "forbidden": ["modify", "create", "build", "commit"], + "allowed": ["read", "search", "analyze", "document"], + "required": "complete_investigation_before_fixing" + } +} +``` + +**State File Location**: `.cursor/rules/.workflow_state.json` + +**This enables the core always-on rule to enforce diagnosis mode constraints.** + +## When to Use + +**ALWAYS** - Apply this workflow to every bug investigation, regardless of +severity or complexity. This ensures systematic problem-solving and prevents +common investigation pitfalls. + +## Bundled Rules + +### **Investigation Foundation** + +- **`development/research_diagnostic.mdc`** - Research and investigation methodologies +- **`development/logging_standards.mdc`** - Logging and debugging best practices +- **`development/type_safety_guide.mdc`** - Type safety and error prevention + +### **Development Workflow** + +- **`workflow/version_control.mdc`** - Version control during investigation +- **`development/software_development.mdc`** - Development best practices + +## Critical Development Constraints + +### **🚫 NEVER Use Build Commands During Diagnosis** + +**Critical Rule**: Never use `npm run build:web` or similar build commands during bug diagnosis + +- **Reason**: These commands block the chat and prevent effective troubleshooting +- **Impact**: Blocks user interaction, prevents real-time problem solving +- **Alternative**: Use safe, fast commands for investigation +- **When to use build**: Only after diagnosis is complete and fixes are ready for testing + +### **Safe Diagnosis Commands** + +✅ **Safe to use during diagnosis:** +- `npm run lint-fix` - Syntax and style checking +- `npm run type-check` - TypeScript validation (if available) +- `git status` - Version control status +- `ls` / `dir` - File listing +- `cat` / `read_file` - File content inspection +- `grep_search` - Text pattern searching + +❌ **Never use during diagnosis:** +- `npm run build:web` - Blocks chat +- `npm run build:electron` - Blocks chat +- `npm run build:capacitor` - Blocks chat +- Any long-running build processes + +## Investigation Workflow + +### **Phase 1: Problem Definition** + +1. **Gather Evidence** + - Error messages and stack traces + - User-reported symptoms + - System logs and timestamps + - Reproduction steps + +2. **Context Analysis** + - When did the problem start? + - What changed recently? + - Which platform/environment? + - User actions leading to the issue + +### **Phase 2: Systematic Investigation** + +1. **Code Inspection** + - Relevant file examination + - Import and dependency analysis + - Syntax and type checking + - Logic flow analysis + +2. **Environment Analysis** + - Platform-specific considerations + - Configuration and settings + - Database and storage state + - Network and API connectivity + +### **Phase 3: Root Cause Identification** + +1. **Pattern Recognition** + - Similar issues in codebase + - Common failure modes + - Platform-specific behaviors + - Recent changes impact + +2. **Hypothesis Testing** + - Targeted code changes + - Configuration modifications + - Environment adjustments + - Systematic elimination + +## Investigation Techniques + +### **Safe Code Analysis** + +- **File Reading**: Use `read_file` tool for targeted inspection +- **Pattern Searching**: Use `grep_search` for code patterns +- **Semantic Search**: Use `codebase_search` for related functionality +- **Import Tracing**: Follow dependency chains systematically + +### **Error Analysis** + +- **Stack Trace Analysis**: Identify error origin and propagation +- **Log Correlation**: Match errors with system events +- **Timeline Reconstruction**: Build sequence of events +- **Context Preservation**: Maintain investigation state + +### **Platform Considerations** + +- **Web Platform**: Browser-specific behaviors and limitations +- **Electron Platform**: Desktop app considerations +- **Capacitor Platform**: Mobile app behaviors +- **Cross-Platform**: Shared vs. platform-specific code + +## Evidence Collection Standards + +### **Timestamps** + +- **UTC Format**: All timestamps in UTC for consistency +- **Precision**: Include milliseconds for precise correlation +- **Context**: Include relevant system state information +- **Correlation**: Link events across different components + +### **Error Context** + +- **Full Error Objects**: Capture complete error information +- **Stack Traces**: Preserve call stack for analysis +- **User Actions**: Document steps leading to error +- **System State**: Capture relevant configuration and state + +### **Reproduction Steps** + +- **Clear Sequence**: Step-by-step reproduction instructions +- **Environment Details**: Platform, version, configuration +- **Data Requirements**: Required data or state +- **Expected vs. Actual**: Clear behavior comparison + +## Investigation Documentation + +### **Problem Summary** + +- **Issue Description**: Clear, concise problem statement +- **Impact Assessment**: Severity and user impact +- **Scope Definition**: Affected components and users +- **Priority Level**: Based on impact and frequency + +### **Investigation Log** + +- **Timeline**: Chronological investigation steps +- **Evidence**: Collected information and findings +- **Hypotheses**: Tested theories and results +- **Conclusions**: Root cause identification + +### **Solution Requirements** + +- **Fix Description**: Required changes and approach +- **Testing Strategy**: Validation and verification steps +- **Rollback Plan**: Reversion strategy if needed +- **Prevention Measures**: Future issue prevention + +## Quality Standards + +### **Investigation Completeness** + +- **Evidence Sufficiency**: Adequate information for root cause +- **Alternative Theories**: Considered and eliminated +- **Platform Coverage**: All relevant platforms investigated +- **Edge Cases**: Unusual scenarios considered + +### **Documentation Quality** + +- **Clear Communication**: Understandable to all stakeholders +- **Technical Accuracy**: Precise technical details +- **Actionable Insights**: Clear next steps and recommendations +- **Knowledge Transfer**: Lessons learned for future reference + +## Common Pitfalls + +### **Investigation Mistakes** + +- **Jumping to Solutions**: Implementing fixes before understanding +- **Insufficient Evidence**: Making assumptions without data +- **Platform Blindness**: Ignoring platform-specific behaviors +- **Scope Creep**: Expanding investigation beyond original problem + +### **Communication Issues** + +- **Technical Jargon**: Using unclear terminology +- **Missing Context**: Insufficient background information +- **Unclear Recommendations**: Vague or ambiguous next steps +- **Poor Documentation**: Incomplete or unclear investigation records + +## Success Criteria + +- [ ] **Problem clearly defined** with sufficient evidence +- [ ] **Root cause identified** through systematic investigation +- [ ] **Solution approach determined** with clear requirements +- [ ] **Documentation complete** for knowledge transfer +- [ ] **No chat-blocking commands** used during investigation +- [ ] **Platform considerations** properly addressed +- [ ] **Timeline and context** properly documented + +## Integration with Other Meta-Rules + +### **Bug Fixing** + +- **Investigation Results**: Provide foundation for fix implementation +- **Solution Requirements**: Define what needs to be built +- **Testing Strategy**: Inform validation approach +- **Documentation**: Support implementation guidance + +### **Feature Planning** + +- **Root Cause Analysis**: Identify systemic issues +- **Prevention Measures**: Plan future issue avoidance +- **Architecture Improvements**: Identify structural enhancements +- **Process Refinements**: Improve development workflows + +### **Research and Documentation** + +- **Knowledge Base**: Contribute to troubleshooting guides +- **Pattern Recognition**: Identify common failure modes +- **Best Practices**: Develop investigation methodologies +- **Team Training**: Improve investigation capabilities + +--- + +**See also**: + +- `.cursor/rules/meta_bug_fixing.mdc` for implementing fixes +- `.cursor/rules/meta_feature_planning.mdc` for planning improvements +- `.cursor/rules/meta_documentation.mdc` for documentation standards + +**Status**: Active meta-rule for bug diagnosis +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, QA team, DevOps team diff --git a/.cursor/rules/meta_bug_fixing.mdc b/.cursor/rules/meta_bug_fixing.mdc new file mode 100644 index 0000000..538b5ca --- /dev/null +++ b/.cursor/rules/meta_bug_fixing.mdc @@ -0,0 +1,214 @@ +# Meta-Rule: Bug Fixing + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Bug fix implementation workflow bundling + +## Purpose + +This meta-rule bundles all the rules needed for implementing bug fixes +with proper testing and validation. Use this after diagnosis when +implementing the actual fix. + +## Workflow Constraints + +**This meta-rule enforces FIXING MODE for all bundled sub-rules:** + +```json +{ + "workflowMode": "fixing", + "constraints": { + "mode": "implementation", + "allowed": ["modify", "create", "build", "test", "commit"], + "required": "diagnosis_complete_before_fixing" + } +} +``` + +**All bundled sub-rules automatically inherit these constraints.** + +## Workflow State Update + +**When this meta-rule is invoked, update the workflow state file:** + +```json +{ + "currentMode": "fixing", + "lastInvoked": "meta_bug_fixing.mdc", + "timestamp": "2025-01-27T15:30:00Z", + "constraints": { + "mode": "implementation", + "allowed": ["modify", "create", "build", "test", "commit"], + "forbidden": [], + "required": "diagnosis_complete_before_fixing" + } +} +``` + +**State File Location**: `.cursor/rules/.workflow_state.json` + +**This enables the core always-on rule to enforce fixing mode constraints.** + +## When to Use + +- **Post-Diagnosis**: After root cause is identified and fix is planned +- **Fix Implementation**: When coding the actual bug fix +- **Testing & Validation**: When testing the fix works correctly +- **Code Review**: When reviewing the fix implementation +- **Deployment**: When preparing the fix for deployment +- **Documentation**: When documenting the fix and lessons learned + +## Bundled Rules + +### **Implementation Standards** + +- **`development/software_development.mdc`** - Core development + principles, evidence requirements, and testing strategy +- **`development/type_safety_guide.mdc`** - Type-safe implementation + with proper error handling and type guards +- **`development/logging_migration.mdc`** - Proper logging + implementation and migration from console.* calls + +### **Code Quality & Review** + +- **`development/historical_comment_management.mdc`** - Code quality + standards and comment transformation rules +- **`development/historical_comment_patterns.mdc`** - Specific + patterns for transforming historical comments +- **`development/complexity_assessment.mdc`** - Complexity evaluation + for fix implementation + +### **Platform & Testing** + +- **`app/timesafari_development.mdc`** - TimeSafari-specific + development workflow and testing requirements +- **`app/timesafari_platforms.mdc`** - Platform-specific testing + and validation requirements +- **`architecture/build_validation.mdc`** - Build system validation + and testing procedures + +## Workflow Sequence + +### **Phase 1: Fix Implementation (Start Here)** + +1. **Development Standards** - Apply `software_development.mdc` for + core implementation principles +2. **Type Safety** - Use `type_safety_guide.mdc` for type-safe + implementation +3. **Logging Implementation** - Apply `logging_migration.mdc` for + proper logging + +### **Phase 2: Quality & Review** + +1. **Code Quality** - Use `historical_comment_management.mdc` for + code quality standards +2. **Complexity Assessment** - Apply `complexity_assessment.mdc` to + evaluate fix complexity +3. **Code Review** - Follow review standards from bundled rules + +### **Phase 3: Testing & Validation** + +1. **Platform Testing** - Use `timesafari_platforms.mdc` for + platform-specific testing +2. **Build Validation** - Apply `build_validation.mdc` for build + system compliance +3. **Final Validation** - Verify fix works across all platforms + +## Success Criteria + +- [ ] **Fix implemented** following development standards +- [ ] **Type safety maintained** with proper error handling +- [ ] **Logging properly implemented** with component context +- [ ] **Code quality standards met** with clean, maintainable code +- [ ] **Testing completed** across all target platforms +- [ ] **Build validation passed** with no build system issues +- [ ] **Code review completed** with all feedback addressed +- [ ] **Documentation updated** with fix details and lessons learned + +## Common Pitfalls + +- **Don't skip type safety** - leads to runtime errors +- **Don't ignore logging** - makes future debugging harder +- **Don't skip platform testing** - misses platform-specific issues +- **Don't ignore code quality** - creates technical debt +- **Don't skip build validation** - can break build system +- **Don't forget documentation** - loses fix context for future + +## Integration Points + +### **With Other Meta-Rules** + +- **Bug Diagnosis**: Investigation results drive fix implementation +- **Feature Implementation**: Fix patterns inform future development +- **Feature Planning**: Fix complexity informs future planning + +### **With Development Workflow** + +- Fix implementation follows development standards +- Testing strategy ensures fix quality +- Code review maintains code quality + +## Feedback & Improvement + +### **Sub-Rule Ratings (1-5 scale)** + +- **Development Standards**: ___/5 - Comments: _______________ +- **Type Safety**: ___/5 - Comments: _______________ +- **Logging Migration**: ___/5 - Comments: _______________ +- **Code Quality**: ___/5 - Comments: _______________ +- **Platform Testing**: ___/5 - Comments: _______________ + +### **Workflow Feedback** + +- **Implementation Clarity**: How clear was the implementation guidance? +- **Testing Coverage**: Were testing requirements sufficient or excessive? +- **Process Effectiveness**: How well did the workflow work for you? + +### **Sub-Rule Improvements** + +- **Clarity Issues**: Which rules were unclear or confusing? +- **Missing Examples**: What examples would make rules more useful? +- **Integration Problems**: Do any rules conflict or overlap? + +### **Overall Experience** + +- **Time Saved**: How much time did this meta-rule save you? +- **Quality Improvement**: Did following these rules improve your fix? +- **Recommendation**: Would you recommend this meta-rule to others? + +## Model Implementation Checklist + +### Before Bug Fixing + +- [ ] **Root Cause Understood**: Confirm root cause is clearly identified +- [ ] **Fix Strategy Planned**: Plan implementation approach and testing +- [ ] **Platform Impact Assessed**: Understand impact across all platforms +- [ ] **Testing Strategy Planned**: Plan testing approach for the fix + +### During Bug Fixing + +- [ ] **Rule Application**: Apply bundled rules in recommended sequence +- [ ] **Implementation**: Implement fix following development standards +- [ ] **Testing**: Test fix across all target platforms +- [ ] **Documentation**: Document implementation details and decisions + +### After Bug Fixing + +- [ ] **Validation**: Verify fix meets all success criteria +- [ ] **Code Review**: Complete code review with team +- [ ] **Deployment**: Deploy fix following deployment procedures +- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness + +--- + +**See also**: + +- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation workflow +- `.cursor/rules/meta_feature_implementation.mdc` for implementation patterns +- `.cursor/rules/meta_feature_planning.mdc` for planning future work + +**Status**: Active meta-rule for bug fixing +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, QA team, DevOps team diff --git a/.cursor/rules/meta_change_evaluation.mdc b/.cursor/rules/meta_change_evaluation.mdc new file mode 100644 index 0000000..dd4e1f7 --- /dev/null +++ b/.cursor/rules/meta_change_evaluation.mdc @@ -0,0 +1,383 @@ +# Meta-Rule: Change Evaluation and Breaking Change Detection + +**Author**: Matthew Raymer +**Date**: 2025-08-25 +**Status**: 🎯 **ACTIVE** - Manually activated change evaluation rule + +## Purpose + +This meta-rule provides a systematic approach to evaluate changes between +branches and detect potential breaking changes. It's designed to catch +problematic model behavior by analyzing the nature, scope, and impact of +code changes before they cause issues. + +## When to Use + +**Manual Activation Only** - This rule should be invoked when: + +- Reviewing changes before merging branches +- Investigating unexpected behavior after updates +- Validating that model-generated changes are safe +- Analyzing the impact of recent commits +- Debugging issues that may be caused by recent changes + +## Workflow State Enforcement + +**This meta-rule enforces current workflow mode constraints:** + +### **Current Workflow State** + +```json +{ + "workflowState": { + "currentMode": "diagnosis|fixing|planning|research|documentation", + "constraints": { + "mode": "read_only|implementation|design_only|investigation|writing_only", + "allowed": ["array", "of", "allowed", "actions"], + "forbidden": ["array", "of", "forbidden", "actions"] + } + } +} +``` + +### **Mode-Specific Enforcement** + +**Diagnosis Mode (read_only):** + +- ❌ **Forbidden**: File modification, code creation, build commands, git + commits +- ✅ **Allowed**: File reading, code analysis, investigation, documentation +- **Response**: Focus on analysis and documentation, not implementation + +**Fixing Mode (implementation):** + +- ✅ **Allowed**: File modification, code creation, build commands, testing, + git commits +- ❌ **Forbidden**: None (full implementation mode) +- **Response**: Proceed with implementation and testing + +**Planning Mode (design_only):** + +- ❌ **Forbidden**: Implementation, coding, building, deployment +- ✅ **Allowed**: Analysis, design, estimation, documentation, architecture +- **Response**: Focus on planning and design, not implementation + +**Research Mode (investigation):** + +- ❌ **Forbidden**: File modification, implementation, deployment +- ✅ **Allowed**: Investigation, analysis, research, documentation +- **Response**: Focus on investigation and analysis + +**Documentation Mode (writing_only):** + +- ❌ **Forbidden**: Implementation, coding, building, deployment +- ✅ **Allowed**: Writing, editing, formatting, structuring, reviewing +- **Response**: Focus on documentation creation and improvement + +## Change Evaluation Process + +### **Phase 1: Change Discovery and Analysis** + +1. **Branch Comparison Analysis** + + - Compare working branch with master/main branch + - Identify all changed files and their modification types + - Categorize changes by scope and impact + +2. **Change Pattern Recognition** + + - Identify common change patterns (refactoring, feature addition, bug + fixes) + - Detect unusual or suspicious change patterns + - Flag changes that deviate from established patterns + +3. **Dependency Impact Assessment** + + - Analyze changes to imports, exports, and interfaces + - Identify potential breaking changes to public APIs + - Assess impact on dependent components and services + +### **Phase 2: Breaking Change Detection** + +1. **API Contract Analysis** + + - Check for changes to function signatures, method names, class + interfaces + - Identify removed or renamed public methods/properties + - Detect changes to configuration options and constants + +2. **Data Structure Changes** + + - Analyze database schema modifications + - Check for changes to data models and interfaces + - Identify modifications to serialization/deserialization logic + +3. **Behavioral Changes** + + - Detect changes to business logic and algorithms + - Identify modifications to error handling and validation + - Check for changes to user experience and workflows + +### **Phase 3: Risk Assessment and Recommendations** + +1. **Risk Level Classification** + + - **LOW**: Cosmetic changes, documentation updates, minor refactoring + - **MEDIUM**: Internal API changes, configuration modifications, + performance improvements + - **HIGH**: Public API changes, breaking interface modifications, major + architectural changes + - **CRITICAL**: Database schema changes, authentication modifications, + security-related changes + +2. **Impact Analysis** + + - Identify affected user groups and use cases + - Assess potential for data loss or corruption + - Evaluate impact on system performance and reliability + +3. **Mitigation Strategies** + + - Recommend testing approaches for affected areas + - Suggest rollback strategies if needed + - Identify areas requiring additional validation + +## Implementation Guidelines + +### **Change Analysis Tools** + +1. **Git Diff Analysis** + + ```bash + # Compare working branch with master + git diff master..HEAD --name-only + git diff master..HEAD --stat + git log master..HEAD --oneline + ``` + +2. **File Change Categorization** + + - **Core Files**: Application entry points, main services, critical + utilities + - **Interface Files**: Public APIs, component interfaces, data models + - **Configuration Files**: Environment settings, build configurations, + deployment scripts + - **Test Files**: Unit tests, integration tests, test utilities + +3. **Change Impact Mapping** + + - Map changed files to affected functionality + - Identify cross-dependencies and ripple effects + - Document potential side effects and unintended consequences + +### **Breaking Change Detection Patterns** + +1. **Function Signature Changes** + + ```typescript + // BEFORE + function processData(data: string, options?: Options): Result + + // AFTER - BREAKING CHANGE + function processData(data: string, options: Required): Result + ``` + +2. **Interface Modifications** + + ```typescript + // BEFORE + interface UserProfile { + name: string; + email: string; + } + + // AFTER - BREAKING CHANGE + interface UserProfile { + name: string; + email: string; + phone: string; // Required new field + } + ``` + +3. **Configuration Changes** + + ```typescript + // BEFORE + const config = { + apiUrl: 'https://api.example.com', + timeout: 5000 + }; + + // AFTER - BREAKING CHANGE + const config = { + apiUrl: 'https://api.example.com', + timeout: 5000, + retries: 3 // New required configuration + }; + ``` + +## Output Format + +### **Change Evaluation Report** + +```markdown +# Change Evaluation Report + +## Executive Summary + +- **Risk Level**: [LOW|MEDIUM|HIGH|CRITICAL] +- **Overall Assessment**: [SAFE|CAUTION|DANGEROUS|CRITICAL] +- **Recommendation**: [PROCEED|REVIEW|HALT|IMMEDIATE_ROLLBACK] + +## Change Analysis + +### Files Modified + +- **Total Changes**: [X] files +- **Core Files**: [X] files +- **Interface Files**: [X] files +- **Configuration Files**: [X] files +- **Test Files**: [X] files + +### Change Categories + +- **Refactoring**: [X] changes +- **Feature Addition**: [X] changes +- **Bug Fixes**: [X] changes +- **Configuration**: [X] changes +- **Documentation**: [X] changes + +## Breaking Change Detection + +### API Contract Changes + +- **Function Signatures**: [X] modified +- **Interface Definitions**: [X] modified +- **Public Methods**: [X] added/removed/modified + +### Data Structure Changes + +- **Database Schema**: [X] modifications +- **Data Models**: [X] changes +- **Serialization**: [X] changes + +### Behavioral Changes + +- **Business Logic**: [X] modifications +- **Error Handling**: [X] changes +- **User Experience**: [X] changes + +## Risk Assessment + +### Impact Analysis + +- **User Groups Affected**: [Description] +- **Use Cases Impacted**: [Description] +- **Performance Impact**: [Description] +- **Reliability Impact**: [Description] + +### Dependencies + +- **Internal Dependencies**: [List] +- **External Dependencies**: [List] +- **Configuration Dependencies**: [List] + +## Recommendations + +### Testing Requirements + +- [ ] Unit tests for modified components +- [ ] Integration tests for affected workflows +- [ ] Performance tests for changed algorithms +- [ ] User acceptance tests for UI changes + +### Validation Steps + +- [ ] Code review by domain experts +- [ ] API compatibility testing +- [ ] Database migration testing +- [ ] End-to-end workflow testing + +### Rollback Strategy + +- **Rollback Complexity**: [LOW|MEDIUM|HIGH] +- **Rollback Time**: [Estimated time] +- **Data Preservation**: [Strategy description] + +## Conclusion + +[Summary of findings and final recommendation] +``` + +## Usage Examples + +### **Example 1: Safe Refactoring** + +```bash +@meta_change_evaluation.mdc analyze changes between feature-branch and master +``` + +### **Example 2: Breaking Change Investigation** + +```bash +@meta_change_evaluation.mdc evaluate potential breaking changes in recent commits +``` + +### **Example 3: Pre-Merge Validation** + +```bash +@meta_change_evaluation.mdc validate changes before merging feature-branch to master +``` + +## Success Criteria + +- [ ] **Change Discovery**: All modified files are identified and categorized +- [ ] **Pattern Recognition**: Unusual change patterns are detected and flagged +- [ ] **Breaking Change Detection**: All potential breaking changes are identified +- [ ] **Risk Assessment**: Accurate risk levels are assigned with justification +- [ ] **Recommendations**: Actionable recommendations are provided +- [ ] **Documentation**: Complete change evaluation report is generated + +## Common Pitfalls + +- **Missing Dependencies**: Failing to identify all affected components +- **Underestimating Impact**: Not considering ripple effects of changes +- **Incomplete Testing**: Missing critical test scenarios for changes +- **Configuration Blindness**: Overlooking configuration file changes +- **Interface Assumptions**: Assuming internal changes won't affect external + users + +## Integration with Other Meta-Rules + +### **With Bug Diagnosis** + +- Use change evaluation to identify recent changes that may have caused + bugs +- Correlate change patterns with reported issues + +### **With Feature Planning** + +- Evaluate the impact of planned changes before implementation +- Identify potential breaking changes early in the planning process + +### **With Bug Fixing** + +- Validate that fixes don't introduce new breaking changes +- Ensure fixes maintain backward compatibility + +--- + +**See also**: + +- `.cursor/rules/meta_core_always_on.mdc` for core always-on rules +- `.cursor/rules/meta_feature_planning.mdc` for feature development + workflows +- `.cursor/rules/meta_bug_diagnosis.mdc` for bug investigation workflows +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation workflows + +**Status**: Active change evaluation meta-rule +**Priority**: High (applies to all change evaluation tasks) +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, Quality Assurance team, Release +Management team diff --git a/.cursor/rules/meta_core_always_on.mdc b/.cursor/rules/meta_core_always_on.mdc new file mode 100644 index 0000000..ac9ee1d --- /dev/null +++ b/.cursor/rules/meta_core_always_on.mdc @@ -0,0 +1,311 @@ +--- +alwaysApply: true +--- + +# Meta-Rule: Core Always-On Rules + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Core rules for every prompt + +## Purpose + +This meta-rule bundles the core rules that should be applied to **every single +prompt** because they define fundamental behaviors, principles, and context +that are essential for all AI interactions. + +## Workflow Constraints + +**This meta-rule enforces ALWAYS-ON MODE for all bundled sub-rules:** + +```json +{ + "workflowMode": "always_on", + "constraints": { + "mode": "foundation", + "alwaysApplied": true, + "required": "applied_to_every_prompt" + } +} +``` + +**All bundled sub-rules automatically inherit these constraints.** + +## Workflow State Enforcement + +**This meta-rule enforces current workflow mode constraints for all interactions:** + +### **Current Workflow State** +```json +{ + "workflowState": { + "currentMode": "diagnosis|fixing|planning|research|documentation", + "constraints": { + "mode": "read_only|implementation|design_only|investigation|writing_only", + "allowed": ["array", "of", "allowed", "actions"], + "forbidden": ["array", "of", "forbidden", "actions"] + } + } +} +``` + +### **Constraint Enforcement Rules** + +**Before responding to any user request, enforce current mode constraints:** + +1. **Read current workflow state** from `.cursor/rules/.workflow_state.json` +2. **Identify current mode** and its constraints +3. **Validate user request** against current mode constraints +4. **Enforce constraints** before generating response +5. **Guide model behavior** based on current mode + +### **Mode-Specific Enforcement** + +**Diagnosis Mode (read_only):** +- ❌ **Forbidden**: File modification, code creation, build commands, git commits +- ✅ **Allowed**: File reading, code analysis, investigation, documentation +- **Response**: Guide user toward investigation and analysis, not implementation + +**Fixing Mode (implementation):** +- ✅ **Allowed**: File modification, code creation, build commands, testing, git commits +- ❌ **Forbidden**: None (full implementation mode) +- **Response**: Proceed with implementation and testing + +**Planning Mode (design_only):** +- ❌ **Forbidden**: Implementation, coding, building, deployment +- ✅ **Allowed**: Analysis, design, estimation, documentation, architecture +- **Response**: Focus on planning and design, not implementation + +**Research Mode (investigation):** +- ❌ **Forbidden**: File modification, implementation, deployment +- ✅ **Allowed**: Investigation, analysis, research, documentation +- **Response**: Focus on investigation and analysis + +**Documentation Mode (writing_only):** +- ❌ **Forbidden**: Implementation, coding, building, deployment +- ✅ **Allowed**: Writing, editing, formatting, structuring, reviewing +- **Response**: Focus on documentation creation and improvement + +### **Constraint Violation Response** + +**If user request violates current mode constraints:** + +``` +❌ **WORKFLOW CONSTRAINT VIOLATION** + +**Current Mode**: [MODE_NAME] +**Requested Action**: [ACTION] +**Constraint Violation**: [DESCRIPTION] + +**What You Can Do Instead**: +- [LIST OF ALLOWED ALTERNATIVES] + +**To Enable This Action**: Invoke @meta_[appropriate_mode].mdc +``` + +### **Mode Transition Guidance** + +**When user needs to change modes, provide clear guidance:** + +``` +🔄 **MODE TRANSITION REQUIRED** + +**Current Mode**: [CURRENT_MODE] +**Required Mode**: [REQUIRED_MODE] +**Action**: Invoke @meta_[required_mode].mdc + +**This will enable**: [DESCRIPTION OF NEW CAPABILITIES] +``` + +## When to Use + +**ALWAYS** - These rules apply to every single prompt, regardless of the task +or context. They form the foundation for all AI assistant behavior. + +## Bundled Rules + +### **Core Human Competence Principles** + +- **`core/base_context.mdc`** - Human competence first principles, interaction + guidelines, and output contract requirements +- **`core/less_complex.mdc`** - Minimalist solution principle and complexity + guidelines + +### **Time & Context Standards** + +- **`development/time.mdc`** - Time handling principles and UTC standards +- **`development/time_examples.mdc`** - Practical time implementation examples +- **`development/time_implementation.mdc`** - Detailed time implementation + guidelines + +### **Version Control & Process** + +- **`workflow/version_control.mdc`** - Version control principles and commit + guidelines +- **`workflow/commit_messages.mdc`** - Commit message format and conventions + +### **Application Context** + +- **`app/timesafari.mdc`** - Core TimeSafari application context and + development principles +- **`app/timesafari_development.mdc`** - TimeSafari-specific development + workflow and quality standards + +## Why These Rules Are Always-On + +### **Base Context** + +- **Human Competence First**: Every interaction must increase human competence +- **Output Contract**: All responses must follow the required structure +- **Competence Hooks**: Learning and collaboration must be built into every response + +### **Time Standards** + +- **UTC Consistency**: All timestamps must use UTC for system operations +- **Evidence Collection**: Time context is essential for debugging and investigation +- **Cross-Platform**: Time handling affects all platforms and features + +### **Version Control** + +- **Commit Standards**: Every code change must follow commit message conventions +- **Process Consistency**: Version control affects all development work +- **Team Collaboration**: Commit standards enable effective team communication + +### **Application Context** + +- **Platform Awareness**: Every task must consider web/mobile/desktop platforms +- **Architecture Principles**: All work must follow TimeSafari patterns +- **Development Standards**: Quality and testing requirements apply to all work + +## Application Priority + +### **Primary (Apply First)** + +1. **Base Context** - Human competence and output contract +2. **Time Standards** - UTC and timestamp requirements +3. **Application Context** - TimeSafari principles and platforms + +### **Secondary (Apply as Needed)** + +1. **Version Control** - When making code changes +2. **Complexity Guidelines** - When evaluating solution approaches + +## Integration with Other Meta-Rules + +### **Feature Planning** + +- Base context ensures human competence focus +- Time standards inform planning and estimation +- Application context drives platform considerations + +### **Bug Diagnosis** + +- Base context ensures systematic investigation +- Time standards enable proper evidence collection +- Application context provides system understanding + +### **Bug Fixing** + +- Base context ensures quality implementation +- Time standards maintain logging consistency +- Application context guides testing strategy + +### **Feature Implementation** + +- Base context ensures proper development approach +- Time standards maintain system consistency +- Application context drives architecture decisions + +## Success Criteria + +- [ ] **Base context applied** to every single prompt +- [ ] **Time standards followed** for all timestamps and logging +- [ ] **Version control standards** applied to all code changes +- [ ] **Application context considered** for all platform work +- [ ] **Human competence focus** maintained in all interactions +- [ ] **Output contract structure** followed in all responses + +## Common Pitfalls + +- **Don't skip base context** - loses human competence focus +- **Don't ignore time standards** - creates inconsistent timestamps +- **Don't forget application context** - misses platform considerations +- **Don't skip version control** - creates inconsistent commit history +- **Don't lose competence focus** - reduces learning value + +## Feedback & Improvement + +### **Rule Effectiveness Ratings (1-5 scale)** + +- **Base Context**: ___/5 - Comments: _______________ +- **Time Standards**: ___/5 - Comments: _______________ +- **Version Control**: ___/5 - Comments: _______________ +- **Application Context**: ___/5 - Comments: _______________ + +### **Always-On Effectiveness** + +- **Consistency**: Are these rules applied consistently across all prompts? +- **Value**: Do these rules add value to every interaction? +- **Overhead**: Are these rules too burdensome for simple tasks? + +### **Integration Feedback** + +- **With Other Meta-Rules**: How well do these integrate with workflow rules? +- **Context Switching**: Do these rules help or hinder context switching? +- **Learning Curve**: Are these rules easy for new users to understand? + +### **Overall Experience** + +- **Quality Improvement**: Do these rules improve response quality? +- **Efficiency**: Do these rules make interactions more efficient? +- **Recommendation**: Would you recommend keeping these always-on? + +## Model Implementation Checklist + +### Before Every Prompt + +- [ ] **Base Context**: Ensure human competence principles are active +- [ ] **Time Standards**: Verify UTC and timestamp requirements are clear +- [ ] **Application Context**: Confirm TimeSafari context is loaded +- [ ] **Version Control**: Prepare commit standards if code changes are needed +- [ ] **Workflow State**: Read current mode constraints from state file +- [ ] **Constraint Validation**: Validate user request against current mode + +### During Response Creation + +- [ ] **Output Contract**: Follow required response structure +- [ ] **Competence Hooks**: Include learning and collaboration elements +- [ ] **Time Consistency**: Apply UTC standards for all time references +- [ ] **Platform Awareness**: Consider all target platforms +- [ ] **Mode Enforcement**: Apply current mode constraints to response +- [ ] **Constraint Violations**: Block forbidden actions and guide alternatives + +### After Response Creation + +- [ ] **Validation**: Verify all always-on rules were applied +- [ ] **Quality Check**: Ensure response meets competence standards +- [ ] **Context Review**: Confirm application context was properly considered +- [ ] **Feedback Collection**: Note any issues with always-on application +- [ ] **Mode Compliance**: Verify response stayed within current mode constraints +- [ ] **Transition Guidance**: Provide clear guidance for mode changes if needed + +--- + +**See also**: + +- `.cursor/rules/meta_feature_planning.mdc` for workflow-specific rules +- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation workflows +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation +- `.cursor/rules/meta_feature_implementation.mdc` for feature development + +**Status**: Active core always-on meta-rule +**Priority**: Critical (applies to every prompt) +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: All AI interactions, Development team + +**Dependencies**: All bundled sub-rules +**Stakeholders**: All AI interactions, Development team + +**Dependencies**: All bundled sub-rules +**Stakeholders**: All AI interactions, Development team diff --git a/.cursor/rules/meta_documentation.mdc b/.cursor/rules/meta_documentation.mdc new file mode 100644 index 0000000..56c4400 --- /dev/null +++ b/.cursor/rules/meta_documentation.mdc @@ -0,0 +1,275 @@ +# Meta-Rule: Documentation Writing & Education + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Documentation writing and education workflow + +## Purpose + +This meta-rule bundles documentation-related rules to create comprehensive, +educational documentation that increases human competence rather than just +providing technical descriptions. + +## Workflow Constraints + +**This meta-rule enforces DOCUMENTATION MODE for all bundled sub-rules:** + +```json +{ + "workflowMode": "documentation", + "constraints": { + "mode": "writing_only", + "allowed": ["write", "edit", "format", "structure", "review"], + "forbidden": ["implement", "code", "build", "deploy"] + } +} +``` + +**All bundled sub-rules automatically inherit these constraints.** + +## Workflow State Update + +**When this meta-rule is invoked, update the workflow state file:** + +```json +{ + "currentMode": "documentation", + "lastInvoked": "meta_documentation.mdc", + "timestamp": "2025-01-27T15:30:00Z", + "constraints": { + "mode": "writing_only", + "allowed": ["write", "edit", "format", "structure", "review"], + "forbidden": ["implement", "code", "build", "deploy"] + } +} +``` + +**State File Location**: `.cursor/rules/.workflow_state.json` + +**This enables the core always-on rule to enforce documentation mode constraints.** + +## When to Use + +**Use this meta-rule when**: +- Writing new documentation +- Updating existing documentation +- Creating technical guides +- Writing migration documentation +- Creating architectural documentation +- Writing user guides or tutorials + +## Bundled Rules + +### **Core Documentation Standards** + +- **`docs/markdown_core.mdc`** - Core markdown formatting and automation +- **`docs/markdown_templates.mdc`** - Document templates and structure +- **`docs/markdown_workflow.mdc`** - Documentation validation workflows + +### **Documentation Principles** + +- **`core/base_context.mdc`** - Human competence first principles +- **`core/less_complex.mdc`** - Minimalist solution guidelines +- **`development/software_development.mdc`** - Development documentation standards + +### **Context-Specific Rules** + +- **`app/timesafari.mdc`** - TimeSafari application context +- **`app/timesafari_development.mdc`** - Development documentation patterns +- **`architecture/architectural_patterns.mdc`** - Architecture documentation + +## Core Documentation Philosophy + +### **Education Over Technical Description** + +**Primary Goal**: Increase human competence and understanding +**Secondary Goal**: Provide accurate technical information +**Approach**: Explain the "why" before the "how" + +### **Human Competence Principles** + +1. **Context First**: Explain the problem before the solution +2. **Learning Path**: Structure content for progressive understanding +3. **Real Examples**: Use concrete, relatable examples +4. **Common Pitfalls**: Warn about typical mistakes and misconceptions +5. **Decision Context**: Explain why certain choices were made + +### **Documentation Hierarchy** + +1. **Conceptual Understanding** - What is this and why does it matter? +2. **Context and Motivation** - When and why would you use this? +3. **Technical Implementation** - How do you implement it? +4. **Examples and Patterns** - What does it look like in practice? +5. **Troubleshooting** - What can go wrong and how to fix it? + +## Implementation Guidelines + +### **Document Structure** + +**Mandatory Sections**: +- **Overview**: Clear purpose and scope with educational context +- **Why This Matters**: Business value and user benefit explanation +- **Core Concepts**: Fundamental understanding before implementation +- **Implementation**: Step-by-step technical guidance +- **Examples**: Real-world usage patterns +- **Common Issues**: Troubleshooting and prevention +- **Next Steps**: Where to go from here + +**Optional Sections**: +- **Background**: Historical context and evolution +- **Alternatives**: Other approaches and trade-offs +- **Advanced Topics**: Deep dive into complex scenarios +- **References**: Additional learning resources + +### **Writing Style** + +**Educational Approach**: +- **Conversational tone**: Write as if explaining to a colleague +- **Progressive disclosure**: Start simple, add complexity gradually +- **Active voice**: "You can do this" not "This can be done" +- **Question format**: "What happens when..." to engage thinking +- **Analogies**: Use familiar concepts to explain complex ideas + +**Technical Accuracy**: +- **Precise language**: Use exact technical terms consistently +- **Code examples**: Working, tested code snippets +- **Version information**: Specify applicable versions and platforms +- **Limitations**: Clearly state what the solution doesn't do + +### **Content Quality Standards** + +**Educational Value**: +- [ ] **Concept clarity**: Reader understands the fundamental idea +- [ ] **Context relevance**: Reader knows when to apply the knowledge +- [ ] **Practical application**: Reader can implement the solution +- [ ] **Problem prevention**: Reader avoids common mistakes +- [ ] **Next steps**: Reader knows where to continue learning + +**Technical Accuracy**: +- [ ] **Fact verification**: All technical details are correct +- [ ] **Code validation**: Examples compile and run correctly +- [ ] **Version compatibility**: Platform and version requirements clear +- [ ] **Security consideration**: Security implications addressed +- [ ] **Performance notes**: Performance characteristics documented + +## Document Types and Templates + +### **Technical Guides** + +**Focus**: Implementation and technical details +**Structure**: Problem → Solution → Implementation → Examples +**Education**: Explain the "why" behind technical choices + +### **Migration Documentation** + +**Focus**: Process and workflow guidance +**Structure**: Context → Preparation → Steps → Validation → Troubleshooting +**Education**: Help users understand migration benefits and risks + +### **Architecture Documentation** + +**Focus**: System design and decision rationale +**Structure**: Problem → Constraints → Alternatives → Decision → Implementation +**Education**: Explain design trade-offs and decision factors + +### **User Guides** + +**Focus**: Task completion and user empowerment +**Structure**: Goal → Prerequisites → Steps → Verification → Next Steps +**Education**: Help users understand the system's capabilities + +## Quality Assurance + +### **Review Checklist** + +**Educational Quality**: +- [ ] **Clear learning objective**: What will the reader learn? +- [ ] **Appropriate complexity**: Matches target audience knowledge +- [ ] **Progressive disclosure**: Information builds logically +- [ ] **Practical examples**: Real-world scenarios and use cases +- [ ] **Common questions**: Anticipates and answers reader questions + +**Technical Quality**: +- [ ] **Accuracy**: All technical details verified +- [ ] **Completeness**: Covers all necessary information +- [ ] **Consistency**: Terminology and formatting consistent +- [ ] **Currency**: Information is up-to-date +- [ ] **Accessibility**: Clear for target audience + +### **Validation Workflows** + +1. **Content Review**: Subject matter expert review +2. **Educational Review**: Learning effectiveness assessment +3. **Technical Review**: Accuracy and completeness validation +4. **User Testing**: Real user comprehension testing +5. **Continuous Improvement**: Regular updates based on feedback + +## Success Metrics + +### **Educational Effectiveness** + +- **Comprehension**: Users understand the concepts +- **Application**: Users can implement the solutions +- **Confidence**: Users feel capable and empowered +- **Efficiency**: Users complete tasks faster +- **Satisfaction**: Users find documentation helpful + +### **Technical Quality** + +- **Accuracy**: Zero technical errors +- **Completeness**: All necessary information included +- **Consistency**: Uniform style and format +- **Maintainability**: Easy to update and extend +- **Accessibility**: Clear for target audience + +## Common Pitfalls + +### **Educational Mistakes** + +- **Assumption overload**: Assuming too much prior knowledge +- **Information dump**: Overwhelming with details +- **Context missing**: Not explaining why something matters +- **Example poverty**: Insufficient practical examples +- **Feedback missing**: No way to verify understanding + +### **Technical Mistakes** + +- **Outdated information**: Not keeping content current +- **Incomplete coverage**: Missing important details +- **Inconsistent terminology**: Using different terms for same concepts +- **Poor examples**: Non-working or confusing code +- **Missing validation**: No way to verify correctness + +## Feedback and Improvement + +### **Continuous Learning** + +- **User feedback**: Collect and analyze user comments +- **Usage metrics**: Track document usage and effectiveness +- **Review cycles**: Regular content review and updates +- **Community input**: Engage users in documentation improvement +- **Best practices**: Stay current with documentation standards + +### **Quality Metrics** + +- **Readability scores**: Measure content clarity +- **User satisfaction**: Survey-based quality assessment +- **Task completion**: Success rate of documented procedures +- **Support reduction**: Decrease in help requests +- **Knowledge retention**: Long-term user understanding + +--- + +**See also**: + +- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards +- `.cursor/rules/docs/markdown_templates.mdc` for document templates +- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows +- `.cursor/rules/docs/meta_rule_usage_guide.md` for how to use meta-rules +- `.cursor/rules/core/base_context.mdc` for human competence principles + +**Status**: Active documentation meta-rule +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Documentation team, Development team, Users diff --git a/.cursor/rules/meta_feature_implementation.mdc b/.cursor/rules/meta_feature_implementation.mdc new file mode 100644 index 0000000..ff16596 --- /dev/null +++ b/.cursor/rules/meta_feature_implementation.mdc @@ -0,0 +1,226 @@ +# Meta-Rule: Feature Implementation + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Feature implementation workflow bundling + +## Purpose + +This meta-rule bundles all the rules needed for building features with +proper architecture and cross-platform support. Use this when implementing +planned features or refactoring existing code. + +## Workflow Constraints + +**This meta-rule enforces IMPLEMENTATION MODE for all bundled sub-rules:** + +```json +{ + "workflowMode": "implementation", + "constraints": { + "mode": "development", + "allowed": ["code", "build", "test", "refactor", "deploy"], + "required": "planning_complete_before_implementation" + } +} +``` + +**All bundled sub-rules automatically inherit these constraints.** + +## Workflow State Update + +**When this meta-rule is invoked, update the workflow state file:** + +```json +{ + "currentMode": "implementation", + "lastInvoked": "meta_feature_implementation.mdc", + "timestamp": "2025-01-27T15:30:00Z", + "constraints": { + "mode": "development", + "allowed": ["code", "build", "test", "refactor", "deploy"], + "forbidden": [], + "required": "planning_complete_before_implementation" + } +} +``` + +**State File Location**: `.cursor/rules/.workflow_state.json` + +**This enables the core always-on rule to enforce implementation mode constraints.** + +## When to Use + +- **Feature Development**: Building new features from planning +- **Code Refactoring**: Restructuring existing code for better architecture +- **Platform Expansion**: Adding features to new platforms +- **Service Implementation**: Building new services or components +- **Integration Work**: Connecting features with existing systems +- **Performance Optimization**: Improving feature performance + +## Bundled Rules + +### **Development Foundation** + +- **`app/timesafari_development.mdc`** - TimeSafari-specific + development workflow and quality standards +- **`development/software_development.mdc`** - Core development + principles and evidence requirements +- **`development/type_safety_guide.mdc`** - Type-safe implementation + with proper error handling + +### **Architecture & Patterns** + +- **`app/architectural_patterns.mdc`** - Design patterns and + architectural examples for features +- **`app/architectural_examples.mdc`** - Implementation examples + and testing strategies +- **`app/architectural_implementation.mdc`** - Implementation + guidelines and best practices + +### **Platform & Services** + +- **`app/timesafari_platforms.mdc`** - Platform abstraction + patterns and platform-specific requirements +- **`development/asset_configuration.mdc`** - Asset management + and build integration +- **`development/logging_standards.mdc`** - Proper logging + implementation standards + +### **Quality & Validation** + +- **`architecture/build_validation.mdc`** - Build system + validation and testing procedures +- **`architecture/build_testing.mdc`** - Testing requirements + and feedback collection +- **`development/complexity_assessment.mdc`** - Complexity + evaluation for implementation + +## Workflow Sequence + +### **Phase 1: Implementation Foundation (Start Here)** + +1. **Development Workflow** - Use `timesafari_development.mdc` for + development standards and workflow +2. **Type Safety** - Apply `type_safety_guide.mdc` for type-safe + implementation +3. **Architecture Patterns** - Use `architectural_patterns.mdc` for + design patterns + +### **Phase 2: Feature Development** + +1. **Platform Services** - Apply `timesafari_platforms.mdc` for + platform abstraction +2. **Implementation Examples** - Use `architectural_examples.mdc` + for implementation guidance +3. **Asset Configuration** - Apply `asset_configuration.mdc` for + asset management + +### **Phase 3: Quality & Testing** + +1. **Logging Implementation** - Use `logging_standards.mdc` for + proper logging +2. **Build Validation** - Apply `build_validation.mdc` for build + system compliance +3. **Testing & Feedback** - Use `build_testing.mdc` for testing + requirements + +## Success Criteria + +- [ ] **Feature implemented** following development standards +- [ ] **Type safety maintained** with proper error handling +- [ ] **Architecture patterns applied** consistently +- [ ] **Platform abstraction implemented** correctly +- [ ] **Logging properly implemented** with component context +- [ ] **Assets configured** and integrated with build system +- [ ] **Build validation passed** with no build system issues +- [ ] **Testing completed** across all target platforms +- [ ] **Code review completed** with all feedback addressed + +## Common Pitfalls + +- **Don't skip architecture patterns** - leads to inconsistent design +- **Don't ignore platform abstraction** - creates platform-specific code +- **Don't skip type safety** - leads to runtime errors +- **Don't ignore logging** - makes future debugging harder +- **Don't skip build validation** - can break build system +- **Don't forget asset configuration** - leads to missing assets + +## Integration Points + +### **With Other Meta-Rules** + +- **Feature Planning**: Planning outputs drive implementation approach +- **Bug Fixing**: Implementation patterns inform fix strategies +- **Bug Diagnosis**: Implementation insights help with investigation + +### **With Development Workflow** + +- Implementation follows development standards +- Architecture decisions drive implementation approach +- Platform requirements inform testing strategy + +## Feedback & Improvement + +### **Sub-Rule Ratings (1-5 scale)** + +- **Development Workflow**: ___/5 - Comments: _______________ +- **Type Safety**: ___/5 - Comments: _______________ +- **Architecture Patterns**: ___/5 - Comments: _______________ +- **Platform Services**: ___/5 - Comments: _______________ +- **Build Validation**: ___/5 - Comments: _______________ + +### **Workflow Feedback** + +- **Implementation Clarity**: How clear was the implementation guidance? +- **Pattern Effectiveness**: How well did architecture patterns work? +- **Platform Coverage**: How well did platform guidance cover your needs? + +### **Sub-Rule Improvements** + +- **Clarity Issues**: Which rules were unclear or confusing? +- **Missing Examples**: What examples would make rules more useful? +- **Integration Problems**: Do any rules conflict or overlap? + +### **Overall Experience** + +- **Time Saved**: How much time did this meta-rule save you? +- **Quality Improvement**: Did following these rules improve your implementation? +- **Recommendation**: Would you recommend this meta-rule to others? + +## Model Implementation Checklist + +### Before Feature Implementation + +- [ ] **Planning Review**: Review feature planning and requirements +- [ ] **Architecture Planning**: Plan architecture and design patterns +- [ ] **Platform Analysis**: Understand platform-specific requirements +- [ ] **Testing Strategy**: Plan testing approach for the feature + +### During Feature Implementation + +- [ ] **Rule Application**: Apply bundled rules in recommended sequence +- [ ] **Implementation**: Implement feature following development standards +- [ ] **Testing**: Test feature across all target platforms +- [ ] **Documentation**: Document implementation details and decisions + +### After Feature Implementation + +- [ ] **Validation**: Verify feature meets all success criteria +- [ ] **Code Review**: Complete code review with team +- [ ] **Testing**: Complete comprehensive testing across platforms +- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness + +--- + +**See also**: + +- `.cursor/rules/meta_feature_planning.mdc` for planning workflow +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation patterns +- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation insights + +**Status**: Active meta-rule for feature implementation +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, Architecture team, QA team diff --git a/.cursor/rules/meta_feature_planning.mdc b/.cursor/rules/meta_feature_planning.mdc new file mode 100644 index 0000000..f76b09b --- /dev/null +++ b/.cursor/rules/meta_feature_planning.mdc @@ -0,0 +1,203 @@ +# Meta-Rule: Feature Planning + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Feature planning workflow bundling + +## Purpose + +This meta-rule bundles all the rules needed for comprehensive feature planning +across all platforms. Use this when starting any new feature development, +planning sprints, or estimating work effort. + +## Workflow Constraints + +**This meta-rule enforces PLANNING MODE for all bundled sub-rules:** + +```json +{ + "workflowMode": "planning", + "constraints": { + "mode": "design_only", + "allowed": ["analyze", "plan", "design", "estimate", "document"], + "forbidden": ["implement", "code", "build", "test", "deploy"] + } +} +``` + +**All bundled sub-rules automatically inherit these constraints.** + +## Workflow State Update + +**When this meta-rule is invoked, update the workflow state file:** + +```json +{ + "currentMode": "planning", + "lastInvoked": "meta_feature_planning.mdc", + "timestamp": "2025-01-27T15:30:00Z", + "constraints": { + "mode": "design_only", + "allowed": ["analyze", "plan", "design", "estimate", "document"], + "forbidden": ["implement", "code", "build", "test", "deploy"] + } +} +``` + +**State File Location**: `.cursor/rules/.workflow_state.json` + +**This enables the core always-on rule to enforce planning mode constraints.** + +## When to Use + +- **New Feature Development**: Planning features from concept to implementation +- **Sprint Planning**: Estimating effort and breaking down work +- **Architecture Decisions**: Planning major architectural changes +- **Platform Expansion**: Adding features to new platforms +- **Refactoring Planning**: Planning significant code restructuring + +## Bundled Rules + +### **Core Planning Foundation** + +- **`development/planning_examples.mdc`** - Planning templates, examples, and + best practices for structured planning +- **`development/realistic_time_estimation.mdc`** - Time estimation framework + with complexity-based phases and milestones +- **`development/complexity_assessment.mdc`** - Technical and business + complexity evaluation with risk assessment + +### **Platform & Architecture** + +- **`app/timesafari_platforms.mdc`** - Platform-specific requirements, + constraints, and capabilities across web/mobile/desktop +- **`app/architectural_decision_record.mdc`** - ADR process for documenting + major architectural decisions and trade-offs + +### **Development Context** + +- **`app/timesafari.mdc`** - Core application context, principles, and + development focus areas +- **`app/timesafari_development.mdc`** - TimeSafari-specific development + workflow and quality standards + +## Workflow Sequence + +### **Phase 1: Foundation (Start Here)** + +1. **Complexity Assessment** - Use `complexity_assessment.mdc` to evaluate + technical and business complexity +2. **Time Estimation** - Apply `realistic_time_estimation.mdc` framework + based on complexity results +3. **Core Planning** - Use `planning_examples.mdc` for structured planning + approach + +### **Phase 2: Platform & Architecture** + +1. **Platform Analysis** - Review `timesafari_platforms.mdc` for + platform-specific requirements +2. **Architecture Planning** - Use `architectural_decision_record.mdc` if + major architectural changes are needed + +### **Phase 3: Implementation Planning** + +1. **Development Workflow** - Reference `timesafari_development.mdc` for + development standards and testing strategy +2. **Final Planning** - Consolidate all inputs into comprehensive plan + +## Success Criteria + +- [ ] **Complexity assessed** and documented with risk factors +- [ ] **Time estimate created** with clear phases and milestones +- [ ] **Platform requirements identified** for all target platforms +- [ ] **Architecture decisions documented** (if major changes needed) +- [ ] **Testing strategy planned** with platform-specific considerations +- [ ] **Dependencies mapped** between tasks and phases +- [ ] **Stakeholder input gathered** and incorporated + +## Common Pitfalls + +- **Don't skip complexity assessment** - leads to unrealistic estimates +- **Don't estimate without platform analysis** - misses platform-specific work +- **Don't plan without stakeholder input** - creates misaligned expectations +- **Don't ignore testing strategy** - leads to incomplete planning +- **Don't skip architecture decisions** - creates technical debt + +## Integration Points + +### **With Other Meta-Rules** + +- **Bug Diagnosis**: Use complexity assessment for bug investigation planning +- **Feature Implementation**: This planning feeds directly into implementation +- **Code Review**: Planning standards inform review requirements + +### **With Development Workflow** + +- Planning outputs become inputs for sprint planning +- Complexity assessment informs testing strategy +- Platform requirements drive architecture decisions + +## Feedback & Improvement + +### **Sub-Rule Ratings (1-5 scale)** + +- **Complexity Assessment**: ___/5 - Comments: _______________ +- **Time Estimation**: ___/5 - Comments: _______________ +- **Planning Examples**: ___/5 - Comments: _______________ +- **Platform Analysis**: ___/5 - Comments: _______________ +- **Architecture Decisions**: ___/5 - Comments: _______________ + +### **Workflow Feedback** + +- **Sequence Effectiveness**: Did the recommended order work for you? +- **Missing Guidance**: What additional information would have helped? +- **Process Gaps**: Where did the workflow break down? + +### **Sub-Rule Improvements** + +- **Clarity Issues**: Which rules were unclear or confusing? +- **Missing Examples**: What examples would make rules more useful? +- **Integration Problems**: Do any rules conflict or overlap? + +### **Overall Experience** + +- **Time Saved**: How much time did this meta-rule save you? +- **Quality Improvement**: Did following these rules improve your planning? +- **Recommendation**: Would you recommend this meta-rule to others? + +## Model Implementation Checklist + +### Before Feature Planning + +- [ ] **Scope Definition**: Clearly define the feature scope and boundaries +- [ ] **Stakeholder Identification**: Identify all stakeholders and decision makers +- [ ] **Platform Requirements**: Understand target platforms and constraints +- [ ] **Complexity Assessment**: Plan complexity evaluation approach + +### During Feature Planning + +- [ ] **Rule Application**: Apply bundled rules in recommended sequence +- [ ] **Documentation**: Document all planning decisions and rationale +- [ ] **Stakeholder Input**: Gather and incorporate stakeholder feedback +- [ ] **Validation**: Validate planning against success criteria + +### After Feature Planning + +- [ ] **Plan Review**: Review plan with stakeholders and team +- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness +- [ ] **Documentation Update**: Update relevant documentation +- [ ] **Process Improvement**: Identify improvements for future planning + +--- + +**See also**: + +- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation planning +- `.cursor/rules/meta_feature_implementation.mdc` for implementation workflow +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation + +**Status**: Active meta-rule for feature planning +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, Product team, Architecture team diff --git a/.cursor/rules/meta_research.mdc b/.cursor/rules/meta_research.mdc new file mode 100644 index 0000000..0bbd0fb --- /dev/null +++ b/.cursor/rules/meta_research.mdc @@ -0,0 +1,285 @@ +# Meta-Rule: Enhanced Research Workflows + +**Author**: Matthew Raymer +**Date**: 2025-01-27 +**Status**: 🎯 **ACTIVE** - Research and investigation workflows + +## Purpose + +This meta-rule bundles research-specific rules that should be applied when conducting +systematic investigation, analysis, evidence collection, or research tasks. It provides +a comprehensive framework for thorough, methodical research workflows that produce +actionable insights and evidence-based conclusions. + +## Workflow Constraints + +**This meta-rule enforces RESEARCH MODE for all bundled sub-rules:** + +```json +{ + "workflowMode": "research", + "constraints": { + "mode": "investigation", + "allowed": ["read", "search", "analyze", "plan"], + "forbidden": ["modify", "create", "build", "commit"] + } +} +``` + +**All bundled sub-rules automatically inherit these constraints.** + +## Workflow State Update + +**When this meta-rule is invoked, update the workflow state file:** + +```json +{ + "currentMode": "research", + "lastInvoked": "meta_research.mdc", + "timestamp": "2025-01-27T15:30:00Z", + "constraints": { + "mode": "investigation", + "allowed": ["read", "search", "analyze", "plan"], + "forbidden": ["modify", "create", "build", "commit"] + } +} +``` + +**State File Location**: `.cursor/rules/.workflow_state.json` + +**This enables the core always-on rule to enforce research mode constraints.** + +## When to Use + +**RESEARCH TASKS** - Apply this meta-rule when: + +- Investigating bugs, defects, or system issues +- Conducting technical research or feasibility analysis +- Analyzing codebases, architectures, or dependencies +- Researching solutions, alternatives, or best practices +- Collecting evidence for decision-making or documentation +- Performing root cause analysis or impact assessment + +## Bundled Rules + +### **Core Research Principles** + +- **`development/research_diagnostic.mdc`** - Systematic investigation workflow + and evidence collection methodology +- **`development/type_safety_guide.mdc`** - Type analysis and safety research + for TypeScript/JavaScript codebases + +### **Investigation & Analysis** + +- **`workflow/version_control.mdc`** - Git history analysis and commit research +- **`workflow/commit_messages.mdc`** - Commit pattern analysis and history + investigation + +### **Platform & Context Research** + +- **`app/timesafari.mdc`** - Application context research and platform + understanding +- **`app/timesafari_platforms.mdc`** - Platform-specific research and + capability analysis + +## Why These Rules Are Research-Focused + +### **Research Diagnostic** + +- **Systematic Approach**: Provides structured investigation methodology +- **Evidence Collection**: Ensures thorough data gathering and documentation +- **Root Cause Analysis**: Guides systematic problem investigation +- **Impact Assessment**: Helps evaluate scope and consequences + +### **Type Safety Research** + +- **Code Analysis**: Enables systematic type system investigation +- **Safety Assessment**: Guides research into type-related issues +- **Migration Planning**: Supports research for architectural changes + +### **Version Control Research** + +- **History Analysis**: Enables investigation of code evolution +- **Pattern Recognition**: Helps identify commit and change patterns +- **Timeline Research**: Supports chronological investigation + +### **Platform Research** + +- **Capability Analysis**: Guides research into platform-specific features +- **Context Understanding**: Ensures research considers application context +- **Cross-Platform Research**: Supports multi-platform investigation + +## Application Priority + +### **Primary (Apply First)** + +1. **Research Diagnostic** - Systematic investigation methodology +2. **Type Safety Guide** - Code analysis and type research +3. **Application Context** - Platform and context understanding + +### **Secondary (Apply as Needed)** + +1. **Version Control** - When investigating code history +2. **Platform Details** - When researching platform-specific capabilities + +## Integration with Other Meta-Rules + +### **Bug Diagnosis** + +- Research meta-rule provides investigation methodology +- Core always-on ensures systematic approach +- Application context provides system understanding + +### **Feature Planning** + +- Research meta-rule guides feasibility research +- Core always-on ensures competence focus +- Application context drives platform considerations + +### **Architecture Analysis** + +- Research meta-rule provides systematic analysis framework +- Core always-on ensures quality standards +- Application context informs architectural decisions + +### **Performance Investigation** + +- Research meta-rule guides systematic performance research +- Core always-on ensures thorough investigation +- Application context provides performance context + +## Research Workflow Phases + +### **Phase 1: Investigation Setup** + +1. **Scope Definition** - Define research boundaries and objectives +2. **Context Gathering** - Collect relevant application and platform context +3. **Methodology Selection** - Choose appropriate research approaches + +### **Phase 2: Evidence Collection** + +1. **Systematic Data Gathering** - Collect evidence using structured methods +2. **Documentation** - Record all findings and observations +3. **Validation** - Verify evidence accuracy and relevance + +### **Phase 3: Analysis & Synthesis** + +1. **Pattern Recognition** - Identify trends and patterns in evidence +2. **Root Cause Analysis** - Determine underlying causes and factors +3. **Impact Assessment** - Evaluate scope and consequences + +### **Phase 4: Conclusion & Action** + +1. **Evidence-Based Conclusions** - Draw conclusions from collected evidence +2. **Actionable Recommendations** - Provide specific, implementable guidance +3. **Documentation** - Create comprehensive research documentation + +## Success Criteria + +- [ ] **Research diagnostic applied** to all investigation tasks +- [ ] **Type safety research** conducted for code analysis +- [ ] **Evidence collection** systematic and comprehensive +- [ ] **Root cause analysis** thorough and accurate +- [ ] **Conclusions actionable** and evidence-based +- [ ] **Documentation complete** and searchable + +## Common Research Pitfalls + +- **Don't skip systematic approach** - leads to incomplete investigation +- **Don't ignore evidence validation** - creates unreliable conclusions +- **Don't forget context** - misses important factors +- **Don't skip documentation** - loses research value +- **Don't rush conclusions** - produces poor recommendations + +## Research Quality Standards + +### **Evidence Quality** + +- **Completeness**: All relevant evidence collected +- **Accuracy**: Evidence verified and validated +- **Relevance**: Evidence directly addresses research questions +- **Timeliness**: Evidence current and up-to-date + +### **Analysis Quality** + +- **Systematic**: Analysis follows structured methodology +- **Objective**: Analysis free from bias and assumptions +- **Thorough**: All evidence considered and evaluated +- **Logical**: Conclusions follow from evidence + +### **Documentation Quality** + +- **Comprehensive**: All findings and methods documented +- **Searchable**: Documentation easily findable and navigable +- **Actionable**: Recommendations specific and implementable +- **Maintainable**: Documentation structure supports updates + +## Feedback & Improvement + +### **Rule Effectiveness Ratings (1-5 scale)** + +- **Research Diagnostic**: ___/5 - Comments: _______________ +- **Type Safety Guide**: ___/5 - Comments: _______________ +- **Version Control**: ___/5 - Comments: _______________ +- **Platform Context**: ___/5 - Comments: _______________ + +### **Research Workflow Effectiveness** + +- **Investigation Quality**: Are research tasks producing thorough results? +- **Evidence Collection**: Is evidence gathering systematic and complete? +- **Conclusion Quality**: Are conclusions actionable and evidence-based? +- **Documentation Value**: Is research documentation useful and maintainable? + +### **Integration Feedback** + +- **With Other Meta-Rules**: How well does this integrate with workflow rules? +- **Context Switching**: Do these rules help or hinder research context? +- **Learning Curve**: Are these rules easy for new researchers to understand? + +### **Overall Research Experience** + +- **Quality Improvement**: Do these rules improve research outcomes? +- **Efficiency**: Do these rules make research more efficient? +- **Recommendation**: Would you recommend keeping this research meta-rule? + +## Model Implementation Checklist + +### Before Research Tasks + +- [ ] **Research Diagnostic**: Ensure systematic investigation methodology +- [ ] **Type Safety Guide**: Prepare for code analysis if needed +- [ ] **Application Context**: Load relevant platform and context information +- [ ] **Version Control**: Prepare for history analysis if needed + +### During Research Execution + +- [ ] **Systematic Approach**: Follow structured investigation methodology +- [ ] **Evidence Collection**: Gather comprehensive and validated evidence +- [ ] **Documentation**: Record all findings and observations +- [ ] **Context Awareness**: Consider application and platform context + +### After Research Completion + +- [ ] **Validation**: Verify all research phases completed +- [ ] **Quality Check**: Ensure research meets quality standards +- [ ] **Documentation Review**: Confirm research properly documented +- [ ] **Feedback Collection**: Note any issues with research process + +--- + +**See also**: + +- `.cursor/rules/meta_core_always_on.mdc` for core always-on rules +- `.cursor/rules/meta_feature_planning.mdc` for feature development workflows +- `.cursor/rules/meta_bug_diagnosis.mdc` for bug investigation workflows +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation workflows + +**Status**: Active research meta-rule +**Priority**: High (applies to all research tasks) +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, Research team, Quality Assurance team +description: +globs: +alwaysApply: false +--- diff --git a/.cursor/rules/meta_rule_architecture.md b/.cursor/rules/meta_rule_architecture.md new file mode 100644 index 0000000..9f0bfb0 --- /dev/null +++ b/.cursor/rules/meta_rule_architecture.md @@ -0,0 +1,103 @@ +# Meta-Rule Architecture Overview + +**Author**: Matthew Raymer +**Date**: 2025-01-27 +**Status**: 📋 **ACTIVE** - Meta-rule organization and relationships + +## Meta-Rule Structure + +### **Core Always-On Rules** (`meta_core_always_on.mdc`) +- **Purpose**: Applied to every single prompt +- **Scope**: Human competence, time standards, version control, application context +- **Priority**: Critical - foundation for all interactions + +### **Enhanced Research Workflows** (`meta_research.mdc`) ⭐ **NEW** +- **Purpose**: Applied to research, investigation, and analysis tasks +- **Scope**: Systematic investigation, evidence collection, root cause analysis +- **Priority**: High - applies to all research tasks +- **Bundles**: Research diagnostic, type safety, version control research, platform context + +### **Feature Development Workflows** (`meta_feature_planning.mdc`) +- **Purpose**: Applied to feature planning and development tasks +- **Scope**: Requirements analysis, architecture planning, implementation strategy +- **Priority**: High - applies to feature development + +### **Bug Investigation Workflows** (`meta_bug_diagnosis.mdc`) +- **Purpose**: Applied to bug investigation and diagnosis tasks +- **Scope**: Defect analysis, evidence collection, root cause identification +- **Priority**: High - applies to bug investigation + +### **Bug Fixing Workflows** (`meta_bug_fixing.mdc`) +- **Purpose**: Applied to bug fixing and resolution tasks +- **Scope**: Fix implementation, testing, validation +- **Priority**: High - applies to bug resolution + +## Research Meta-Rule Integration + +### **When to Use Research Meta-Rule** + +The research meta-rule should be applied when: +- **Investigating bugs** - systematic defect analysis +- **Researching solutions** - feasibility and alternative analysis +- **Analyzing codebases** - architecture and dependency research +- **Collecting evidence** - systematic data gathering +- **Root cause analysis** - systematic problem investigation +- **Impact assessment** - scope and consequence evaluation + +### **How It Complements Other Meta-Rules** + +- **Core Always-On**: Provides foundation (competence, time, context) +- **Research**: Adds systematic investigation methodology +- **Feature Planning**: Guides feasibility research and analysis +- **Bug Diagnosis**: Provides investigation framework +- **Bug Fixing**: Informs fix strategy through research + +### **Research Workflow Phases** + +1. **Investigation Setup** - Scope, context, methodology +2. **Evidence Collection** - Systematic data gathering +3. **Analysis & Synthesis** - Pattern recognition, root cause +4. **Conclusion & Action** - Evidence-based recommendations + +## Usage Examples + +### **Bug Investigation** +``` +Apply: meta_core_always_on + meta_research + meta_bug_diagnosis +Result: Systematic investigation with evidence collection and root cause analysis +``` + +### **Feature Research** +``` +Apply: meta_core_always_on + meta_research + meta_feature_planning +Result: Comprehensive feasibility research with platform context +``` + +### **Architecture Analysis** +``` +Apply: meta_core_always_on + meta_research +Result: Systematic architecture investigation with evidence-based conclusions +``` + +## Benefits of Enhanced Research Meta-Rule + +- **Systematic Approach**: Structured investigation methodology +- **Evidence-Based**: Comprehensive data collection and validation +- **Quality Standards**: Defined research quality criteria +- **Integration**: Seamless integration with existing workflows +- **Documentation**: Comprehensive research documentation standards + +## Next Steps + +1. **Test Research Meta-Rule** - Apply to next research task +2. **Validate Integration** - Ensure smooth workflow integration +3. **Collect Feedback** - Gather effectiveness ratings +4. **Iterate** - Refine based on usage experience + +--- + +**Status**: Active documentation +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: All meta-rules +**Stakeholders**: Development team, Research team diff --git a/.cursor/rules/progress_reports.mdc b/.cursor/rules/progress_reports.mdc deleted file mode 100644 index c1ee163..0000000 --- a/.cursor/rules/progress_reports.mdc +++ /dev/null @@ -1,6 +0,0 @@ ---- -alwaysApply: true ---- -progress reports are based on git commit messages and file differences for that day -reports are in conversational style -do not be a bean counter unless otherwise instructed \ No newline at end of file diff --git a/.cursor/rules/project.mdc b/.cursor/rules/project.mdc deleted file mode 100644 index eeed6ae..0000000 --- a/.cursor/rules/project.mdc +++ /dev/null @@ -1,242 +0,0 @@ -# TimeSafari Notifications — LLM Implementation Directive (v2.0) -_Last updated: August 12, 2025_ - -## 0) Role & Objective -**You are the implementation LLM.** Build an **offline-first daily notifications system** for Android (Kotlin) and iOS (Swift) that **prefetches -> caches -> schedules -> displays** content **without requiring network at display time**. Favor **reliability over richness**. - -## 1) Golden Rules -1. **Follow the pipeline:** **Prefetch → Cache → Schedule → Display.** -2. **Never depend on network at display time.** All assets must be local. -3. **Design for failure.** Always have a last-known-good and an emergency fallback. -4. **Keep content scannable (<3s), single message, actionable.** -5. **Measure everything** (fetch success, delivery, engagement, stale usage). -6. **Minimize battery impact** and respect platform limitations and user settings. -7. **Ask only when needed:** if a required input is missing, use the defaults below; otherwise proceed. - -## 2) Default Assumptions (use unless overridden) -- **Product mode:** Lightweight Daily Updates (text + emoji) with option to extend to media later. -- **Fetch size:** 1–2 KB JSON daily. -- **User schedule default:** 07:30 local time, daily. -- **Quiet hours:** None (app-level quiet hours supported but disabled by default). -- **Analytics:** Local log + pluggable uploader (no-op by default). - -## 3) Deliverables -Produce the following artifacts: - -### Android (Kotlin) -- `:core`: models, storage, metrics, fallback manager. -- `:data`: fetchers (WorkManager), mappers, cache policy. -- `:notify`: scheduler (AlarmManager), receiver, channels. -- App manifest entries & permissions. -- Unit tests for fallback, scheduling, metrics. -- README with battery optimization instructions (OEMs). - -### iOS (Swift) -- `NotificationKit`: models, storage, metrics, fallback manager. -- BGTaskScheduler registration + handler. -- UNUserNotificationCenter scheduling + categories + attachments. -- Unit tests for fallback, scheduling, metrics. -- README with Background App Refresh caveats + Focus/Summary notes. - -## 4) Permissions & Required Setup -### Android Manifest -```xml - - - - -``` -- Create a high-importance **NotificationChannel** `timesafari.daily`. -- If **SCHEDULE_EXACT_ALARM** denied on Android 12+, auto-fallback to inexact. - -### iOS App Setup (AppDelegate / SceneDelegate) -- Register `BGTaskScheduler` with ID `com.timesafari.daily-fetch`. -- Request alerts, sound, badge via `UNUserNotificationCenter`. -- Create category `DAILY_UPDATE` with a primary `View` action. -- Ensure Background Modes: **Background fetch**, **Remote notifications** (optional for future push). - -## 5) Data Model (keep minimal, versioned) -### Canonical Schema (language-agnostic) -``` -NotificationContent v1 -- id: string (uuid) -- title: string -- body: string (plain text; may include simple emoji) -- scheduledTime: epoch millis (client-local target) -- mediaUrl: string? (for future; must be mirrored to local path before use) -- fetchTime: epoch millis -``` -### Kotlin -```kotlin -@Entity -data class NotificationContent( - @PrimaryKey val id: String, - val title: String, - val body: String, - val scheduledTime: Long, - val mediaUrl: String?, - val fetchTime: Long -) -``` -### Swift -```swift -struct NotificationContent: Codable { - let id: String - let title: String - let body: String - let scheduledTime: TimeInterval - let mediaUrl: String? - let fetchTime: TimeInterval -} -``` - -## 6) Storage Layers -**Tier 1: Key-Value (quick)** — next payload, last fetch timestamp, user prefs. -**Tier 2: DB (structured)** — history, media metadata, analytics events. -**Tier 3: Files (large assets)** — images/audio; LRU cache & quotas. - -- Android: SharedPreferences/DataStore + Room + `context.cacheDir/notifications/` -- iOS: UserDefaults + Core Data/SQLite + `Library/Caches/notifications/` - -## 7) Background Execution -### Android — WorkManager -- Periodic daily work with constraints (CONNECTED network). -- Total time budget ~10m; use **timeouts** (e.g., fetch ≤30s, overall ≤8m). -- On exception/timeout: **schedule from cache**; then `Result.success()` or `Result.retry()` per policy. - -### iOS — BGTaskScheduler -- `BGAppRefreshTask` with aggressive time budgeting (10–30s typical). -- Submit next request immediately at start of handler. -- Set `expirationHandler` first; cancel tasks cleanly; **fallback to cache** on failure. - -## 8) Scheduling & Display -### Android -- Prefer `AlarmManager.setExactAndAllowWhileIdle()` if permitted; else inexact. -- Receiver builds notification using **BigTextStyle** for long bodies. -- Limit actions to ≤3; default: `View` (foreground intent). - -### iOS -- `UNCalendarNotificationTrigger` repeating at preferred time. -- Category `DAILY_UPDATE` with `View` action. -- Media attachments **only if local**; otherwise skip gracefully. - -## 9) Fallback Hierarchy (must implement) -1. **Foreground prefetch path** if app is open. -2. **Background fetch** with short network timeout. -3. **Last good cache** (annotate staleness: “as of X”). -4. **Emergency phrases** (rotate from static list). - -Provide helper: -- `withStaleMarker(content) -> content'` appends age label (e.g., “from 3h ago”). - -## 10) Failure Matrix & Responses -| Scenario | Detect | Action | -|---|---|---| -| No network / timeout | Exceptions / status | Use last-good; schedule | -| Invalid JSON | Parse error | Use emergency content; log | -| Storage full | Write error | Evict old; retry minimal payload | -| Notifications disabled | OS state | In-app education screen | -| Background killed | Gaps in execution | Catch-up next foreground open | - -## 11) Metrics (local first; uploader optional) -Track per attempt: -``` -NotificationMetrics v1 -- scheduledTime, actualDeliveryTime? -- contentAge (ms) -- engagement: {TAPPED, DISMISSED, IGNORED}? -- failureReason? -- platformInfo (oem, os version, app state) -``` -- Compute: **Fetch Success Rate**, **Delivery Rate**, **Engagement Rate**, **Stale Content Rate**. - -## 12) Testing Requirements -### Matrix (minimum) -- Android 12+ foreground/background/killed; with/without Battery Saver; Wi‑Fi/Mobile/Offline. -- iOS 16+ background/Low Power/Focus/Scheduled Summary on & off. -- Offline at trigger time (must still display). - -### Unit Tests (examples) -- Fallback when fetch fails (uses last-good and marks stale). -- Exact vs inexact scheduling path selected correctly. -- Metrics recorded for each stage. - -## 13) UX Standards -- One clear message; no clutter. -- ≤2 actions; primary takes user into app. -- Respect quiet hours if configured. -- Provide onboarding: value explanation → permission request → time picker → test notification → tips for OEM battery settings (Android) or Focus/Summary (iOS). - -## 14) Code Stubs (must generate & wire) -### Android — Worker (core pattern) -```kotlin -class DailyContentWorker(ctx: Context, params: WorkerParameters) : CoroutineWorker(ctx, params) { - override suspend fun doWork(): Result = try { - withTimeout(8.minutes) { - val content = fetchDailyContent(timeout = 30.seconds) - saveToCache(content) - scheduleNotification(content) - } - Result.success() - } catch (e: TimeoutCancellationException) { - scheduleFromCache(); Result.success() - } catch (e: Exception) { - scheduleFromCache(); Result.retry() - } -} -``` -### iOS — BG Refresh Handler (core pattern) -```swift -func handleBackgroundRefresh(_ task: BGAppRefreshTask) { - scheduleNextRefresh() - var finished = false - task.expirationHandler = { if !finished { cancelNetwork(); task.setTaskCompleted(success: false) } } - fetchDailyContent(timeout: 15) { result in - defer { finished = true; task.setTaskCompleted(success: result.isSuccess) } - switch result { - case .success(let content): quickSave(content); scheduleNotification(content) - case .failure: scheduleFromCache() - } - } -} -``` - -## 15) Security & Privacy -- Use HTTPS; pin if required. -- Strip PII from payloads; keep content generic by default. -- Store only what is necessary; apply cache quotas; purge on logout/uninstall. -- Respect OS privacy settings (Focus, Scheduled Summary, Quiet Hours). - -## 16) Troubleshooting Playbook (LLM should generate helpers) -- Android: verify permission, channel, OEM battery settings; `adb shell dumpsys notification`. -- iOS: check authorization, Background App Refresh, Low Power, Focus/Summary state. - -## 17) Roadmap Flags (implement behind switches) -- `FEATURE_MEDIA_ATTACHMENTS` (default off). -- `FEATURE_PERSONALIZATION_ENGINE` (time/frequency, content types). -- `FEATURE_PUSH_REALTIME` (server-driven for urgent alerts). - -## 18) Definition of Done -- Notifications deliver daily at user-selected time **without network**. -- Graceful fallback chain proven by tests. -- Metrics recorded locally; viewable log. -- Clear onboarding and self-diagnostic screen. -- Battery/OS constraints documented; user education available. - -## 19) Quick Start (LLM execution order) -1. Scaffold modules (Android + iOS). -2. Implement models + storage + fallback content. -3. Implement schedulers (AlarmManager / UNCalendarNotificationTrigger). -4. Implement background fetchers (WorkManager / BGTaskScheduler). -5. Wire onboarding + test notification. -6. Add metrics logging. -7. Ship minimal, then iterate. - ---- - -### Appendix A — Emergency Fallback Lines -- "🌅 Good morning! Ready to make today amazing?" -- "💪 Every small step forward counts. You've got this!" -- "🎯 Focus on what you can control today." -- "✨ Your potential is limitless. Keep growing!" -- "🌟 Progress over perfection, always." diff --git a/.cursor/rules/templates/adr_template.mdc b/.cursor/rules/templates/adr_template.mdc new file mode 100644 index 0000000..6114b28 --- /dev/null +++ b/.cursor/rules/templates/adr_template.mdc @@ -0,0 +1,98 @@ +--- +alwaysApply: false +--- + +# ADR Template + +## ADR-XXXX-YY-ZZ: [Short Title] + +**Date:** YYYY-MM-DD +**Status:** [PROPOSED | ACCEPTED | REJECTED | DEPRECATED | SUPERSEDED] +**Deciders:** [List of decision makers] +**Technical Story:** [Link to issue/PR if applicable] + +## Context + +[Describe the forces at play, including technological, political, social, and +project local. These forces are probably in tension, and should be called out as +such. The language in this section is value-neutral. It is simply describing + facts.] + +## Decision + +[Describe our response to these forces. We will use the past tense ( + "We will...").] + +## Consequences + +### Positive + +- [List positive consequences] + +### Negative + +- [List negative consequences or trade-offs] + +### Neutral + +- [List neutral consequences or notes] + +## Alternatives Considered + +- **Alternative 1:** [Description] - [Why rejected] + +- **Alternative 2:** [Description] - [Why rejected] + +- **Alternative 3:** [Description] - [Why rejected] + +## Implementation Notes + +[Any specific implementation details, migration steps, or + technical considerations] + +## References + +- [Link to relevant documentation] + +- [Link to related ADRs] + +- [Link to external resources] + +## Related Decisions + +- [List related ADRs or decisions] + +--- + +## Usage Guidelines + +1. **Copy this template** for new ADRs +2. **Number sequentially** (ADR-001, ADR-002, etc.) +3. **Use descriptive titles** that clearly indicate the decision +4. **Include all stakeholders** in the deciders list +5. **Link to related issues** and documentation +6. **Update status** as decisions evolve +7. **Store in** `doc/architecture-decisions/` directory + +## Model Implementation Checklist + +### Before ADR Creation + +- [ ] **Decision Context**: Understand the decision that needs to be made +- [ ] **Stakeholder Identification**: Identify all decision makers +- [ ] **Research**: Research alternatives and gather evidence +- [ ] **Template Selection**: Choose appropriate ADR template + +### During ADR Creation + +- [ ] **Context Documentation**: Document the context and forces at play +- [ ] **Decision Recording**: Record the decision and rationale +- [ ] **Consequences Analysis**: Analyze positive, negative, and neutral consequences +- [ ] **Alternatives Documentation**: Document alternatives considered + +### After ADR Creation + +- [ ] **Review**: Review ADR with stakeholders +- [ ] **Approval**: Get approval from decision makers +- [ ] **Communication**: Communicate decision to team +- [ ] **Implementation**: Plan implementation of the decision diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc deleted file mode 100644 index 8a15f9b..0000000 --- a/.cursor/rules/testing.mdc +++ /dev/null @@ -1,12 +0,0 @@ ---- -alwaysApply: true ---- - -**always** - -use pydantic and marshallow -use mocking, unit tests, e2e -fragment tests into folders acccording to feature, sub-feature, sub-sub-feature, etc. -document each folder with a README.md -examples are tests using real data instead of mocks-units -examples have their own folder system structured the same diff --git a/.cursor/rules/time.mdc b/.cursor/rules/time.mdc deleted file mode 100644 index 3534990..0000000 --- a/.cursor/rules/time.mdc +++ /dev/null @@ -1,5 +0,0 @@ ---- -alwaysApply: true ---- -Eagerly query the local system for time in UTC -Use local system time for all time sense, queries, and calculations involving time. diff --git a/.cursor/rules/version_control.mdc b/.cursor/rules/version_control.mdc deleted file mode 100644 index 212e000..0000000 --- a/.cursor/rules/version_control.mdc +++ /dev/null @@ -1,7 +0,0 @@ ---- -alwaysApply: true ---- -use git -commit messages are based on unstaged files and the chnages made to them -present proposed messages for approval -get approval before staging or commmiting diff --git a/.cursor/rules/versioning.mdc b/.cursor/rules/versioning.mdc deleted file mode 100644 index 892855e..0000000 --- a/.cursor/rules/versioning.mdc +++ /dev/null @@ -1,7 +0,0 @@ ---- -alwaysApply: true ---- - -Semantic Versioning: Follows MAJOR.MINOR.PATCH format -Centralized Management: Single source of truth for all version information -Git Integration: Automatic commit hash detection