78 changed files with 10916 additions and 2894 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,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 |
|||
Sqlite and will be deprecated in future versions. |
|||
**Status**: Legacy migration guidelines |
|||
**Priority**: Low |
|||
**Estimated Effort**: Ongoing reference |
|||
**Dependencies**: absurd-sql.mdc |
|||
**Stakeholders**: Database team, Development team |
|||
|
|||
All references in the codebase to Dexie apply only to migration from IndexedDb |
|||
to Sqlite and will be deprecated in future versions. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Legacy Dexie Work |
|||
|
|||
- [ ] **Migration Analysis**: Identify legacy Dexie code that needs migration |
|||
- [ ] **Target Planning**: Plan migration to Absurd SQL with IndexedDB backend |
|||
- [ ] **Backward Compatibility**: Plan to maintain existing functionality |
|||
- [ ] **Testing Strategy**: Plan testing approach for migration |
|||
|
|||
### During Legacy Dexie Migration |
|||
|
|||
- [ ] **No New Dexie**: Ensure no new Dexie code is introduced |
|||
- [ ] **Migration Implementation**: Implement migration to Absurd SQL |
|||
- [ ] **Functionality Preservation**: Maintain existing functionality during migration |
|||
- [ ] **Error Handling**: Implement proper error handling for migration |
|||
|
|||
### After Legacy Dexie Migration |
|||
|
|||
- [ ] **Functionality Testing**: Verify all functionality still works correctly |
|||
- [ ] **Performance Validation**: Ensure performance meets or exceeds legacy |
|||
- [ ] **Documentation Update**: Update database documentation |
|||
- [ ] **Legacy Cleanup**: Remove deprecated Dexie code |
|||
|
|||
@ -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,14 +1,37 @@ |
|||
--- |
|||
alwaysApply: true |
|||
alwaysApply: false |
|||
--- |
|||
# Directive for Documentation Generation |
|||
|
|||
1. Produce a **small, focused set of documents** rather than an overwhelming volume. |
|||
2. Ensure the content is **maintainable and worth preserving**, so that humans |
|||
are motivated to keep it up to date. |
|||
are motivated to keep it up to date. |
|||
3. Prioritize **educational value**: the documents must clearly explain the |
|||
workings of the system. |
|||
4. Avoid **shallow, generic, or filler explanations** often found in |
|||
AI-generated documentation. |
|||
workings of the system. |
|||
4. Avoid **shallow, generic, or filler explanations** often found in AI-generated |
|||
documentation. |
|||
5. Aim for **clarity, depth, and usefulness**, so readers gain genuine understanding. |
|||
6. Always check the local system date to determine current date. |
|||
|
|||
## Model Implementation Checklist |
|||
|
|||
### Before Documentation Creation |
|||
|
|||
- [ ] **Scope Definition**: Define what needs to be documented |
|||
- [ ] **Audience Analysis**: Identify target readers and their needs |
|||
- [ ] **Content Planning**: Plan focused, educational content structure |
|||
- [ ] **Maintenance Planning**: Ensure content will be worth preserving |
|||
|
|||
### During Documentation Creation |
|||
|
|||
- [ ] **Educational Focus**: Clearly explain how the system works |
|||
- [ ] **Depth and Clarity**: Provide genuine understanding, not surface explanations |
|||
- [ ] **Focused Content**: Keep documents small and focused on specific topics |
|||
- [ ] **Current Date**: Check local system date for time-sensitive content |
|||
|
|||
### After Documentation Creation |
|||
|
|||
- [ ] **Quality Review**: Ensure content is clear, deep, and useful |
|||
- [ ] **Maintainability Check**: Verify content motivates humans to keep it updated |
|||
- [ ] **Audience Validation**: Confirm content meets target reader needs |
|||
- [ ] **Integration**: Integrate with existing documentation structure |
|||
|
|||
@ -1,79 +0,0 @@ |
|||
--- |
|||
alwaysApply: true |
|||
--- |
|||
|
|||
# Markdown Automation System |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-08-20 |
|||
**Status**: 🎯 **ACTIVE** - Markdown formatting automation |
|||
|
|||
## Overview |
|||
|
|||
The Markdown Automation System ensures your markdown formatting standards are |
|||
followed **during content generation** by AI agents, not just applied after the |
|||
fact. |
|||
|
|||
## AI-First Approach |
|||
|
|||
### **Primary Method**: AI Agent Compliance |
|||
|
|||
- **AI agents follow markdown rules** while generating content |
|||
- **No post-generation fixes needed** - content is compliant from creation |
|||
- **Consistent formatting** across all generated documentation |
|||
|
|||
### **Secondary Method**: Automated Validation |
|||
|
|||
- **Pre-commit hooks** catch any remaining issues |
|||
- **GitHub Actions** validate formatting before merge |
|||
- **Manual tools** for bulk fixes when needed |
|||
|
|||
## How It Works |
|||
|
|||
### 1. **AI Agent Compliance** (Primary) |
|||
|
|||
- **When**: Every time AI generates markdown content |
|||
- **What**: AI follows markdown rules during generation |
|||
- **Result**: Content is properly formatted from creation |
|||
|
|||
### 2. **Pre-commit Hooks** (Backup) |
|||
|
|||
- **When**: Every time you commit |
|||
- **What**: Catches any remaining formatting issues |
|||
- **Result**: Clean, properly formatted markdown files |
|||
|
|||
### 3. **GitHub Actions** (Pre-merge) |
|||
|
|||
- **When**: Every pull request |
|||
- **What**: Validates markdown formatting across all files |
|||
- **Result**: Blocks merge if formatting issues exist |
|||
|
|||
## AI Agent Rules Integration |
|||
|
|||
The AI agent follows markdown rules defined in `.cursor/rules/docs/markdown.mdc`: |
|||
|
|||
- **alwaysApply: true** - Rules are enforced during generation |
|||
- **Line Length**: AI never generates lines > 80 characters |
|||
- **Blank Lines**: AI adds proper spacing around all elements |
|||
- **Structure**: AI uses established templates and patterns |
|||
|
|||
## Available Commands |
|||
|
|||
### NPM Scripts |
|||
|
|||
- **`npm run markdown:setup`** - Install the automation system |
|||
- **`npm run markdown:fix`** - Fix formatting in all markdown files |
|||
- **`npm run markdown:check`** - Validate formatting without fixing |
|||
|
|||
## 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 |
|||
|
|||
--- |
|||
|
|||
**Status**: Active automation system |
|||
**Priority**: High |
|||
**Maintainer**: Development team |
|||
**Next Review**: 2025-09-20 |
|||
@ -1,366 +0,0 @@ |
|||
--- |
|||
globs: ["*.md", "*.mdc"] |
|||
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. |
|||
|
|||
**⚠️ CRITICAL FOR AI AGENTS**: These rules must be followed DURING content |
|||
generation, not applied after the fact. Always generate markdown that complies |
|||
with these standards from the start. |
|||
|
|||
## 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 |
|||
|
|||
### **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 |
|||
|
|||
### **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 |
|||
|
|||
## 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 |
|||
``` |
|||
## 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 |
|||
@ -1,206 +0,0 @@ |
|||
--- |
|||
alwaysApply: true |
|||
inherits: base_context.mdc |
|||
--- |
|||
```json |
|||
{ |
|||
"coaching_level": "standard", |
|||
"socratic_max_questions": 2, |
|||
"verbosity": "concise", |
|||
"timebox_minutes": 10, |
|||
"format_enforcement": "strict" |
|||
} |
|||
``` |
|||
|
|||
# Harbor Pilot — Universal Directive for Human-Facing Technical Guides |
|||
|
|||
**Author**: System/Shared |
|||
**Date**: 2025-08-21 (UTC) |
|||
**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human Competence First* |
|||
|
|||
> **Alignment with Base Context** |
|||
> - **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. |
|||
|
|||
--- |
|||
|
|||
## Objective |
|||
Produce a **developer-grade, reproducible guide** for any technical topic that onboards a competent practitioner **without meta narration** and **with evidence-backed steps**. |
|||
|
|||
## Scope & Constraints |
|||
- **One Markdown document** as the deliverable. |
|||
- 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). |
|||
- Provide runnable examples where applicable: |
|||
- **APIs**: `curl` + one client library (e.g., `httpx` for Python). |
|||
- **CLIs**: literal command blocks and expected output snippets. |
|||
- **Code**: minimal, self-contained samples (language appropriate). |
|||
- Cite **evidence** for *Works/Doesn’t* items (timestamps, filenames, line numbers, IDs/status codes, or logs). |
|||
- If something is unknown, output `TODO:<missing>` — **never invent**. |
|||
|
|||
## Required Sections (extends Base Output Contract) |
|||
Follow this exact order **after** the Base Contract’s **Objective → Result → Use/Run** headers: |
|||
|
|||
1. **Context & Scope** |
|||
- Problem statement, audience, in/out-of-scope bullets. |
|||
2. **Artifacts & Links** |
|||
- Repos/PRs, design docs, datasets/HARs/pcaps, scripts/tools, dashboards. |
|||
3. **Environment & Preconditions** |
|||
- OS/runtime, versions/build IDs, services/endpoints/URLs, credentials/auth mode (describe acquisition, do not expose secrets). |
|||
4. **Architecture / Process Overview** |
|||
- Short prose + **one diagram** selected from the list above. |
|||
5. **Interfaces & Contracts (choose one)** |
|||
- **API-based**: Endpoint table (*Step, Method, Path/URL, Auth, Key Headers/Params, Sample Req/Resp ref*). |
|||
- **Data/Files**: I/O contract table (*Source, Format, Schema/Columns, Size, Validation rules*). |
|||
- **Systems/Hardware**: Interfaces table (*Port/Bus, Protocol, Voltage/Timing, Constraints*). |
|||
6. **Repro: End-to-End Procedure** |
|||
- Minimal copy-paste steps with code/commands and **expected outputs**. |
|||
7. **What Works (with Evidence)** |
|||
- Each item: **Time (UTC)** • **Artifact/Req IDs** • **Status/Result** • **Where to verify**. |
|||
8. **What Doesn’t (Evidence & Hypotheses)** |
|||
- Each failure: locus (file/endpoint/module), evidence snippet; short hypothesis and **next probe**. |
|||
9. **Risks, Limits, Assumptions** |
|||
- SLOs/limits, rate/size caps, security boundaries (CORS/CSRF/ACLs), retries/backoff/idempotency patterns. |
|||
10. **Next Steps (Owner • Exit Criteria • Target Date)** |
|||
- Actionable, assigned, and time-bound. |
|||
11. **References** |
|||
- Canonical docs, specs, tickets, prior analyses. |
|||
|
|||
> **Competence Hooks (per Base Context; keep lightweight):** |
|||
> - *Why this works* (≤3 bullets) — core invariants or guarantees. |
|||
> - *Common pitfalls* (≤3 bullets) — the traps we saw in evidence. |
|||
> - *Next skill unlock* (1 line) — the next capability to implement/learn. |
|||
> - *Teach-back* (1 line) — prompt the reader to restate the flow/architecture. |
|||
|
|||
> **Collaboration Hooks (per Base Context):** |
|||
> - Name reviewers for **Interfaces & Contracts** and the **diagram**. |
|||
> - Short **sign-off checklist** before merging/publishing the guide. |
|||
|
|||
## Do / Don’t (Base-aligned) |
|||
- **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**. |
|||
- **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. |
|||
|
|||
## Validation Checklist (self-check before returning) |
|||
- [ ] All Required Sections present and ordered. |
|||
- [ ] Diagram compiles (basic Mermaid syntax) and fits the problem. |
|||
- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for each endpoint. |
|||
- [ ] Repro section includes commands/code **and expected outputs**. |
|||
- [ ] Every Works/Doesn’t item has **UTC timestamp**, **status/result**, and **verifiable evidence**. |
|||
- [ ] Next Steps include **Owner**, **Exit Criteria**, **Target Date**. |
|||
- [ ] Unknowns are `TODO:<missing>` — no fabrication. |
|||
- [ ] Base **Output Contract** sections satisfied (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References). |
|||
|
|||
## Universal Template (fill-in) |
|||
```markdown |
|||
# <Title> — Working Notes (As of YYYY-MM-DDTHH:MMZ) |
|||
|
|||
## Objective |
|||
<one line> |
|||
|
|||
## Result |
|||
<link to the produced guide file or say “this document”> |
|||
|
|||
## Use/Run |
|||
<how to apply/test and where to run samples> |
|||
|
|||
## Context & Scope |
|||
- Audience: <role(s)> |
|||
- In scope: <bullets> |
|||
- Out of scope: <bullets> |
|||
|
|||
## Artifacts & Links |
|||
- Repo/PR: <link> |
|||
- Data/Logs: <paths or links> |
|||
- Scripts/Tools: <paths> |
|||
- Dashboards: <links> |
|||
|
|||
## Environment & Preconditions |
|||
- OS/Runtime: <details> |
|||
- Versions/Builds: <list> |
|||
- Services/Endpoints: <list> |
|||
- Auth mode: <Bearer/Session/Keys + how acquired> |
|||
|
|||
## Architecture / Process Overview |
|||
<short prose> |
|||
```mermaid |
|||
<one suitable diagram: sequenceDiagram | flowchart | stateDiagram | gantt | classDiagram> |
|||
``` |
|||
|
|||
## Interfaces & Contracts |
|||
### If API-based |
|||
| Step | Method | Path/URL | Auth | Key Headers/Params | Sample | |
|||
|---|---|---|---|---|---| |
|||
| <…> | <…> | <…> | <…> | <…> | below | |
|||
|
|||
### If Data/Files |
|||
| Source | Format | Schema/Columns | Size | Validation | |
|||
|---|---|---|---|---| |
|||
| <…> | <…> | <…> | <…> | <…> | |
|||
|
|||
### If Systems/Hardware |
|||
| Interface | Protocol | Timing/Voltage | Constraints | Notes | |
|||
|---|---|---|---|---| |
|||
| <…> | <…> | <…> | <…> | <…> | |
|||
|
|||
## Repro: End-to-End Procedure |
|||
```bash |
|||
# commands / curl examples (redacted where necessary) |
|||
``` |
|||
```python |
|||
# minimal client library example (language appropriate) |
|||
``` |
|||
> Expected output: <snippet/checks> |
|||
|
|||
## What Works (Evidence) |
|||
- ✅ <short statement> |
|||
- **Time**: <YYYY-MM-DDTHH:MMZ> |
|||
- **Evidence**: file/line/log or request id/status |
|||
- **Verify at**: <where> |
|||
|
|||
## What Doesn’t (Evidence & Hypotheses) |
|||
- ❌ <short failure> at `<component/endpoint/file>` |
|||
- **Time**: <YYYY-MM-DDTHH:MMZ> |
|||
- **Evidence**: <snippet/id/status> |
|||
- **Hypothesis**: <short> |
|||
- **Next probe**: <short> |
|||
|
|||
## Risks, Limits, Assumptions |
|||
<bullets: limits, security boundaries, retries/backoff, idempotency, SLOs> |
|||
|
|||
## Next Steps |
|||
| Owner | Task | Exit Criteria | Target Date (UTC) | |
|||
|---|---|---|---| |
|||
| <name> | <action> | <measurable outcome> | <YYYY-MM-DD> | |
|||
|
|||
## References |
|||
<links/titles> |
|||
|
|||
## Competence Hooks |
|||
- *Why this works*: <≤3 bullets> |
|||
- *Common pitfalls*: <≤3 bullets> |
|||
- *Next skill unlock*: <1 line> |
|||
- *Teach-back*: <1 line> |
|||
|
|||
## Collaboration Hooks |
|||
- Reviewers: <names/roles> |
|||
- Sign-off checklist: <≤5 checks> |
|||
|
|||
## Assumptions & Limits |
|||
<bullets> |
|||
|
|||
## Deferred for depth |
|||
<park deeper material here to respect timeboxing> |
|||
``` |
|||
|
|||
--- |
|||
|
|||
**Notes for Implementers:** |
|||
- Respect Base *Do-Not* (no filler, no invented facts, no censorship). |
|||
- Prefer clarity over completeness when timeboxed; capture unknowns explicitly. |
|||
- Apply historical comment management rules (see `.cursor/rules/historical_comment_management.mdc`) |
|||
- Apply realistic time estimation rules (see `.cursor/rules/realistic_time_estimation.mdc`) |
|||
@ -1,236 +0,0 @@ |
|||
--- |
|||
description: when comments are generated by the model |
|||
alwaysApply: false |
|||
--- |
|||
# Historical Comment Management — Harbor Pilot Directive |
|||
|
|||
> **Agent role**: When encountering historical comments about removed methods, deprecated patterns, or architectural changes, apply these guidelines to maintain code clarity and developer guidance. |
|||
|
|||
## 🎯 Purpose |
|||
|
|||
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 |
|||
|
|||
### Remove Historical Comments When: |
|||
- **Obsolete Information**: Comment describes functionality that no longer exists |
|||
- **No Action Required**: Comment doesn't help future developers make decisions |
|||
- **Outdated Context**: Comment refers to old patterns that are no longer relevant |
|||
- **Self-Evident**: The current code clearly shows the current approach |
|||
|
|||
### Transform Historical Comments When: |
|||
- **Architectural Context**: The change represents a significant pattern shift |
|||
- **Migration Guidance**: Future developers might need to understand the evolution |
|||
- **Decision Rationale**: The "why" behind the change is still relevant |
|||
- **Alternative Approaches**: The comment can guide future implementation choices |
|||
|
|||
## 🔄 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 |
|||
|
|||
## ✅ Best Practices |
|||
|
|||
### When Keeping Historical Context: |
|||
1. **Explain the "Why"**: Why was the change made? |
|||
2. **Describe the "What"**: What is the current approach? |
|||
3. **Provide Context**: When might this information be useful? |
|||
4. **Use Actionable Language**: Guide future decisions, not just document history |
|||
|
|||
### When Removing Historical Context: |
|||
1. **Verify Obsoleteness**: Ensure the information is truly outdated |
|||
2. **Check for Dependencies**: Ensure no other code references the old approach |
|||
3. **Update Related Docs**: If removing from code, consider adding to documentation |
|||
4. **Preserve in Git History**: The change is preserved in version control |
|||
|
|||
## 🔍 Implementation Checklist |
|||
|
|||
- [ ] Identify historical comments about removed/deprecated functionality |
|||
- [ ] Determine if comment provides actionable guidance |
|||
- [ ] Transform useful comments into migration notes or architectural context |
|||
- [ ] Remove comments that are purely historical without guidance value |
|||
- [ ] Ensure remaining comments explain current approach and rationale |
|||
- [ ] Update related documentation if significant context is removed |
|||
|
|||
## 📚 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 |
|||
``` |
|||
|
|||
## 🎯 Integration with Harbor Pilot |
|||
|
|||
This rule works in conjunction with: |
|||
- **Component Creation Ideals**: Maintains architectural consistency |
|||
- **Migration Patterns**: Documents evolution of patterns |
|||
- **Code Review Guidelines**: Ensures comments provide value |
|||
|
|||
## 📝 Version History |
|||
|
|||
### v1.0.0 (2025-08-21) |
|||
- Initial creation based on notification system cleanup |
|||
- Established decision framework for historical comment management |
|||
- Added transformation patterns and anti-patterns |
|||
- Integrated with existing Harbor Pilot architecture rules |
|||
# Historical Comment Management — Harbor Pilot Directive |
|||
|
|||
> **Agent role**: When encountering historical comments about removed methods, deprecated patterns, or architectural changes, apply these guidelines to maintain code clarity and developer guidance. |
|||
|
|||
## 🎯 Purpose |
|||
|
|||
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 |
|||
|
|||
### Remove Historical Comments When: |
|||
- **Obsolete Information**: Comment describes functionality that no longer exists |
|||
- **No Action Required**: Comment doesn't help future developers make decisions |
|||
- **Outdated Context**: Comment refers to old patterns that are no longer relevant |
|||
- **Self-Evident**: The current code clearly shows the current approach |
|||
|
|||
### Transform Historical Comments When: |
|||
- **Architectural Context**: The change represents a significant pattern shift |
|||
- **Migration Guidance**: Future developers might need to understand the evolution |
|||
- **Decision Rationale**: The "why" behind the change is still relevant |
|||
- **Alternative Approaches**: The comment can guide future implementation choices |
|||
|
|||
## 🔄 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 |
|||
|
|||
## ✅ Best Practices |
|||
|
|||
### When Keeping Historical Context: |
|||
1. **Explain the "Why"**: Why was the change made? |
|||
2. **Describe the "What"**: What is the current approach? |
|||
3. **Provide Context**: When might this information be useful? |
|||
4. **Use Actionable Language**: Guide future decisions, not just document history |
|||
|
|||
### When Removing Historical Context: |
|||
1. **Verify Obsoleteness**: Ensure the information is truly outdated |
|||
2. **Check for Dependencies**: Ensure no other code references the old approach |
|||
3. **Update Related Docs**: If removing from code, consider adding to documentation |
|||
4. **Preserve in Git History**: The change is preserved in version control |
|||
|
|||
## 🔍 Implementation Checklist |
|||
|
|||
- [ ] Identify historical comments about removed/deprecated functionality |
|||
- [ ] Determine if comment provides actionable guidance |
|||
- [ ] Transform useful comments into migration notes or architectural context |
|||
- [ ] Remove comments that are purely historical without guidance value |
|||
- [ ] Ensure remaining comments explain current approach and rationale |
|||
- [ ] Update related documentation if significant context is removed |
|||
|
|||
## 📚 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 |
|||
``` |
|||
|
|||
## 🎯 Integration with Harbor Pilot |
|||
|
|||
This rule works in conjunction with: |
|||
- **Component Creation Ideals**: Maintains architectural consistency |
|||
- **Migration Patterns**: Documents evolution of patterns |
|||
- **Code Review Guidelines**: Ensures comments provide value |
|||
|
|||
## 📝 Version History |
|||
|
|||
### v1.0.0 (2025-08-21) |
|||
- Initial creation based on notification system cleanup |
|||
- Established decision framework for historical comment management |
|||
- Added transformation patterns and anti-patterns |
|||
- Integrated with existing Harbor Pilot architecture rules |
|||
@ -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 |
|||
@ -1,348 +0,0 @@ |
|||
--- |
|||
description: when generating text that has project task work estimates |
|||
alwaysApply: false |
|||
--- |
|||
# No Time Estimates — Harbor Pilot Directive |
|||
|
|||
> **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 |
|||
|
|||
**DO NOT MAKE TIME ESTIMATES** |
|||
- **Never provide specific time estimates** - they are always wrong |
|||
- **Use phases and milestones** instead of days/weeks |
|||
- **Focus on complexity and dependencies** rather than time |
|||
- **Set expectations based on progress, not deadlines** |
|||
|
|||
## 📊 Planning Framework (Not Time Estimates) |
|||
|
|||
### **Complexity Categories** |
|||
- **Simple**: Text changes, styling updates, minor bug fixes |
|||
- **Medium**: New features, refactoring, component updates |
|||
- **Complex**: Architecture changes, integrations, cross-platform work |
|||
- **Unknown**: New technologies, APIs, or approaches |
|||
|
|||
### **Platform Complexity** |
|||
- **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 Complexity** |
|||
- **Basic**: Unit tests for new functionality |
|||
- **Comprehensive**: Integration tests, cross-platform testing |
|||
- **User acceptance**: User testing, feedback integration |
|||
|
|||
## 🔍 Planning Process (No Time Estimates) |
|||
|
|||
### **Step 1: Break Down the Work** |
|||
- Identify all subtasks and dependencies |
|||
- Group related work into logical phases |
|||
- Identify critical path and blockers |
|||
|
|||
### **Step 2: Define Phases and Milestones** |
|||
- **Phase 1**: Foundation work (basic fixes, core functionality) |
|||
- **Phase 2**: Enhancement work (new features, integrations) |
|||
- **Phase 3**: Polish work (testing, user experience, edge cases) |
|||
|
|||
### **Step 3: Identify Dependencies** |
|||
- **Technical dependencies**: What must be built first |
|||
- **Platform dependencies**: What works on which platforms |
|||
- **Testing dependencies**: What can be tested when |
|||
|
|||
### **Step 4: Set Progress Milestones** |
|||
- **Milestone 1**: Basic functionality working |
|||
- **Milestone 2**: All platforms supported |
|||
- **Milestone 3**: Fully tested and polished |
|||
|
|||
## 📋 Planning Checklist (No Time Estimates) |
|||
|
|||
- [ ] Work broken down into logical phases |
|||
- [ ] Dependencies identified and mapped |
|||
- [ ] Milestones defined with clear criteria |
|||
- [ ] Complexity levels assigned to each phase |
|||
- [ ] Platform requirements identified |
|||
- [ ] Testing strategy planned |
|||
- [ ] Risk factors identified |
|||
- [ ] Success criteria defined |
|||
|
|||
## 🎯 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 |
|||
|
|||
## 📝 Version History |
|||
|
|||
### v2.0.0 (2025-08-21) |
|||
- **Major Change**: Completely removed time estimation approach |
|||
- **New Focus**: Phases, milestones, and complexity-based planning |
|||
- **Eliminated**: All time multipliers, estimates, and calculations |
|||
- **Added**: Dependency mapping and progress milestone framework |
|||
|
|||
### v1.0.0 (2025-08-21) |
|||
- Initial creation based on user feedback about estimation accuracy |
|||
- ~~Established realistic estimation multipliers and process~~ |
|||
- ~~Added comprehensive estimation checklist and examples~~ |
|||
- Integrated with Harbor Pilot planning and risk management |
|||
|
|||
--- |
|||
|
|||
## 🚨 Remember |
|||
|
|||
**DO NOT MAKE TIME ESTIMATES. Use phases, milestones, and complexity instead. Focus on progress, not deadlines.** |
|||
|
|||
## 🚨 Remember |
|||
|
|||
**Your first estimate is wrong. Your second estimate is probably still wrong. Focus on progress, not deadlines.** |
|||
# No Time Estimates — Harbor Pilot Directive |
|||
|
|||
> **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 |
|||
|
|||
**DO NOT MAKE TIME ESTIMATES** |
|||
- **Never provide specific time estimates** - they are always wrong |
|||
- **Use phases and milestones** instead of days/weeks |
|||
- **Focus on complexity and dependencies** rather than time |
|||
- **Set expectations based on progress, not deadlines** |
|||
|
|||
## 📊 Planning Framework (Not Time Estimates) |
|||
|
|||
### **Complexity Categories** |
|||
- **Simple**: Text changes, styling updates, minor bug fixes |
|||
- **Medium**: New features, refactoring, component updates |
|||
- **Complex**: Architecture changes, integrations, cross-platform work |
|||
- **Unknown**: New technologies, APIs, or approaches |
|||
|
|||
### **Platform Complexity** |
|||
- **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 Complexity** |
|||
- **Basic**: Unit tests for new functionality |
|||
- **Comprehensive**: Integration tests, cross-platform testing |
|||
- **User acceptance**: User testing, feedback integration |
|||
|
|||
## 🔍 Planning Process (No Time Estimates) |
|||
|
|||
### **Step 1: Break Down the Work** |
|||
- Identify all subtasks and dependencies |
|||
- Group related work into logical phases |
|||
- Identify critical path and blockers |
|||
|
|||
### **Step 2: Define Phases and Milestones** |
|||
- **Phase 1**: Foundation work (basic fixes, core functionality) |
|||
- **Phase 2**: Enhancement work (new features, integrations) |
|||
- **Phase 3**: Polish work (testing, user experience, edge cases) |
|||
|
|||
### **Step 3: Identify Dependencies** |
|||
- **Technical dependencies**: What must be built first |
|||
- **Platform dependencies**: What works on which platforms |
|||
- **Testing dependencies**: What can be tested when |
|||
|
|||
### **Step 4: Set Progress Milestones** |
|||
- **Milestone 1**: Basic functionality working |
|||
- **Milestone 2**: All platforms supported |
|||
- **Milestone 3**: Fully tested and polished |
|||
|
|||
## 📋 Planning Checklist (No Time Estimates) |
|||
|
|||
- [ ] Work broken down into logical phases |
|||
- [ ] Dependencies identified and mapped |
|||
- [ ] Milestones defined with clear criteria |
|||
- [ ] Complexity levels assigned to each phase |
|||
- [ ] Platform requirements identified |
|||
- [ ] Testing strategy planned |
|||
- [ ] Risk factors identified |
|||
- [ ] Success criteria defined |
|||
|
|||
## 🎯 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 |
|||
|
|||
## 📝 Version History |
|||
|
|||
### v2.0.0 (2025-08-21) |
|||
- **Major Change**: Completely removed time estimation approach |
|||
- **New Focus**: Phases, milestones, and complexity-based planning |
|||
- **Eliminated**: All time multipliers, estimates, and calculations |
|||
- **Added**: Dependency mapping and progress milestone framework |
|||
|
|||
### v1.0.0 (2025-08-21) |
|||
- Initial creation based on user feedback about estimation accuracy |
|||
- ~~Established realistic estimation multipliers and process~~ |
|||
- ~~Added comprehensive estimation checklist and examples~~ |
|||
- Integrated with Harbor Pilot planning and risk management |
|||
|
|||
--- |
|||
|
|||
## 🚨 Remember |
|||
|
|||
**DO NOT MAKE TIME ESTIMATES. Use phases, milestones, and complexity instead. Focus on progress, not deadlines.** |
|||
|
|||
## 🚨 Remember |
|||
|
|||
**Your first estimate is wrong. Your second estimate is probably still wrong. Focus on progress, not deadlines.** |
|||
@ -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,15 +1,33 @@ |
|||
#!/usr/bin/env bash |
|||
# |
|||
# Husky Pre-commit Hook |
|||
# Runs Build Architecture Guard to check staged files |
|||
# Runs lint-fix and Build Architecture Guard on staged files |
|||
# |
|||
. "$(dirname -- "$0")/_/husky.sh" |
|||
|
|||
echo "🔍 Running Build Architecture Guard (pre-commit)..." |
|||
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,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 |
|||
} |
|||
@ -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 |
|||
File diff suppressed because it is too large
Loading…
Reference in new issue