Jose Olarte III
2 months ago
185 changed files with 15455 additions and 3630 deletions
@ -0,0 +1,151 @@ |
|||||
|
# .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 |
||||
|
|
||||
|
## 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 |
||||
@ -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<string> { |
||||
|
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<string, Function[]> = new Map(); |
||||
|
|
||||
|
async startScanning(): Promise<void> { |
||||
|
this.isScanning = true; |
||||
|
this.emit('scanningStarted'); |
||||
|
} |
||||
|
|
||||
|
async stopScanning(): Promise<void> { |
||||
|
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<void> { |
||||
|
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 |
||||
@ -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 |
||||
@ -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<void>; |
||||
|
stopScanning(): Promise<void>; |
||||
|
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<string, Function[]> = new Map(); |
||||
|
|
||||
|
async startScanning(): Promise<void> { |
||||
|
// Web-specific implementation |
||||
|
const stream = await navigator.mediaDevices.getUserMedia({ video: true }); |
||||
|
// Process video stream for QR codes |
||||
|
} |
||||
|
|
||||
|
async stopScanning(): Promise<void> { |
||||
|
// 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://<route>[/<param>][?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 |
||||
@ -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 <repository-url>` |
||||
|
|
||||
|
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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -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 <prev>`; 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 <custom>` 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 |
||||
@ -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 |
||||
@ -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 |
||||
|
|
||||
|
<one suitable diagram: sequenceDiagram | flowchart | stateDiagram | gantt | |
||||
|
classDiagram> |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Note**: Replace the placeholder with an actual diagram that illustrates |
||||
|
the technical process, architecture, or workflow being documented. |
||||
@ -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 |
||||
@ -1,8 +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 |
||||
|
|
||||
--- |
--- |
||||
globs: **/databaseUtil.ts,**/AccountViewView.vue,**/ContactsView.vue,**/DatabaseMigration.vue,**/NewIdentifierView.vue |
|
||||
alwaysApply: false |
|
||||
--- |
|
||||
# What to do with Dexie |
|
||||
|
|
||||
All references in the codebase to Dexie apply only to migration from IndexedDb to |
**Status**: Legacy migration guidelines |
||||
Sqlite and will be deprecated in future versions. |
**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 |
||||
|
|||||
@ -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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -1,332 +0,0 @@ |
|||||
--- |
|
||||
globs: *.md |
|
||||
alwaysApply: false |
|
||||
--- |
|
||||
# Cursor Markdown Ruleset for TimeSafari Documentation |
|
||||
|
|
||||
## Overview |
|
||||
|
|
||||
This ruleset enforces consistent markdown formatting standards across all project |
|
||||
documentation, ensuring readability, maintainability, and compliance with |
|
||||
markdownlint best practices. |
|
||||
|
|
||||
## General 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 |
|
||||
- **Use case**: Project planning, checklists, implementation tracking |
|
||||
|
|
||||
## Code Block Standards |
|
||||
|
|
||||
### Fenced Code Blocks |
|
||||
|
|
||||
- **Syntax**: Triple backticks with language specification |
|
||||
- **Languages**: `json`, `bash`, `typescript`, `javascript`, `yaml`, `markdown` |
|
||||
- **Blank lines**: Must be surrounded by blank lines above and below |
|
||||
- **Line length**: No enforcement within code blocks |
|
||||
|
|
||||
### Inline Code |
|
||||
|
|
||||
- **Format**: Single backticks for inline code references |
|
||||
- **Use case**: File names, commands, variables, properties |
|
||||
|
|
||||
## Special Content Standards |
|
||||
|
|
||||
### 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 |
|
||||
/** |
|
||||
* Get environment configuration |
|
||||
* @param env - Environment name |
|
||||
* @returns Environment config object |
|
||||
*/ |
|
||||
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 |
|
||||
|
|
||||
1. **Overview/Introduction** |
|
||||
2. **Current State Analysis** |
|
||||
3. **Implementation Plan** |
|
||||
4. **Technical Details** |
|
||||
5. **Testing & Validation** |
|
||||
6. **Next Steps** |
|
||||
|
|
||||
## Markdownlint Configuration |
|
||||
|
|
||||
### Required Rules |
|
||||
|
|
||||
```json |
|
||||
{ |
|
||||
"MD013": { "code_blocks": false }, |
|
||||
"MD012": true, |
|
||||
"MD022": true, |
|
||||
"MD031": true, |
|
||||
"MD032": true, |
|
||||
"MD047": true, |
|
||||
"MD009": true |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
### Rule Explanations |
|
||||
|
|
||||
- **MD013**: Line length (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 |
|
||||
|
|
||||
## Validation Commands |
|
||||
|
|
||||
### Check Single File |
|
||||
|
|
||||
```bash |
|
||||
npx markdownlint docs/filename.md |
|
||||
``` |
|
||||
|
|
||||
### Check All Documentation |
|
||||
|
|
||||
```bash |
|
||||
npx markdownlint docs/ |
|
||||
``` |
|
||||
|
|
||||
### Auto-fix Common Issues |
|
||||
|
|
||||
```bash |
|
||||
# Remove trailing spaces |
|
||||
sed -i 's/[[:space:]]*$//' docs/filename.md |
|
||||
|
|
||||
# Remove multiple blank lines |
|
||||
sed -i '/^$/N;/^\n$/D' docs/filename.md |
|
||||
|
|
||||
# Add newline at end if missing |
|
||||
echo "" >> docs/filename.md |
|
||||
``` |
|
||||
|
|
||||
## Common Patterns |
|
||||
|
|
||||
### Implementation Plans |
|
||||
|
|
||||
```markdown |
|
||||
## Implementation Plan |
|
||||
|
|
||||
### Phase 1: Foundation (Day 1) |
|
||||
|
|
||||
#### 1.1 Component Setup |
|
||||
|
|
||||
- [ ] Create new component file |
|
||||
- [ ] Add basic structure |
|
||||
- [ ] Implement core functionality |
|
||||
|
|
||||
#### 1.2 Configuration |
|
||||
|
|
||||
- [ ] Update configuration files |
|
||||
- [ ] Add environment variables |
|
||||
- [ ] Test configuration loading |
|
||||
``` |
|
||||
|
|
||||
### Status Tracking |
|
||||
|
|
||||
```markdown |
|
||||
**Status**: ✅ **COMPLETE** - All phases finished |
|
||||
**Progress**: 75% (15/20 components) |
|
||||
**Next**: Ready for testing phase |
|
||||
``` |
|
||||
|
|
||||
### Performance Metrics |
|
||||
|
|
||||
```markdown |
|
||||
#### 📊 Performance Metrics |
|
||||
- **Build Time**: 2.3 seconds (50% faster than baseline) |
|
||||
- **Bundle Size**: 1.2MB (30% reduction) |
|
||||
- **Success Rate**: 100% (no failures in 50 builds) |
|
||||
``` |
|
||||
|
|
||||
## Enforcement |
|
||||
|
|
||||
### Pre-commit Hooks |
|
||||
|
|
||||
- Run markdownlint on all changed markdown files |
|
||||
- Block commits with linting violations |
|
||||
- Auto-fix common issues when possible |
|
||||
|
|
||||
### CI/CD Integration |
|
||||
|
|
||||
- Include markdownlint in build pipeline |
|
||||
- Generate reports for documentation quality |
|
||||
- Fail builds with critical violations |
|
||||
|
|
||||
### Team Guidelines |
|
||||
|
|
||||
- All documentation PRs must pass markdownlint |
|
||||
- Use provided templates for new documents |
|
||||
- Follow established patterns for consistency |
|
||||
|
|
||||
## Templates |
|
||||
|
|
||||
### New Document Template |
|
||||
|
|
||||
```markdown |
|
||||
# Document Title |
|
||||
|
|
||||
**Author**: Matthew Raymer |
|
||||
**Date**: YYYY-MM-DD |
|
||||
**Status**: 🎯 **PLANNING** - Ready for Implementation |
|
||||
|
|
||||
## Overview |
|
||||
|
|
||||
Brief description of the document's purpose and scope. |
|
||||
|
|
||||
## Current State |
|
||||
|
|
||||
Description of current situation or problem. |
|
||||
|
|
||||
## Implementation Plan |
|
||||
|
|
||||
### Phase 1: Foundation |
|
||||
|
|
||||
- [ ] Task 1 |
|
||||
- [ ] Task 2 |
|
||||
|
|
||||
## Next Steps |
|
||||
|
|
||||
1. **Review and approve plan** |
|
||||
2. **Begin implementation** |
|
||||
3. **Test and validate** |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
**Status**: Ready for implementation |
|
||||
**Priority**: Medium |
|
||||
**Estimated Effort**: X days |
|
||||
**Dependencies**: None |
|
||||
**Stakeholders**: Development team |
|
||||
``` |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
**Last Updated**: 2025-07-09 |
|
||||
**Version**: 1.0 |
|
||||
**Maintainer**: Matthew Raymer |
|
||||
|
|
||||
|
|
||||
### Heading Uniqueness |
|
||||
|
|
||||
- **Rule**: No duplicate heading content at the same level |
|
||||
- **Scope**: Within a single document |
|
||||
- **Rationale**: Maintains clear document structure and navigation |
|
||||
- **Example**: |
|
||||
|
|
||||
```markdown |
|
||||
## Features ✅ |
|
||||
### Authentication |
|
||||
### Authorization |
|
||||
|
|
||||
## Features ❌ (Duplicate heading) |
|
||||
### Security |
|
||||
### Performance |
|
||||
``` |
|
||||
@ -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 |
||||
@ -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<T> { |
||||
|
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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -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 |
||||
@ -0,0 +1,172 @@ |
|||||
|
# Meta-Rule: Bug Diagnosis |
||||
|
|
||||
|
**Author**: Matthew Raymer |
||||
|
**Date**: 2025-08-21 |
||||
|
**Status**: 🎯 **ACTIVE** - Bug investigation workflow bundling |
||||
|
|
||||
|
## Purpose |
||||
|
|
||||
|
This meta-rule bundles all the rules needed for systematic bug investigation |
||||
|
and root cause analysis. Use this when bugs are reported, performance |
||||
|
issues occur, or unexpected behavior happens. |
||||
|
|
||||
|
## When to Use |
||||
|
|
||||
|
- **Bug Reports**: Investigating reported bugs or issues |
||||
|
- **Performance Issues**: Diagnosing slow performance or bottlenecks |
||||
|
- **Unexpected Behavior**: Understanding why code behaves unexpectedly |
||||
|
- **Production Issues**: Investigating issues in live environments |
||||
|
- **Test Failures**: Understanding why tests are failing |
||||
|
- **Integration Problems**: Diagnosing issues between components |
||||
|
|
||||
|
## Bundled Rules |
||||
|
|
||||
|
### **Investigation Process** |
||||
|
|
||||
|
- **`development/research_diagnostic.mdc`** - Systematic investigation |
||||
|
workflow with evidence collection and analysis |
||||
|
- **`development/investigation_report_example.mdc`** - Investigation |
||||
|
documentation templates and examples |
||||
|
- **`core/harbor_pilot_universal.mdc`** - Technical guide creation |
||||
|
for complex investigations |
||||
|
|
||||
|
### **Evidence Collection** |
||||
|
|
||||
|
- **`development/logging_standards.mdc`** - Logging implementation |
||||
|
standards for debugging and evidence collection |
||||
|
- **`development/time.mdc`** - Timestamp requirements and time |
||||
|
handling standards for evidence |
||||
|
- **`development/time_examples.mdc`** - Practical examples of |
||||
|
proper time handling in investigations |
||||
|
|
||||
|
### **Technical Context** |
||||
|
|
||||
|
- **`app/timesafari.mdc`** - Core application context and |
||||
|
architecture for understanding the system |
||||
|
- **`app/timesafari_platforms.mdc`** - Platform-specific |
||||
|
considerations and constraints |
||||
|
|
||||
|
## Workflow Sequence |
||||
|
|
||||
|
### **Phase 1: Initial Investigation (Start Here)** |
||||
|
|
||||
|
1. **Research Diagnostic** - Use `research_diagnostic.mdc` for |
||||
|
systematic investigation approach |
||||
|
2. **Evidence Collection** - Apply `logging_standards.mdc` and |
||||
|
`time.mdc` for proper evidence gathering |
||||
|
3. **Context Understanding** - Review `timesafari.mdc` for |
||||
|
application context |
||||
|
|
||||
|
### **Phase 2: Deep Investigation** |
||||
|
|
||||
|
1. **Platform Analysis** - Check `timesafari_platforms.mdc` for |
||||
|
platform-specific issues |
||||
|
2. **Technical Guide Creation** - Use `harbor_pilot_universal.mdc` |
||||
|
for complex investigation documentation |
||||
|
3. **Evidence Analysis** - Apply `time_examples.mdc` for proper |
||||
|
timestamp handling |
||||
|
|
||||
|
### **Phase 3: Documentation & Reporting** |
||||
|
|
||||
|
1. **Investigation Report** - Use `investigation_report_example.mdc` |
||||
|
for comprehensive documentation |
||||
|
2. **Root Cause Analysis** - Synthesize findings into actionable |
||||
|
insights |
||||
|
|
||||
|
## Success Criteria |
||||
|
|
||||
|
- [ ] **Root cause identified** with supporting evidence |
||||
|
- [ ] **Evidence properly collected** with timestamps and context |
||||
|
- [ ] **Investigation documented** using appropriate templates |
||||
|
- [ ] **Platform factors considered** in diagnosis |
||||
|
- [ ] **Reproduction steps documented** for verification |
||||
|
- [ ] **Impact assessment completed** with scope defined |
||||
|
- [ ] **Next steps identified** for resolution |
||||
|
|
||||
|
## Common Pitfalls |
||||
|
|
||||
|
- **Don't skip evidence collection** - leads to speculation |
||||
|
- **Don't ignore platform differences** - misses platform-specific issues |
||||
|
- **Don't skip documentation** - loses investigation insights |
||||
|
- **Don't assume root cause** - verify with evidence |
||||
|
- **Don't ignore time context** - misses temporal factors |
||||
|
- **Don't skip reproduction steps** - makes verification impossible |
||||
|
|
||||
|
## Integration Points |
||||
|
|
||||
|
### **With Other Meta-Rules** |
||||
|
|
||||
|
- **Feature Planning**: Use complexity assessment for investigation planning |
||||
|
- **Bug Fixing**: Investigation results feed directly into fix implementation |
||||
|
- **Feature Implementation**: Investigation insights inform future development |
||||
|
|
||||
|
### **With Development Workflow** |
||||
|
|
||||
|
- Investigation findings inform testing strategy |
||||
|
- Root cause analysis drives preventive measures |
||||
|
- Evidence collection improves logging standards |
||||
|
|
||||
|
## Feedback & Improvement |
||||
|
|
||||
|
### **Sub-Rule Ratings (1-5 scale)** |
||||
|
|
||||
|
- **Research Diagnostic**: ___/5 - Comments: _______________ |
||||
|
- **Investigation Report**: ___/5 - Comments: _______________ |
||||
|
- **Technical Guide Creation**: ___/5 - Comments: _______________ |
||||
|
- **Logging Standards**: ___/5 - Comments: _______________ |
||||
|
- **Time Standards**: ___/5 - Comments: _______________ |
||||
|
|
||||
|
### **Workflow Feedback** |
||||
|
|
||||
|
- **Investigation Effectiveness**: How well did the process help find root cause? |
||||
|
- **Missing Steps**: What investigation steps should be added? |
||||
|
- **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? |
||||
|
- **Template Improvements**: How could investigation templates be better? |
||||
|
|
||||
|
### **Overall Experience** |
||||
|
|
||||
|
- **Time Saved**: How much time did this meta-rule save you? |
||||
|
- **Quality Improvement**: Did following these rules improve your investigation? |
||||
|
- **Recommendation**: Would you recommend this meta-rule to others? |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Bug Investigation |
||||
|
|
||||
|
- [ ] **Problem Definition**: Clearly define what needs to be investigated |
||||
|
- [ ] **Scope Definition**: Determine investigation scope and boundaries |
||||
|
- [ ] **Evidence Planning**: Plan evidence collection strategy |
||||
|
- [ ] **Stakeholder Identification**: Identify who needs to be involved |
||||
|
|
||||
|
### During Bug Investigation |
||||
|
|
||||
|
- [ ] **Rule Application**: Apply bundled rules in recommended sequence |
||||
|
- [ ] **Evidence Collection**: Collect evidence systematically with timestamps |
||||
|
- [ ] **Documentation**: Document investigation process and findings |
||||
|
- [ ] **Validation**: Verify findings with reproduction steps |
||||
|
|
||||
|
### After Bug Investigation |
||||
|
|
||||
|
- [ ] **Report Creation**: Create comprehensive investigation report |
||||
|
- [ ] **Root Cause Analysis**: Document root cause with evidence |
||||
|
- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness |
||||
|
- [ ] **Process Improvement**: Identify improvements for future investigations |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: |
||||
|
|
||||
|
- `.cursor/rules/meta_feature_planning.mdc` for planning investigation work |
||||
|
- `.cursor/rules/meta_bug_fixing.mdc` for implementing fixes |
||||
|
- `.cursor/rules/meta_feature_implementation.mdc` for preventive measures |
||||
|
|
||||
|
**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 |
||||
@ -0,0 +1,175 @@ |
|||||
|
# 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. |
||||
|
|
||||
|
## 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 |
||||
@ -0,0 +1,196 @@ |
|||||
|
--- |
||||
|
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. |
||||
|
|
||||
|
## 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 |
||||
@ -0,0 +1,237 @@ |
|||||
|
# 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. |
||||
|
|
||||
|
## 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 |
||||
@ -0,0 +1,187 @@ |
|||||
|
# 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. |
||||
|
|
||||
|
## 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 |
||||
@ -0,0 +1,165 @@ |
|||||
|
# 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. |
||||
|
|
||||
|
## 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 |
||||
@ -0,0 +1,247 @@ |
|||||
|
# 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. |
||||
|
|
||||
|
## 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 |
||||
|
--- |
||||
@ -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 |
||||
@ -0,0 +1,196 @@ |
|||||
|
# Commit Message Format and Templates |
||||
|
|
||||
|
> **Agent role**: |
||||
|
Reference this file for commit message formatting and templates. |
||||
|
|
||||
|
## Commit Message Format (Normative) |
||||
|
|
||||
|
### A. Subject Line (required) |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
<type>(<scope>)<!>: <summary> |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
- **type** (lowercase, Conventional Commits): |
||||
|
|
||||
|
`feat|fix|refactor|perf|docs|test|build|chore|ci|revert` |
||||
|
|
||||
|
- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`) |
||||
|
|
||||
|
- **!**: include when a breaking change is introduced |
||||
|
|
||||
|
- **summary**: imperative mood, ≤ 72 chars, no trailing period |
||||
|
|
||||
|
**Examples** |
||||
|
|
||||
|
- `fix(api): handle null token in refresh path` |
||||
|
|
||||
|
- `feat(ui/login)!: require OTP after 3 failed attempts` |
||||
|
|
||||
|
### B. Body (optional, when it adds non-obvious value) |
||||
|
|
||||
|
- One blank line after subject. |
||||
|
|
||||
|
- Wrap at ~72 chars. |
||||
|
|
||||
|
- Explain **what** and **why**, not line-by-line "how". |
||||
|
|
||||
|
- Include brief notes like tests passing or TS/lint issues resolved |
||||
|
|
||||
|
**only if material**. |
||||
|
|
||||
|
**Body checklist** |
||||
|
|
||||
|
- [ ] Problem/symptom being addressed |
||||
|
|
||||
|
- [ ] High-level approach or rationale |
||||
|
|
||||
|
- [ ] Risks, tradeoffs, or follow-ups (if any) |
||||
|
|
||||
|
### C. Footer (optional) |
||||
|
|
||||
|
- Issue refs: `Closes #123`, `Refs #456` |
||||
|
|
||||
|
- Breaking change (alternative to `!`): |
||||
|
|
||||
|
`BREAKING CHANGE: <impact + migration note>` |
||||
|
|
||||
|
- Authors: `Co-authored-by: Name <email>` |
||||
|
|
||||
|
- Security: `CVE-XXXX-YYYY: <short note>` (if applicable) |
||||
|
|
||||
|
## Content Guidance |
||||
|
|
||||
|
### Include (when relevant) |
||||
|
|
||||
|
- Specific fixes/features delivered |
||||
|
|
||||
|
- Symptoms/problems fixed |
||||
|
|
||||
|
- Brief note that tests passed or TS/lint errors resolved |
||||
|
|
||||
|
### Avoid |
||||
|
|
||||
|
- Vague: *improved, enhanced, better* |
||||
|
|
||||
|
- Trivialities: tiny docs, one-liners, pure lint cleanups (separate, |
||||
|
|
||||
|
focused commits if needed) |
||||
|
|
||||
|
- Redundancy: generic blurbs repeated across files |
||||
|
|
||||
|
- Multi-purpose dumps: keep commits **narrow and focused** |
||||
|
|
||||
|
- Long explanations that good inline code comments already cover |
||||
|
|
||||
|
**Guiding Principle:** Let code and inline docs speak. Use commits to |
||||
|
highlight what isn't obvious. |
||||
|
|
||||
|
## Copy-Paste Templates |
||||
|
|
||||
|
### Minimal (no body) |
||||
|
|
||||
|
```text |
||||
|
|
||||
|
<type>(<scope>): <summary> |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### Standard (with body & footer) |
||||
|
|
||||
|
```text |
||||
|
|
||||
|
<type>(<scope>)<!>: <summary> |
||||
|
|
||||
|
<why-this-change?> |
||||
|
<what-it-does?> |
||||
|
<risks-or-follow-ups?> |
||||
|
|
||||
|
Closes #<id> |
||||
|
BREAKING CHANGE: <impact + migration> |
||||
|
Co-authored-by: <Name> <email> |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## Type Descriptions |
||||
|
|
||||
|
### feat |
||||
|
|
||||
|
New feature for the user |
||||
|
|
||||
|
### fix |
||||
|
|
||||
|
Bug fix for the user |
||||
|
|
||||
|
### docs |
||||
|
|
||||
|
Documentation only changes |
||||
|
|
||||
|
### style |
||||
|
|
||||
|
Changes that do not affect the meaning of the code |
||||
|
|
||||
|
### refactor |
||||
|
|
||||
|
Code change that neither fixes a bug nor adds a feature |
||||
|
|
||||
|
### perf |
||||
|
|
||||
|
Code change that improves performance |
||||
|
|
||||
|
### test |
||||
|
|
||||
|
Adding missing tests or correcting existing tests |
||||
|
|
||||
|
### build |
||||
|
|
||||
|
Changes that affect the build system or external dependencies |
||||
|
|
||||
|
### ci |
||||
|
|
||||
|
Changes to CI configuration files and scripts |
||||
|
|
||||
|
### chore |
||||
|
|
||||
|
Other changes that don't modify src or test files |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: |
||||
|
|
||||
|
- `.cursor/rules/workflow/version_control.mdc` for |
||||
|
|
||||
|
core version control principles |
||||
|
|
||||
|
- `.cursor/rules/workflow/version_sync.mdc` for version synchronization details |
||||
|
|
||||
|
**Status**: Active commit message guidelines |
||||
|
**Priority**: High |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: version_control.mdc |
||||
|
**Stakeholders**: Development team, AI assistants |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Creating Commits |
||||
|
|
||||
|
- [ ] **Change Review**: Review all changes to be committed |
||||
|
- [ ] **Scope Assessment**: Determine if changes belong in single or multiple commits |
||||
|
- [ ] **Message Planning**: Plan clear, descriptive commit message |
||||
|
- [ ] **Convention Check**: Review commit message format requirements |
||||
|
|
||||
|
### During Commit Creation |
||||
|
|
||||
|
- [ ] **Type Selection**: Choose appropriate commit type (feat, fix, docs, etc.) |
||||
|
- [ ] **Message Writing**: Write clear, concise commit message |
||||
|
- [ ] **Body Content**: Add detailed description if needed |
||||
|
- [ ] **Breaking Changes**: Document breaking changes with `!` and migration notes |
||||
|
|
||||
|
### After Commit Creation |
||||
|
|
||||
|
- [ ] **Message Review**: Verify commit message follows conventions |
||||
|
- [ ] **Change Validation**: Confirm all intended changes are included |
||||
|
- [ ] **Documentation**: Update any related documentation |
||||
|
- [ ] **Team Communication**: Communicate significant changes to team |
||||
@ -0,0 +1,176 @@ |
|||||
|
# Version Synchronization and Changelog Management |
||||
|
|
||||
|
> **Agent role**: Reference this file for version synchronization |
||||
|
> requirements and changelog management. |
||||
|
|
||||
|
## Version Sync Checklist (Before Commit) |
||||
|
|
||||
|
- [ ] `package.json` version matches latest `CHANGELOG.md` entry |
||||
|
- [ ] New version follows semantic versioning |
||||
|
(MAJOR.MINOR.PATCH[-PRERELEASE]) |
||||
|
- [ ] Changelog entry includes all significant changes since last version |
||||
|
- [ ] Version bump commit message follows `build(version): bump to X.Y.Z` |
||||
|
format |
||||
|
- [ ] Breaking changes properly documented with migration notes |
||||
|
- [ ] Alert developer in chat message that version has been updated |
||||
|
|
||||
|
## Version Change Detection |
||||
|
|
||||
|
- **Check for version changes** in staged/unstaged `package.json` |
||||
|
- **Alert developer** if version changed but changelog not updated |
||||
|
- **Suggest changelog update** with proper format and content |
||||
|
- **Validate semantic versioning** compliance |
||||
|
|
||||
|
## Implementation Notes |
||||
|
|
||||
|
### Version Detection |
||||
|
|
||||
|
- Compare `package.json` version field with latest changelog entry |
||||
|
- Use semantic versioning validation |
||||
|
- Check for pre-release version consistency |
||||
|
|
||||
|
### Semantic Validation |
||||
|
|
||||
|
- Ensure version follows `X.Y.Z[-PRERELEASE]` format |
||||
|
- Validate major.minor.patch components |
||||
|
- Handle pre-release suffixes (beta, alpha, rc) |
||||
|
|
||||
|
### Changelog Format |
||||
|
|
||||
|
- Follow [Keep a Changelog](https://keepachangelog.com/) standards |
||||
|
- Use consistent section headers |
||||
|
- Include breaking change notes |
||||
|
- Maintain chronological order |
||||
|
|
||||
|
### Breaking Changes |
||||
|
|
||||
|
- Use `!` in commit message |
||||
|
- Include `BREAKING CHANGE:` in changelog |
||||
|
- Provide migration notes |
||||
|
- Document impact clearly |
||||
|
|
||||
|
### Pre-release Versions |
||||
|
|
||||
|
- Include beta/alpha/rc suffixes consistently |
||||
|
- Update both `package.json` and changelog |
||||
|
- Maintain version number alignment |
||||
|
- Document pre-release status |
||||
|
|
||||
|
## Changelog Sections |
||||
|
|
||||
|
### Added |
||||
|
|
||||
|
- New features |
||||
|
- New capabilities |
||||
|
- New dependencies |
||||
|
|
||||
|
### Changed |
||||
|
|
||||
|
- Changes in existing functionality |
||||
|
- API changes |
||||
|
- Performance improvements |
||||
|
|
||||
|
### Deprecated |
||||
|
|
||||
|
- Soon-to-be removed features |
||||
|
- Migration paths |
||||
|
- Sunset timelines |
||||
|
|
||||
|
### Removed |
||||
|
|
||||
|
- Removed features |
||||
|
- Breaking changes |
||||
|
- Deprecated items |
||||
|
|
||||
|
### Fixed |
||||
|
|
||||
|
- Bug fixes |
||||
|
- Security patches |
||||
|
- Performance fixes |
||||
|
|
||||
|
### Security |
||||
|
|
||||
|
- Security vulnerabilities |
||||
|
- CVE references |
||||
|
- Mitigation steps |
||||
|
|
||||
|
## Version Bump Guidelines |
||||
|
|
||||
|
### Patch (X.Y.Z+1) |
||||
|
|
||||
|
- Bug fixes |
||||
|
- Documentation updates |
||||
|
- Minor improvements |
||||
|
|
||||
|
### Minor (X.Y+1.Z) |
||||
|
|
||||
|
- New features |
||||
|
- Backward-compatible changes |
||||
|
- Significant improvements |
||||
|
|
||||
|
### Major (X+1.Y.Z) |
||||
|
|
||||
|
- Breaking changes |
||||
|
- Major API changes |
||||
|
- Incompatible changes |
||||
|
|
||||
|
## Pre-release Guidelines |
||||
|
|
||||
|
### Beta Versions |
||||
|
|
||||
|
- Feature complete |
||||
|
- Testing phase |
||||
|
- API stable |
||||
|
|
||||
|
### Alpha Versions |
||||
|
|
||||
|
- Early development |
||||
|
- API may change |
||||
|
- Limited testing |
||||
|
|
||||
|
### Release Candidates |
||||
|
|
||||
|
- Final testing |
||||
|
- API frozen |
||||
|
- Production ready |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: |
||||
|
|
||||
|
- `.cursor/rules/workflow/version_control.mdc` for core version |
||||
|
control principles |
||||
|
- `.cursor/rules/workflow/commit_messages.mdc` for commit message |
||||
|
format |
||||
|
|
||||
|
**Status**: Active version synchronization guide |
||||
|
**Priority**: High |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: version_control.mdc |
||||
|
**Stakeholders**: Development team, Release team |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Version Changes |
||||
|
|
||||
|
- [ ] **Version Review**: Check current version in `package.json` and `CHANGELOG.md` |
||||
|
- [ ] **Change Assessment**: Identify what type of version bump is needed (patch/minor/major) |
||||
|
- [ ] **Breaking Changes**: Review if any changes are breaking and require |
||||
|
major version |
||||
|
- [ ] **Pre-release Status**: Determine if this should be a pre-release version |
||||
|
|
||||
|
### During Version Synchronization |
||||
|
|
||||
|
- [ ] **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]` format |
||||
|
- [ ] **Package Update**: Update `package.json` version field |
||||
|
- [ ] **Changelog Entry**: Add entry to `CHANGELOG.md` following Keep a Changelog |
||||
|
format |
||||
|
- [ ] **Breaking Changes**: Document breaking changes with migration notes |
||||
|
if applicable |
||||
|
|
||||
|
### After Version Changes |
||||
|
|
||||
|
- [ ] **Commit Format**: Use `build(version): bump to X.Y.Z` commit message format |
||||
|
- [ ] **Developer Alert**: Alert developer that version has been updated |
||||
|
- [ ] **Validation**: Verify `package.json` and `CHANGELOG.md` are in sync |
||||
|
- [ ] **Pre-release Handling**: Ensure pre-release versions are consistently formatted |
||||
@ -1,142 +0,0 @@ |
|||||
name: Asset Validation & CI Safeguards |
|
||||
|
|
||||
on: |
|
||||
pull_request: |
|
||||
paths: |
|
||||
- 'resources/**' |
|
||||
- 'config/assets/**' |
|
||||
- 'capacitor-assets.config.json' |
|
||||
- 'capacitor.config.ts' |
|
||||
- 'capacitor.config.json' |
|
||||
push: |
|
||||
branches: [main, develop] |
|
||||
paths: |
|
||||
- 'resources/**' |
|
||||
- 'config/assets/**' |
|
||||
- 'capacitor-assets.config.json' |
|
||||
- 'capacitor.config.ts' |
|
||||
- 'capacitor.config.json' |
|
||||
|
|
||||
jobs: |
|
||||
asset-validation: |
|
||||
runs-on: ubuntu-latest |
|
||||
steps: |
|
||||
- name: Checkout code |
|
||||
uses: actions/checkout@v4 |
|
||||
|
|
||||
- name: Setup Node.js |
|
||||
uses: actions/setup-node@v4 |
|
||||
with: |
|
||||
node-version-file: '.nvmrc' |
|
||||
cache: 'npm' |
|
||||
|
|
||||
- name: Install dependencies |
|
||||
run: npm ci |
|
||||
|
|
||||
- name: Validate asset configuration |
|
||||
run: npm run assets:validate |
|
||||
|
|
||||
- name: Check for committed platform assets (Android) |
|
||||
run: | |
|
||||
if git ls-files -z android/app/src/main/res | grep -E '(AppIcon.*\.png|Splash.*\.png|mipmap-.*/ic_launcher.*\.png)' > /dev/null; then |
|
||||
echo "❌ Android platform assets found in VCS - these should be generated at build-time" |
|
||||
git ls-files -z android/app/src/main/res | grep -E '(AppIcon.*\.png|Splash.*\.png|mipmap-.*/ic_launcher.*\.png)' |
|
||||
exit 1 |
|
||||
fi |
|
||||
echo "✅ No Android platform assets committed" |
|
||||
|
|
||||
- name: Check for committed platform assets (iOS) |
|
||||
run: | |
|
||||
if git ls-files -z ios/App/App/Assets.xcassets | grep -E '(AppIcon.*\.png|Splash.*\.png)' > /dev/null; then |
|
||||
echo "❌ iOS platform assets found in VCS - these should be generated at build-time" |
|
||||
git ls-files -z ios/App/App/Assets.xcassets | grep -E '(AppIcon.*\.png|Splash.*\.png)' |
|
||||
exit 1 |
|
||||
fi |
|
||||
echo "✅ No iOS platform assets committed" |
|
||||
|
|
||||
- name: Test asset generation |
|
||||
run: | |
|
||||
echo "🧪 Testing asset generation workflow..." |
|
||||
npm run build:capacitor |
|
||||
npx cap sync |
|
||||
npx capacitor-assets generate --dry-run || npx capacitor-assets generate |
|
||||
echo "✅ Asset generation test completed" |
|
||||
|
|
||||
- name: Verify clean tree after build |
|
||||
run: | |
|
||||
if [ -n "$(git status --porcelain)" ]; then |
|
||||
echo "❌ Dirty tree after build - asset configs were modified" |
|
||||
git status |
|
||||
git diff |
|
||||
exit 1 |
|
||||
fi |
|
||||
echo "✅ Build completed with clean tree" |
|
||||
|
|
||||
schema-validation: |
|
||||
runs-on: ubuntu-latest |
|
||||
steps: |
|
||||
- name: Checkout code |
|
||||
uses: actions/checkout@v4 |
|
||||
|
|
||||
- name: Setup Node.js |
|
||||
uses: actions/setup-node@v4 |
|
||||
with: |
|
||||
node-version-file: '.nvmrc' |
|
||||
cache: 'npm' |
|
||||
|
|
||||
- name: Install dependencies |
|
||||
run: npm ci |
|
||||
|
|
||||
- name: Validate schema compliance |
|
||||
run: | |
|
||||
echo "🔍 Validating schema compliance..." |
|
||||
node -e " |
|
||||
const fs = require('fs'); |
|
||||
const config = JSON.parse(fs.readFileSync('capacitor-assets.config.json', 'utf8')); |
|
||||
const schema = JSON.parse(fs.readFileSync('config/assets/schema.json', 'utf8')); |
|
||||
|
|
||||
// Basic schema validation |
|
||||
if (!config.icon || !config.splash) { |
|
||||
throw new Error('Missing required sections: icon and splash'); |
|
||||
} |
|
||||
|
|
||||
if (!config.icon.source || !config.splash.source) { |
|
||||
throw new Error('Missing required source fields'); |
|
||||
} |
|
||||
|
|
||||
if (!/^resources\/.*\.(png|svg)$/.test(config.icon.source)) { |
|
||||
throw new Error('Icon source must be in resources/ directory'); |
|
||||
} |
|
||||
|
|
||||
if (!/^resources\/.*\.(png|svg)$/.test(config.splash.source)) { |
|
||||
throw new Error('Splash source must be in resources/ directory'); |
|
||||
} |
|
||||
|
|
||||
console.log('✅ Schema validation passed'); |
|
||||
" |
|
||||
|
|
||||
- name: Check source file existence |
|
||||
run: | |
|
||||
echo "📁 Checking source file existence..." |
|
||||
node -e " |
|
||||
const fs = require('fs'); |
|
||||
const config = JSON.parse(fs.readFileSync('capacitor-assets.config.json', 'utf8')); |
|
||||
|
|
||||
const requiredFiles = [ |
|
||||
config.icon.source, |
|
||||
config.splash.source |
|
||||
]; |
|
||||
|
|
||||
if (config.splash.darkSource) { |
|
||||
requiredFiles.push(config.splash.darkSource); |
|
||||
} |
|
||||
|
|
||||
const missingFiles = requiredFiles.filter(file => !fs.existsSync(file)); |
|
||||
|
|
||||
if (missingFiles.length > 0) { |
|
||||
console.error('❌ Missing source files:', missingFiles); |
|
||||
process.exit(1); |
|
||||
} |
|
||||
|
|
||||
console.log('✅ All source files exist'); |
|
||||
" |
|
||||
@ -1,27 +0,0 @@ |
|||||
name: Playwright Tests |
|
||||
on: |
|
||||
push: |
|
||||
branches: [ main, master ] |
|
||||
pull_request: |
|
||||
branches: [ main, master ] |
|
||||
jobs: |
|
||||
test: |
|
||||
timeout-minutes: 60 |
|
||||
runs-on: ubuntu-latest |
|
||||
steps: |
|
||||
- uses: actions/checkout@v4 |
|
||||
- uses: actions/setup-node@v4 |
|
||||
with: |
|
||||
node-version: lts/* |
|
||||
- name: Install dependencies |
|
||||
run: npm ci |
|
||||
- name: Install Playwright Browsers |
|
||||
run: npx playwright install --with-deps |
|
||||
- name: Run Playwright tests |
|
||||
run: npx playwright test |
|
||||
- uses: actions/upload-artifact@v4 |
|
||||
if: always() |
|
||||
with: |
|
||||
name: playwright-report |
|
||||
path: playwright-report/ |
|
||||
retention-days: 30 |
|
||||
@ -0,0 +1,40 @@ |
|||||
|
#!/usr/bin/env sh |
||||
|
# |
||||
|
# Husky Helper Script |
||||
|
# This file is sourced by all Husky hooks |
||||
|
# |
||||
|
if [ -z "$husky_skip_init" ]; then |
||||
|
debug () { |
||||
|
if [ "$HUSKY_DEBUG" = "1" ]; then |
||||
|
echo "husky (debug) - $1" |
||||
|
fi |
||||
|
} |
||||
|
|
||||
|
readonly hook_name="$(basename -- "$0")" |
||||
|
debug "starting $hook_name..." |
||||
|
|
||||
|
if [ "$HUSKY" = "0" ]; then |
||||
|
debug "HUSKY env variable is set to 0, skipping hook" |
||||
|
exit 0 |
||||
|
fi |
||||
|
|
||||
|
if [ -f ~/.huskyrc ]; then |
||||
|
debug "sourcing ~/.huskyrc" |
||||
|
. ~/.huskyrc |
||||
|
fi |
||||
|
|
||||
|
readonly husky_skip_init=1 |
||||
|
export husky_skip_init |
||||
|
sh -e "$0" "$@" |
||||
|
exitCode="$?" |
||||
|
|
||||
|
if [ $exitCode != 0 ]; then |
||||
|
echo "husky - $hook_name hook exited with code $exitCode (error)" |
||||
|
fi |
||||
|
|
||||
|
if [ $exitCode = 127 ]; then |
||||
|
echo "husky - command not found in PATH=$PATH" |
||||
|
fi |
||||
|
|
||||
|
exit $exitCode |
||||
|
fi |
||||
@ -0,0 +1,10 @@ |
|||||
|
#!/usr/bin/env bash |
||||
|
# |
||||
|
# Husky Commit Message Hook |
||||
|
# Validates commit message format using commitlint |
||||
|
# |
||||
|
. "$(dirname -- "$0")/_/husky.sh" |
||||
|
|
||||
|
# Run commitlint but don't fail the commit (|| true) |
||||
|
# This provides helpful feedback without blocking commits |
||||
|
npx commitlint --edit "$1" || true |
||||
@ -0,0 +1,33 @@ |
|||||
|
#!/usr/bin/env bash |
||||
|
# |
||||
|
# Husky Pre-commit Hook |
||||
|
# Runs lint-fix and Build Architecture Guard on staged files |
||||
|
# |
||||
|
. "$(dirname -- "$0")/_/husky.sh" |
||||
|
|
||||
|
echo "🔍 Running pre-commit hooks..." |
||||
|
|
||||
|
# Run lint-fix first |
||||
|
echo "📝 Running lint-fix..." |
||||
|
npm run lint-fix || { |
||||
|
echo |
||||
|
echo "❌ Linting failed. Please fix the issues and try again." |
||||
|
echo "💡 To bypass this check for emergency commits, use:" |
||||
|
echo " git commit --no-verify" |
||||
|
echo |
||||
|
exit 1 |
||||
|
} |
||||
|
|
||||
|
# Then run Build Architecture Guard |
||||
|
echo "🏗️ Running Build Architecture Guard..." |
||||
|
bash ./scripts/build-arch-guard.sh --staged || { |
||||
|
echo |
||||
|
echo "❌ Build Architecture Guard failed. Please fix the issues and try again." |
||||
|
echo "💡 To bypass this check for emergency commits, use:" |
||||
|
echo " git commit --no-verify" |
||||
|
echo |
||||
|
exit 1 |
||||
|
} |
||||
|
|
||||
|
echo "✅ All pre-commit checks passed!" |
||||
|
|
||||
@ -0,0 +1,27 @@ |
|||||
|
#!/usr/bin/env bash |
||||
|
# |
||||
|
# Husky Pre-push Hook |
||||
|
# Runs Build Architecture Guard to check commits being pushed |
||||
|
# |
||||
|
. "$(dirname -- "$0")/_/husky.sh" |
||||
|
|
||||
|
echo "🔍 Running Build Architecture Guard (pre-push)..." |
||||
|
|
||||
|
# Get the remote branch we're pushing to |
||||
|
REMOTE_BRANCH="origin/$(git rev-parse --abbrev-ref HEAD)" |
||||
|
|
||||
|
# Check if remote branch exists |
||||
|
if git show-ref --verify --quiet "refs/remotes/$REMOTE_BRANCH"; then |
||||
|
RANGE="$REMOTE_BRANCH...HEAD" |
||||
|
else |
||||
|
# If remote branch doesn't exist, check last commit |
||||
|
RANGE="HEAD~1..HEAD" |
||||
|
fi |
||||
|
|
||||
|
bash ./scripts/build-arch-guard.sh --range "$RANGE" || { |
||||
|
echo |
||||
|
echo "💡 To bypass this check for emergency pushes, use:" |
||||
|
echo " git push --no-verify" |
||||
|
echo |
||||
|
exit 1 |
||||
|
} |
||||
@ -0,0 +1,53 @@ |
|||||
|
{ |
||||
|
// Markdownlint configuration for TimeSafari .cursor/rules |
||||
|
"config": { |
||||
|
// Core formatting rules that can be auto-fixed |
||||
|
"MD013": { |
||||
|
"line_length": 80, |
||||
|
"code_blocks": false, |
||||
|
"tables": false, |
||||
|
"headings": false |
||||
|
}, |
||||
|
"MD012": true, // No multiple consecutive blank lines |
||||
|
"MD022": true, // Headings should be surrounded by blank lines |
||||
|
"MD031": true, // Fenced code blocks should be surrounded by blank lines |
||||
|
"MD032": true, // Lists should be surrounded by blank lines |
||||
|
"MD047": true, // Files should end with a single newline |
||||
|
"MD009": true, // No trailing spaces |
||||
|
"MD010": true, // No hard tabs |
||||
|
"MD004": { "style": "dash" }, // Consistent list markers |
||||
|
"MD029": { "style": "ordered" }, // Ordered list item prefix |
||||
|
|
||||
|
// Disable rules that conflict with existing content structure |
||||
|
"MD041": false, // First line heading requirement |
||||
|
"MD025": false, // Multiple top-level headings |
||||
|
"MD024": false, // Duplicate headings |
||||
|
"MD036": false, // Emphasis as headings |
||||
|
"MD003": false, // Heading style consistency |
||||
|
"MD040": false, // Fenced code language |
||||
|
"MD055": false, // Table pipe style |
||||
|
"MD056": false, // Table column count |
||||
|
"MD034": false, // Bare URLs |
||||
|
"MD023": false // Heading indentation |
||||
|
}, |
||||
|
|
||||
|
"globs": [ |
||||
|
".cursor/rules/**/*.mdc", |
||||
|
"*.md", |
||||
|
"*.markdown", |
||||
|
"scripts/**/*.md", |
||||
|
"src/**/*.md", |
||||
|
"test-playwright/**/*.md", |
||||
|
"resources/**/*.md", |
||||
|
"doc/**/*.md", |
||||
|
"ios/**/*.md", |
||||
|
"electron/**/*.md" |
||||
|
], |
||||
|
"ignores": [ |
||||
|
"node_modules/**", |
||||
|
".git/**", |
||||
|
"**/node_modules/**", |
||||
|
"**/dist/**", |
||||
|
"**/build/**" |
||||
|
] |
||||
|
} |
||||
@ -1 +1,27 @@ |
|||||
{"MD013": {"code_blocks": false}} |
{ |
||||
|
"MD013": { |
||||
|
"line_length": 80, |
||||
|
"code_blocks": false, |
||||
|
"tables": false, |
||||
|
"headings": false |
||||
|
}, |
||||
|
"MD012": true, |
||||
|
"MD022": true, |
||||
|
"MD031": true, |
||||
|
"MD032": true, |
||||
|
"MD047": true, |
||||
|
"MD009": true, |
||||
|
"MD010": true, |
||||
|
"MD004": { "style": "dash" }, |
||||
|
"MD029": { "style": "ordered" }, |
||||
|
"MD041": false, |
||||
|
"MD025": false, |
||||
|
"MD024": false, |
||||
|
"MD036": false, |
||||
|
"MD003": false, |
||||
|
"MD040": false, |
||||
|
"MD055": false, |
||||
|
"MD056": false, |
||||
|
"MD034": false, |
||||
|
"MD023": false |
||||
|
} |
||||
File diff suppressed because it is too large
@ -0,0 +1,82 @@ |
|||||
|
# Pull Request Template |
||||
|
|
||||
|
## Location |
||||
|
|
||||
|
The Build Architecture Guard PR template is located at: |
||||
|
|
||||
|
- **`pull_request_template.md`** (root directory) |
||||
|
|
||||
|
## Usage |
||||
|
|
||||
|
When creating a pull request in Gitea, this template will automatically populate the PR description with the required checklist. |
||||
|
|
||||
|
## Template Features |
||||
|
|
||||
|
### Change Level Classification |
||||
|
|
||||
|
- **L1**: Minor changes, documentation updates |
||||
|
- **L2**: Moderate changes, new features, environment changes |
||||
|
- **L3**: Major changes, architecture changes, new platforms |
||||
|
|
||||
|
### Required Fields for All Levels |
||||
|
|
||||
|
- Change level selection |
||||
|
- Scope and impact description |
||||
|
- Commands executed and their output |
||||
|
- Documentation updates (BUILDING.md) |
||||
|
- Rollback verification steps |
||||
|
|
||||
|
### Additional Requirements for L3 |
||||
|
|
||||
|
- **ADR link**: Must provide URL to Architectural Decision Record |
||||
|
- **Artifacts with SHA256**: Must list artifacts with cryptographic hashes |
||||
|
|
||||
|
## Integration |
||||
|
|
||||
|
This template works with: |
||||
|
|
||||
|
- **Gitea Actions**: `.gitea/workflows/build-guard.yml` |
||||
|
- **Client-side hooks**: `.husky/` pre-commit and pre-push hooks |
||||
|
- **Guard script**: `scripts/build-arch-guard.sh` |
||||
|
|
||||
|
## Example Usage |
||||
|
|
||||
|
```markdown |
||||
|
### Change Level |
||||
|
- [x] Level: **L2** |
||||
|
|
||||
|
**Why:** Adding new build script for Docker deployment |
||||
|
|
||||
|
### Scope & Impact |
||||
|
- [x] Files & platforms touched: scripts/build-docker.sh, |
||||
|
BUILDING.md |
||||
|
- [x] Risk triggers: Docker build process changes |
||||
|
- [x] Mitigations/validation done: Tested on local Docker environment |
||||
|
|
||||
|
### Commands Run |
||||
|
- [x] Web: `npm run build:web:docker` ✅ |
||||
|
- [x] Docker: `docker build -t test-image .` ✅ |
||||
|
|
||||
|
### Artifacts |
||||
|
- [x] Names + **sha256** of artifacts/installers: |
||||
|
|
||||
|
Artifacts: |
||||
|
```text |
||||
|
test-image.tar a1b2c3d4e5f6... |
||||
|
``` |
||||
|
|
||||
|
### Docs |
||||
|
- [x] **BUILDING.md** updated (sections): Docker deployment |
||||
|
- [x] Troubleshooting updated: Added Docker troubleshooting section |
||||
|
|
||||
|
### Rollback |
||||
|
- [x] Verified steps to restore previous behavior: |
||||
|
1. `git revert HEAD` |
||||
|
2. `docker rmi test-image` |
||||
|
3. Restore previous BUILDING.md |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**Note**: This template is enforced by the Build Architecture Guard |
||||
|
system. Complete all required fields to ensure your PR can be merged. |
||||
@ -0,0 +1,44 @@ |
|||||
|
package app.timesafari.safearea; |
||||
|
|
||||
|
import android.os.Build; |
||||
|
import android.view.WindowInsets; |
||||
|
import com.getcapacitor.JSObject; |
||||
|
import com.getcapacitor.Plugin; |
||||
|
import com.getcapacitor.PluginCall; |
||||
|
import com.getcapacitor.PluginMethod; |
||||
|
import com.getcapacitor.annotation.CapacitorPlugin; |
||||
|
|
||||
|
@CapacitorPlugin(name = "SafeArea") |
||||
|
public class SafeAreaPlugin extends Plugin { |
||||
|
|
||||
|
@PluginMethod |
||||
|
public void getSafeAreaInsets(PluginCall call) { |
||||
|
JSObject result = new JSObject(); |
||||
|
|
||||
|
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) { |
||||
|
WindowInsets insets = getActivity().getWindow().getDecorView().getRootWindowInsets(); |
||||
|
if (insets != null) { |
||||
|
int top = insets.getInsets(WindowInsets.Type.statusBars()).top; |
||||
|
int bottom = insets.getInsets(WindowInsets.Type.navigationBars()).bottom; |
||||
|
int left = insets.getInsets(WindowInsets.Type.systemBars()).left; |
||||
|
int right = insets.getInsets(WindowInsets.Type.systemBars()).right; |
||||
|
|
||||
|
result.put("top", top); |
||||
|
result.put("bottom", bottom); |
||||
|
result.put("left", left); |
||||
|
result.put("right", right); |
||||
|
|
||||
|
call.resolve(result); |
||||
|
return; |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
// Fallback values
|
||||
|
result.put("top", 0); |
||||
|
result.put("bottom", 0); |
||||
|
result.put("left", 0); |
||||
|
result.put("right", 0); |
||||
|
|
||||
|
call.resolve(result); |
||||
|
} |
||||
|
} |
||||
@ -0,0 +1,9 @@ |
|||||
|
module.exports = { |
||||
|
extends: ['@commitlint/config-conventional'], |
||||
|
rules: { |
||||
|
// Downgrade strict case rules to warnings (level 1) instead of errors (level 2)
|
||||
|
// This eliminates red error messages while maintaining helpful guidance
|
||||
|
'subject-case': [1, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']], |
||||
|
'subject-full-stop': [1, 'never', '.'], |
||||
|
} |
||||
|
}; |
||||
@ -0,0 +1,336 @@ |
|||||
|
# Build Architecture Guard - Husky Implementation |
||||
|
|
||||
|
## Overview |
||||
|
|
||||
|
The Build Architecture Guard protects your build system by enforcing |
||||
|
documentation requirements through **Git hooks**. When you modify |
||||
|
build-critical files, the system automatically blocks commits/pushes |
||||
|
until you update `BUILDING.md`. |
||||
|
|
||||
|
## 🎯 **Why Husky-Only?** |
||||
|
|
||||
|
**Advantages:** |
||||
|
|
||||
|
- ✅ **Immediate feedback** - Hooks run before commit/push |
||||
|
- ✅ **Works everywhere** - No server-side CI/CD required |
||||
|
- ✅ **Simple setup** - One tool, one configuration |
||||
|
- ✅ **Fast execution** - No network delays or server queues |
||||
|
- ✅ **Offline support** - Works without internet connection |
||||
|
|
||||
|
**Trade-offs:** |
||||
|
|
||||
|
- ⚠️ **Can be bypassed** - `git commit --no-verify` or `git push --no-verify` |
||||
|
- ⚠️ **Developer discipline** - Relies on team following the rules |
||||
|
|
||||
|
## 🏗️ **Architecture** |
||||
|
|
||||
|
```bash |
||||
|
Developer Workflow: |
||||
|
1. Modify build files (scripts/, vite.config.*, etc.) |
||||
|
2. Try to commit → Husky pre-commit hook runs |
||||
|
3. Guard script checks if BUILDING.md was updated |
||||
|
4. ✅ Commit succeeds if docs updated |
||||
|
5. ❌ Commit blocked if docs missing |
||||
|
``` |
||||
|
|
||||
|
## 🚀 **Quick Start** |
||||
|
|
||||
|
### 1. Install Dependencies |
||||
|
|
||||
|
```bash |
||||
|
npm install |
||||
|
npm run prepare # Sets up Husky hooks |
||||
|
``` |
||||
|
|
||||
|
### 2. Test the System |
||||
|
|
||||
|
```bash |
||||
|
# Modify a build file without updating BUILDING.md |
||||
|
echo "# test" >> scripts/test.sh |
||||
|
|
||||
|
# Try to commit (should be blocked) |
||||
|
git add scripts/test.sh |
||||
|
git commit -m "test: add build script" |
||||
|
# ❌ Hook blocks commit with helpful message |
||||
|
``` |
||||
|
|
||||
|
### 3. Fix and Retry |
||||
|
|
||||
|
```bash |
||||
|
# Update BUILDING.md with your changes |
||||
|
echo "## New Build Script" >> BUILDING.md |
||||
|
echo "Added test.sh for testing purposes" >> BUILDING.md |
||||
|
|
||||
|
# Now commit should succeed |
||||
|
git add BUILDING.md |
||||
|
git commit -m "feat: add test build script with docs" |
||||
|
# ✅ Commit succeeds |
||||
|
``` |
||||
|
|
||||
|
## 🔧 **How It Works** |
||||
|
|
||||
|
### Pre-commit Hook (`.husky/pre-commit`) |
||||
|
|
||||
|
- **When**: Every `git commit` |
||||
|
- **What**: Runs `./scripts/build-arch-guard.sh --staged` |
||||
|
- **Result**: Blocks commit if build files changed without BUILDING.md update |
||||
|
|
||||
|
### Pre-push Hook (`.husky/pre-push`) |
||||
|
|
||||
|
- **When**: Every `git push` |
||||
|
- **What**: Runs `./scripts/build-arch-guard.sh --range` |
||||
|
- **Result**: Blocks push if commits contain undocumented build changes |
||||
|
|
||||
|
### Guard Script (`scripts/build-arch-guard.sh`) |
||||
|
|
||||
|
- **Detects**: Changes to build-sensitive file patterns |
||||
|
- **Validates**: BUILDING.md was updated alongside changes |
||||
|
- **Reports**: Clear error messages with guidance |
||||
|
|
||||
|
## 📁 **Protected File Patterns** |
||||
|
|
||||
|
The guard script monitors these paths for changes: |
||||
|
|
||||
|
```text |
||||
|
Build Configuration: |
||||
|
├── vite.config.* # Vite configuration |
||||
|
├── capacitor.config.ts # Capacitor configuration |
||||
|
├── package.json # Package configuration |
||||
|
├── package-lock.json # Lock files |
||||
|
├── yarn.lock |
||||
|
└── pnpm-lock.yaml |
||||
|
|
||||
|
Build Scripts: |
||||
|
├── scripts/** # All build and automation scripts |
||||
|
├── electron/** # Electron build files |
||||
|
├── android/** # Android build configuration |
||||
|
├── ios/** # iOS build configuration |
||||
|
├── sw_scripts/** # Service worker scripts |
||||
|
└── sw_combine.js # Service worker combination |
||||
|
|
||||
|
Deployment: |
||||
|
├── Dockerfile # Docker configuration |
||||
|
└── docker/** # Docker services |
||||
|
``` |
||||
|
|
||||
|
## 🎭 **Usage Scenarios** |
||||
|
|
||||
|
### Scenario 1: Adding a New Build Script |
||||
|
|
||||
|
```bash |
||||
|
# ❌ This will be blocked |
||||
|
echo '#!/bin/bash' > scripts/new-build.sh |
||||
|
git add scripts/new-build.sh |
||||
|
git commit -m "feat: add new build script" |
||||
|
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated" |
||||
|
|
||||
|
# ✅ This will succeed |
||||
|
echo '#!/bin/bash' > scripts/new-build.sh |
||||
|
echo '## New Build Script' >> BUILDING.md |
||||
|
echo 'Added new-build.sh for feature X' >> BUILDING.md |
||||
|
git add scripts/new-build.sh BUILDING.md |
||||
|
git commit -m "feat: add new build script with docs" |
||||
|
# ✅ Commit succeeds |
||||
|
``` |
||||
|
|
||||
|
### Scenario 2: Updating Vite Configuration |
||||
|
|
||||
|
```bash |
||||
|
# ❌ This will be blocked |
||||
|
echo 'export default { newOption: true }' >> vite.config.ts |
||||
|
git add vite.config.ts |
||||
|
git commit -m "config: add new vite option" |
||||
|
# Hook blocks: "Build-sensitive files changed but BUILDING.md not updated" |
||||
|
|
||||
|
# ✅ This will succeed |
||||
|
echo 'export default { newOption: true }' >> vite.config.ts |
||||
|
echo '### New Vite Option' >> BUILDING.md |
||||
|
echo 'Added newOption for improved performance' >> BUILDING.md |
||||
|
git add vite.config.ts BUILDING.md |
||||
|
git commit -m "config: add new vite option with docs" |
||||
|
# ✅ Commit succeeds |
||||
|
``` |
||||
|
|
||||
|
## 🚨 **Emergency Bypass** |
||||
|
|
||||
|
**⚠️ Use sparingly and only for emergencies:** |
||||
|
|
||||
|
```bash |
||||
|
# Skip pre-commit hook |
||||
|
git commit -m "emergency: critical fix" --no-verify |
||||
|
|
||||
|
# Skip pre-push hook |
||||
|
git push --no-verify |
||||
|
|
||||
|
# Remember to update BUILDING.md later! |
||||
|
``` |
||||
|
|
||||
|
## 🔍 **Troubleshooting** |
||||
|
|
||||
|
### Hooks Not Running |
||||
|
|
||||
|
```bash |
||||
|
# Reinstall hooks |
||||
|
npm run prepare |
||||
|
|
||||
|
# Check hook files exist and are executable |
||||
|
ls -la .husky/ |
||||
|
chmod +x .husky/* |
||||
|
|
||||
|
# Verify Git hooks path |
||||
|
git config core.hooksPath |
||||
|
# Should show: .husky |
||||
|
``` |
||||
|
|
||||
|
### Guard Script Issues |
||||
|
|
||||
|
```bash |
||||
|
# Test guard script manually |
||||
|
./scripts/build-arch-guard.sh --help |
||||
|
|
||||
|
# Check script permissions |
||||
|
chmod +x scripts/build-arch-guard.sh |
||||
|
|
||||
|
# Test with specific files |
||||
|
./scripts/build-arch-guard.sh --staged |
||||
|
``` |
||||
|
|
||||
|
### False Positives |
||||
|
|
||||
|
```bash |
||||
|
# If guard blocks legitimate changes, check: |
||||
|
# 1. Are you modifying a protected file pattern? |
||||
|
# 2. Did you update BUILDING.md? |
||||
|
# 3. Is BUILDING.md staged for commit? |
||||
|
|
||||
|
# View what the guard sees |
||||
|
git diff --name-only --cached |
||||
|
``` |
||||
|
|
||||
|
## 📋 **Best Practices** |
||||
|
|
||||
|
### For Developers |
||||
|
|
||||
|
1. **Update BUILDING.md first** - Document changes before implementing |
||||
|
2. **Test locally** - Run `./scripts/build-arch-guard.sh --staged` before committing |
||||
|
3. **Use descriptive commits** - Include context about build changes |
||||
|
4. **Don't bypass lightly** - Only use `--no-verify` for true emergencies |
||||
|
|
||||
|
### For Teams |
||||
|
|
||||
|
1. **Document the system** - Ensure everyone understands the guard |
||||
|
2. **Review BUILDING.md updates** - Verify documentation quality |
||||
|
3. **Monitor bypass usage** - Track when hooks are skipped |
||||
|
4. **Regular audits** - Check that BUILDING.md stays current |
||||
|
|
||||
|
### For Maintainers |
||||
|
|
||||
|
1. **Update protected patterns** - Modify `scripts/build-arch-guard.sh` as needed |
||||
|
2. **Monitor effectiveness** - Track how often the guard catches issues |
||||
|
3. **Team training** - Help developers understand the system |
||||
|
4. **Continuous improvement** - Refine patterns and error messages |
||||
|
|
||||
|
## 🚨 **Troubleshooting** |
||||
|
|
||||
|
### Common Issues |
||||
|
|
||||
|
#### mapfile Command Not Found |
||||
|
|
||||
|
**Problem**: Pre-commit hook fails with `mapfile: command not found` |
||||
|
|
||||
|
**Cause**: The `mapfile` command is bash-specific and not available in all shell environments |
||||
|
|
||||
|
**Solution**: The script has been updated to use portable alternatives. If you encounter this issue: |
||||
|
|
||||
|
```bash |
||||
|
# Verify the script is executable |
||||
|
chmod +x scripts/build-arch-guard.sh |
||||
|
|
||||
|
# Test the script directly |
||||
|
./scripts/build-arch-guard.sh --help |
||||
|
|
||||
|
# Check your shell environment |
||||
|
echo $SHELL |
||||
|
bash --version |
||||
|
``` |
||||
|
|
||||
|
**Prevention**: Ensure your development environment uses bash and the script has proper permissions |
||||
|
|
||||
|
### False Positives |
||||
|
|
||||
|
```bash |
||||
|
# If guard blocks legitimate changes, check: |
||||
|
# 1. Are you modifying a protected file pattern? |
||||
|
# 2. Did you update BUILDING.md? |
||||
|
# 3. Is BUILDING.md staged for commit? |
||||
|
|
||||
|
# View what the guard sees |
||||
|
git diff --name-only --cached |
||||
|
``` |
||||
|
|
||||
|
## 🔄 **Customization** |
||||
|
|
||||
|
### Adding New Protected Paths |
||||
|
|
||||
|
Edit `scripts/build-arch-guard.sh`: |
||||
|
|
||||
|
```bash |
||||
|
SENSITIVE=( |
||||
|
# ... existing patterns ... |
||||
|
"new-pattern/**" # Add your new pattern |
||||
|
"*.config.js" # Add file extensions |
||||
|
) |
||||
|
``` |
||||
|
|
||||
|
### Modifying Error Messages |
||||
|
|
||||
|
Edit the guard script to customize: |
||||
|
|
||||
|
- Error message content |
||||
|
- File pattern matching |
||||
|
- Documentation requirements |
||||
|
- Bypass instructions |
||||
|
|
||||
|
### Adding New Validation Rules |
||||
|
|
||||
|
Extend the guard script to check for: |
||||
|
|
||||
|
- Specific file content patterns |
||||
|
- Required documentation sections |
||||
|
- Commit message formats |
||||
|
- Branch naming conventions |
||||
|
|
||||
|
## 📚 **Integration with PR Template** |
||||
|
|
||||
|
The `pull_request_template.md` works with this system by: |
||||
|
|
||||
|
- **Guiding developers** through required documentation |
||||
|
- **Ensuring consistency** across all build changes |
||||
|
- **Providing checklist** for comprehensive updates |
||||
|
- **Supporting L1/L2/L3** change classification |
||||
|
|
||||
|
## 🎯 **Success Metrics** |
||||
|
|
||||
|
Track the effectiveness of your Build Architecture Guard: |
||||
|
|
||||
|
- **Hook execution rate** - How often hooks run successfully |
||||
|
- **Bypass frequency** - How often `--no-verify` is used |
||||
|
- **Documentation quality** - BUILDING.md stays current |
||||
|
- **Build failures** - Fewer issues from undocumented changes |
||||
|
- **Team adoption** - Developers follow the process |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**Status**: Active protection system |
||||
|
**Architecture**: Client-side Git hooks only |
||||
|
**Dependencies**: Husky, Git, Bash |
||||
|
**Maintainer**: Development team |
||||
|
**Related**: `pull_request_template.md`, `scripts/build-arch-guard.sh` |
||||
|
|
||||
|
## 📝 **Changelog** |
||||
|
|
||||
|
### 2025-08-22 - Shell Compatibility Fix |
||||
|
- **Fixed**: Replaced `mapfile` command with portable alternative for cross-shell compatibility |
||||
|
- **Impact**: Resolves "mapfile: command not found" errors in pre-commit hooks |
||||
|
- **Files**: `scripts/build-arch-guard.sh` |
||||
|
- **Testing**: Script now works across different shell environments |
||||
@ -0,0 +1,238 @@ |
|||||
|
# Android Asset Validation System |
||||
|
|
||||
|
**Author**: Matthew Raymer |
||||
|
**Date**: 2025-08-22 |
||||
|
**Status**: 🎯 **ACTIVE** - Production Ready |
||||
|
|
||||
|
## Overview |
||||
|
|
||||
|
The Android Asset Validation System automatically detects and fixes missing Android resources before building, preventing common build failures related to missing splash screens and app icons. |
||||
|
|
||||
|
## Problem Solved |
||||
|
|
||||
|
Previously, Android builds would fail with errors like: |
||||
|
``` |
||||
|
error: resource drawable/splash (aka app.timesafari.app:drawable/splash) not found. |
||||
|
error: resource mipmap/ic_launcher (aka app.timesafari.app:mipmap/ic_launcher) not found. |
||||
|
``` |
||||
|
|
||||
|
This happened when: |
||||
|
- Source assets existed but weren't generated into Android resources |
||||
|
- Android resource directories were missing |
||||
|
- Asset generation tools weren't run before building |
||||
|
|
||||
|
## Solution |
||||
|
|
||||
|
### Enhanced Build Script Validation |
||||
|
|
||||
|
The `scripts/build-android.sh` script now includes comprehensive asset validation that: |
||||
|
|
||||
|
1. **Checks Source Assets**: Validates that required source files exist in `resources/` |
||||
|
2. **Checks Android Resources**: Verifies that generated Android resources exist |
||||
|
3. **Auto-Regenerates**: Automatically regenerates missing resources when detected |
||||
|
4. **Verifies Results**: Confirms that regeneration was successful |
||||
|
|
||||
|
### Validation Process |
||||
|
|
||||
|
```bash |
||||
|
# Validates and regenerates if needed |
||||
|
npm run assets:validate:android |
||||
|
|
||||
|
# Full build with validation |
||||
|
npm run build:android:studio |
||||
|
``` |
||||
|
|
||||
|
### What Gets Validated |
||||
|
|
||||
|
#### Source Assets (Required) |
||||
|
- `resources/icon.png` - App icon source |
||||
|
- `resources/splash.png` - Splash screen source |
||||
|
- `resources/splash_dark.png` - Dark mode splash source |
||||
|
|
||||
|
#### Android Resources (Generated) |
||||
|
- `android/app/src/main/res/drawable/splash.png` - Splash screen drawable |
||||
|
- `android/app/src/main/res/mipmap-*/ic_launcher.png` - App icons for all densities |
||||
|
- `android/app/src/main/res/mipmap-*/ic_launcher_round.png` - Round app icons for all densities |
||||
|
|
||||
|
### Density Levels Checked |
||||
|
- `mipmap-mdpi` (1x) |
||||
|
- `mipmap-hdpi` (1.5x) |
||||
|
- `mipmap-xhdpi` (2x) |
||||
|
- `mipmap-xxhdpi` (3x) |
||||
|
- `mipmap-xxxhdpi` (4x) |
||||
|
|
||||
|
## Usage |
||||
|
|
||||
|
### Automatic Validation (Recommended) |
||||
|
The validation runs automatically during all Android builds: |
||||
|
|
||||
|
```bash |
||||
|
# Development build with validation |
||||
|
npm run build:android:studio |
||||
|
|
||||
|
# Production build with validation |
||||
|
npm run build:android:prod |
||||
|
|
||||
|
# Debug build with validation |
||||
|
npm run build:android:debug |
||||
|
``` |
||||
|
|
||||
|
### Manual Validation |
||||
|
Run validation only to check/fix assets: |
||||
|
|
||||
|
```bash |
||||
|
# Validate and regenerate if needed |
||||
|
npm run assets:validate:android |
||||
|
|
||||
|
# Alternative command |
||||
|
./scripts/build-android.sh --assets-only |
||||
|
``` |
||||
|
|
||||
|
### Validation Only (No Regeneration) |
||||
|
Check configuration without fixing: |
||||
|
|
||||
|
```bash |
||||
|
npm run assets:validate |
||||
|
``` |
||||
|
|
||||
|
## Error Handling |
||||
|
|
||||
|
### Missing Source Assets |
||||
|
If source assets are missing, the build fails with clear error messages: |
||||
|
|
||||
|
``` |
||||
|
[ERROR] Missing source assets: |
||||
|
[ERROR] - resources/icon.png |
||||
|
[ERROR] - resources/splash.png |
||||
|
[ERROR] Please ensure all required assets are present in the resources/ directory. |
||||
|
``` |
||||
|
|
||||
|
### Missing Generated Resources |
||||
|
If generated resources are missing, they're automatically regenerated: |
||||
|
|
||||
|
``` |
||||
|
[WARN] Missing Android resources detected: |
||||
|
[WARN] - drawable/splash.png |
||||
|
[WARN] - mipmap-mdpi/ic_launcher.png |
||||
|
[INFO] Regenerating Android assets... |
||||
|
[SUCCESS] Android assets regenerated successfully |
||||
|
``` |
||||
|
|
||||
|
### Generation Failure |
||||
|
If regeneration fails, helpful guidance is provided: |
||||
|
|
||||
|
``` |
||||
|
[ERROR] Failed to generate Android assets |
||||
|
[INFO] You may need to manually create the missing resources: |
||||
|
[INFO] - android/app/src/main/res/drawable/splash.png |
||||
|
[INFO] - android/app/src/main/res/mipmap-mdpi/ic_launcher.png |
||||
|
``` |
||||
|
|
||||
|
## Integration Points |
||||
|
|
||||
|
### Build Script Integration |
||||
|
The validation is integrated into the main build process: |
||||
|
|
||||
|
```bash |
||||
|
# In scripts/build-android.sh |
||||
|
validate_dependencies |
||||
|
validate_android_assets || { |
||||
|
log_error "Android asset validation failed. Please fix the issues above and try again." |
||||
|
exit 9 |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
### NPM Scripts |
||||
|
New npm scripts for asset management: |
||||
|
|
||||
|
```json |
||||
|
{ |
||||
|
"assets:validate": "npx tsx scripts/assets-validator.ts", |
||||
|
"assets:validate:android": "./scripts/build-android.sh --assets-only", |
||||
|
"assets:clean": "rimraf android/app/src/main/res/mipmap-* ios/App/App/Assets.xcassets/**/AppIcon*.png ios/App/App/Assets.xcassets/**/Splash*.png || true" |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
## Benefits |
||||
|
|
||||
|
### For Developers |
||||
|
- **No More Build Failures**: Automatic detection and fixing of missing resources |
||||
|
- **Faster Development**: No need to manually run asset generation tools |
||||
|
- **Clear Error Messages**: Helpful guidance when issues occur |
||||
|
- **Consistent Results**: Same validation on all development machines |
||||
|
|
||||
|
### For CI/CD |
||||
|
- **Reliable Builds**: Consistent asset validation across environments |
||||
|
- **Early Detection**: Catches issues before they reach production |
||||
|
- **Automated Fixes**: Self-healing builds when possible |
||||
|
|
||||
|
### For Project Maintenance |
||||
|
- **Reduced Support**: Fewer "build doesn't work" issues |
||||
|
- **Documentation**: Clear requirements for required assets |
||||
|
- **Standardization**: Consistent asset structure across the project |
||||
|
|
||||
|
## Troubleshooting |
||||
|
|
||||
|
### Common Issues |
||||
|
|
||||
|
#### "No assets found in the asset path" |
||||
|
This occurs when the `assets/` directory is empty. The validation system automatically copies source assets and regenerates them. |
||||
|
|
||||
|
#### "Failed to generate Android assets" |
||||
|
Check that: |
||||
|
- Source assets exist in `resources/` |
||||
|
- `@capacitor/assets` is installed |
||||
|
- You have write permissions to the Android directories |
||||
|
|
||||
|
#### "Asset generation completed but some resources are still missing" |
||||
|
This indicates a problem with the asset generation tool. Try: |
||||
|
1. Running `npm install` to ensure dependencies are up to date |
||||
|
2. Manually running `npx @capacitor/assets generate` |
||||
|
3. Checking the asset generation logs for specific errors |
||||
|
|
||||
|
### Manual Recovery |
||||
|
If automatic regeneration fails, you can manually create the missing resources: |
||||
|
|
||||
|
```bash |
||||
|
# Create missing directories |
||||
|
mkdir -p android/app/src/main/res/drawable |
||||
|
mkdir -p android/app/src/main/res/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi} |
||||
|
|
||||
|
# Copy source assets to assets directory |
||||
|
cp resources/icon.png assets/ |
||||
|
cp resources/splash.png assets/ |
||||
|
cp resources/splash_dark.png assets/ |
||||
|
|
||||
|
# Generate assets manually |
||||
|
npx @capacitor/assets generate |
||||
|
|
||||
|
# Clean up |
||||
|
rm assets/icon.png assets/splash.png assets/splash_dark.png |
||||
|
``` |
||||
|
|
||||
|
## Future Enhancements |
||||
|
|
||||
|
### Planned Improvements |
||||
|
- **iOS Asset Validation**: Extend validation to iOS assets |
||||
|
- **Asset Quality Checks**: Validate image dimensions and formats |
||||
|
- **Performance Optimization**: Cache validation results |
||||
|
- **CI/CD Integration**: Add validation to GitHub Actions |
||||
|
|
||||
|
### Configuration Options |
||||
|
- **Custom Asset Paths**: Support for different asset directory structures |
||||
|
- **Validation Rules**: Configurable validation requirements |
||||
|
- **Skip Options**: Ability to skip validation for specific scenarios |
||||
|
|
||||
|
## References |
||||
|
|
||||
|
- [Capacitor Assets Documentation](https://github.com/ionic-team/capacitor-assets) |
||||
|
- [Android Resource System](https://developer.android.com/guide/topics/resources/providing-resources) |
||||
|
- [Build Script Documentation](./build-android.sh) |
||||
|
- [Asset Configuration](./capacitor-assets.config.json) |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**Status**: Active validation system |
||||
|
**Priority**: High |
||||
|
**Maintainer**: Development team |
||||
|
**Next Review**: 2025-09-22 |
||||
@ -0,0 +1,272 @@ |
|||||
|
# Meta-Rule Usage Guide: How to Use Meta-Rules in Practice |
||||
|
|
||||
|
**Author**: Matthew Raymer |
||||
|
**Date**: 2025-08-21 |
||||
|
**Status**: 🎯 **ACTIVE** - Comprehensive meta-rule usage guide |
||||
|
|
||||
|
## Overview |
||||
|
|
||||
|
This guide explains how to use the TimeSafari meta-rule system in practice. |
||||
|
Meta-rules are high-level rule bundles that provide workflow-specific guidance |
||||
|
for different types of tasks. |
||||
|
|
||||
|
**Educational Goal**: Help developers understand when and how to apply |
||||
|
meta-rules to maximize their effectiveness and avoid common mistakes. |
||||
|
|
||||
|
## Why Meta-Rules Matter |
||||
|
|
||||
|
**Meta-rules solve the problem of rule overload** by bundling related rules |
||||
|
into logical workflows. Instead of manually selecting 10+ individual rules, |
||||
|
you apply 1-3 meta-rules that automatically include everything you need. |
||||
|
|
||||
|
### **Benefits of Using Meta-Rules** |
||||
|
|
||||
|
- **Faster Setup**: No need to manually select individual rules |
||||
|
- **Better Coverage**: Ensures you don't miss important rules |
||||
|
- **Workflow Consistency**: Standardized approaches across the team |
||||
|
- **Learning Efficiency**: Learn workflows, not individual rules |
||||
|
- **Quality Assurance**: Built-in validation and feedback mechanisms |
||||
|
|
||||
|
## Meta-Rule Selection Strategy |
||||
|
|
||||
|
### **Step 1: Always Start with Core Always-On** |
||||
|
|
||||
|
**Every single interaction** starts with: |
||||
|
``` |
||||
|
meta_core_always_on.mdc |
||||
|
``` |
||||
|
|
||||
|
This provides the foundation: human competence principles, time standards, |
||||
|
version control, and application context. |
||||
|
|
||||
|
### **Step 2: Identify Your Primary Task Type** |
||||
|
|
||||
|
Choose the meta-rule that matches your main objective: |
||||
|
|
||||
|
| **Task Type** | **Primary Meta-Rule** | **When to Use** | |
||||
|
|---------------|------------------------|------------------| |
||||
|
| **Research/Investigation** | `meta_research.mdc` | Bug diagnosis, feasibility research, code analysis | |
||||
|
| **Feature Planning** | `meta_feature_planning.mdc` | New feature design, requirements analysis | |
||||
|
| **Feature Implementation** | `meta_feature_implementation.mdc` | Building features, coding, testing | |
||||
|
| **Bug Diagnosis** | `meta_bug_diagnosis.mdc` | Investigating issues, root cause analysis | |
||||
|
| **Bug Fixing** | `meta_bug_fixing.mdc` | Implementing fixes, validation | |
||||
|
| **Documentation** | `meta_documentation.mdc` | Writing docs, creating guides, tutorials | |
||||
|
|
||||
|
### **Step 3: Add Context-Specific Meta-Rules (Optional)** |
||||
|
|
||||
|
For complex tasks, you might combine multiple meta-rules: |
||||
|
|
||||
|
``` |
||||
|
meta_core_always_on + meta_research + meta_bug_diagnosis |
||||
|
``` |
||||
|
|
||||
|
## Practical Usage Examples |
||||
|
|
||||
|
### **Example 1: Bug Investigation** |
||||
|
|
||||
|
**Scenario**: User reports that the contact list isn't loading properly |
||||
|
|
||||
|
**Meta-Rule Selection**: |
||||
|
``` |
||||
|
meta_core_always_on + meta_research + meta_bug_diagnosis |
||||
|
``` |
||||
|
|
||||
|
**What This Gives You**: |
||||
|
- **Core Always-On**: Human competence focus, time standards, context |
||||
|
- **Research**: Systematic investigation methodology, evidence collection |
||||
|
- **Bug Diagnosis**: Defect analysis framework, root cause identification |
||||
|
|
||||
|
**Workflow**: |
||||
|
1. Apply core always-on for foundation |
||||
|
2. Use research meta-rule for systematic investigation |
||||
|
3. Apply bug diagnosis for defect analysis |
||||
|
4. Follow the bundled workflow automatically |
||||
|
|
||||
|
### **Example 2: Feature Development** |
||||
|
|
||||
|
**Scenario**: Building a new contact search feature |
||||
|
|
||||
|
**Meta-Rule Selection**: |
||||
|
``` |
||||
|
meta_core_always_on + meta_feature_planning + meta_feature_implementation |
||||
|
``` |
||||
|
|
||||
|
**What This Gives You**: |
||||
|
- **Core Always-On**: Foundation principles and context |
||||
|
- **Feature Planning**: Requirements analysis, architecture planning |
||||
|
- **Feature Implementation**: Development workflow, testing strategy |
||||
|
|
||||
|
**Workflow**: |
||||
|
1. Start with core always-on |
||||
|
2. Use feature planning for design and requirements |
||||
|
3. Switch to feature implementation for coding and testing |
||||
|
|
||||
|
### **Example 3: Documentation Creation** |
||||
|
|
||||
|
**Scenario**: Writing a migration guide for the new database system |
||||
|
|
||||
|
**Meta-Rule Selection**: |
||||
|
``` |
||||
|
meta_core_always_on + meta_documentation |
||||
|
``` |
||||
|
|
||||
|
**What This Gives You**: |
||||
|
- **Core Always-On**: Foundation and context |
||||
|
- **Documentation**: Educational focus, templates, quality standards |
||||
|
|
||||
|
**Workflow**: |
||||
|
1. Apply core always-on for foundation |
||||
|
2. Use documentation meta-rule for educational content creation |
||||
|
3. Follow educational templates and quality standards |
||||
|
|
||||
|
## Meta-Rule Application Process |
||||
|
|
||||
|
### **1. Load the Meta-Rule** |
||||
|
|
||||
|
When you start a task, explicitly state which meta-rules you're applying: |
||||
|
|
||||
|
``` |
||||
|
"I'm applying meta_core_always_on + meta_research for this bug investigation." |
||||
|
``` |
||||
|
|
||||
|
### **2. Follow the Bundled Workflow** |
||||
|
|
||||
|
Each meta-rule provides a complete workflow. Follow it step-by-step: |
||||
|
|
||||
|
- **Research Meta-Rule**: Investigation → Evidence → Analysis → Conclusion |
||||
|
- **Feature Planning**: Requirements → Architecture → Strategy → Validation |
||||
|
- **Bug Diagnosis**: Problem → Evidence → Root Cause → Solution |
||||
|
|
||||
|
### **3. Use the Bundled Rules** |
||||
|
|
||||
|
Meta-rules automatically include all necessary sub-rules. You don't need to |
||||
|
manually select individual rules - they're already bundled. |
||||
|
|
||||
|
### **4. Validate Against Success Criteria** |
||||
|
|
||||
|
Each meta-rule includes success criteria. Use these to validate your work: |
||||
|
|
||||
|
- [ ] **Educational Quality**: Content increases human competence |
||||
|
- [ ] **Technical Quality**: All technical details are accurate |
||||
|
- [ ] **Workflow Completion**: All required steps completed |
||||
|
- [ ] **Quality Standards**: Meets defined quality criteria |
||||
|
|
||||
|
## Common Meta-Rule Combinations |
||||
|
|
||||
|
### **Research + Diagnosis** |
||||
|
``` |
||||
|
meta_core_always_on + meta_research + meta_bug_diagnosis |
||||
|
``` |
||||
|
**Use for**: Complex bug investigations requiring systematic analysis |
||||
|
|
||||
|
### **Planning + Implementation** |
||||
|
``` |
||||
|
meta_core_always_on + meta_feature_planning + meta_feature_implementation |
||||
|
``` |
||||
|
**Use for**: End-to-end feature development from concept to deployment |
||||
|
|
||||
|
### **Research + Planning** |
||||
|
``` |
||||
|
meta_core_always_on + meta_research + meta_feature_planning |
||||
|
``` |
||||
|
**Use for**: Feasibility research and solution design |
||||
|
|
||||
|
### **Documentation + Context** |
||||
|
``` |
||||
|
meta_core_always_on + meta_documentation + [context-specific] |
||||
|
``` |
||||
|
**Use for**: Creating comprehensive, educational documentation |
||||
|
|
||||
|
## Best Practices |
||||
|
|
||||
|
### **✅ Do These Things** |
||||
|
|
||||
|
- **Always start with core always-on** - it's the foundation |
||||
|
- **Choose the primary meta-rule** that matches your main task |
||||
|
- **Follow the bundled workflow** step-by-step |
||||
|
- **Use success criteria** to validate your work |
||||
|
- **Collect feedback** on meta-rule effectiveness |
||||
|
|
||||
|
### **❌ Avoid These Mistakes** |
||||
|
|
||||
|
- **Don't skip core always-on** - you'll lose the foundation |
||||
|
- **Don't apply too many meta-rules** - stick to 2-3 maximum |
||||
|
- **Don't ignore the bundled workflow** - follow it systematically |
||||
|
- **Don't forget validation** - use the success criteria |
||||
|
- **Don't skip feedback collection** - it improves the system |
||||
|
|
||||
|
## Troubleshooting Common Issues |
||||
|
|
||||
|
### **Problem**: Meta-rules seem to conflict |
||||
|
|
||||
|
**Solution**: Meta-rules are designed to work together. If you see conflicts, |
||||
|
you're probably applying too many. Stick to 2-3 meta-rules maximum. |
||||
|
|
||||
|
### **Problem**: I don't know which meta-rule to use |
||||
|
|
||||
|
**Solution**: Start with your primary task type. If you're investigating a bug, |
||||
|
use research + bug diagnosis. If you're building a feature, use feature |
||||
|
planning + implementation. |
||||
|
|
||||
|
### **Problem**: The meta-rule workflow seems too complex |
||||
|
|
||||
|
**Solution**: Meta-rules bundle complexity into manageable workflows. Follow |
||||
|
the steps one at a time. The complexity is already organized for you. |
||||
|
|
||||
|
### **Problem**: I'm not seeing the expected behavior |
||||
|
|
||||
|
**Solution**: Ensure you're following the meta-rule workflow step-by-step. |
||||
|
Meta-rules provide guidance, but you still need to execute the workflow. |
||||
|
|
||||
|
## Feedback and Improvement |
||||
|
|
||||
|
### **Rate Your Experience** |
||||
|
|
||||
|
After using a meta-rule, provide feedback: |
||||
|
|
||||
|
- **Effectiveness**: How well did the meta-rule work? (1-5 scale) |
||||
|
- **Time Saved**: How much time did it save you? |
||||
|
- **Quality Improvement**: Did it improve your work quality? |
||||
|
- **Recommendation**: Would you recommend it to others? |
||||
|
|
||||
|
### **Continuous Improvement** |
||||
|
|
||||
|
Meta-rules evolve based on feedback: |
||||
|
|
||||
|
- **Usage patterns** - How teams use the rules |
||||
|
- **Effectiveness ratings** - What works and what doesn't |
||||
|
- **Integration feedback** - How well rules work together |
||||
|
- **Quality metrics** - Impact on work quality |
||||
|
|
||||
|
## Quick Reference |
||||
|
|
||||
|
### **Meta-Rule Selection Matrix** |
||||
|
|
||||
|
| **Task** | **Primary** | **Secondary** | **Tertiary** | |
||||
|
|----------|-------------|---------------|---------------| |
||||
|
| **Bug Investigation** | `meta_research` | `meta_bug_diagnosis` | - | |
||||
|
| **Feature Development** | `meta_feature_planning` | `meta_feature_implementation` | - | |
||||
|
| **Documentation** | `meta_documentation` | - | - | |
||||
|
| **Complex Research** | `meta_research` | `meta_bug_diagnosis` | `meta_feature_planning` | |
||||
|
|
||||
|
### **Always Remember** |
||||
|
|
||||
|
1. **Start with core always-on** - foundation for everything |
||||
|
2. **Choose your primary meta-rule** - matches your main task |
||||
|
3. **Follow the bundled workflow** - step-by-step execution |
||||
|
4. **Validate against success criteria** - ensure quality |
||||
|
5. **Provide feedback** - help improve the system |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: |
||||
|
|
||||
|
- `.cursor/rules/meta_rule_architecture.md` for meta-rule structure overview |
||||
|
- `.cursor/rules/meta_core_always_on.mdc` for foundation rules |
||||
|
- `.cursor/rules/README.md` for complete rule organization |
||||
|
|
||||
|
**Status**: Active usage guide |
||||
|
**Priority**: High |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: All meta-rules |
||||
|
**Stakeholders**: Development team, Documentation team |
||||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue