Browse Source
- Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectoriesmaster
61 changed files with 9202 additions and 3105 deletions
@ -0,0 +1,146 @@ |
|||||
|
# .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 |
||||
|
|
||||
|
### **`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_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 |
||||
|
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 |
||||
|
|
||||
|
## 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,224 @@ |
|||||
|
```json |
||||
|
|
||||
|
{ |
||||
|
"coaching_level": "standard", |
||||
|
"socratic_max_questions": 2, |
||||
|
"verbosity": "concise", |
||||
|
"timebox_minutes": 10, |
||||
|
"format_enforcement": "strict" |
||||
|
} |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
# Harbor Pilot Universal — Technical Guide Standards |
||||
|
|
||||
|
> **Agent role**: When creating technical guides, reference documents, or |
||||
|
> implementation plans, apply these universal directives to ensure consistent |
||||
|
> quality and structure. |
||||
|
|
||||
|
## Purpose |
||||
|
|
||||
|
- **Purpose fit**: Prioritizes human competence and collaboration while |
||||
|
|
||||
|
delivering reproducible artifacts. |
||||
|
|
||||
|
- **Output Contract**: This directive **adds universal constraints** for any |
||||
|
|
||||
|
technical topic while **inheriting** the Base Context contract sections. |
||||
|
|
||||
|
- **Toggles honored**: Uses the same toggle semantics; defaults above can be |
||||
|
|
||||
|
overridden by the caller. |
||||
|
|
||||
|
## Core Directive |
||||
|
|
||||
|
Produce a **developer-grade, reproducible guide** for any technical topic |
||||
|
that onboards a competent practitioner **without meta narration** and **with |
||||
|
evidence-backed steps**. |
||||
|
|
||||
|
## Required Elements |
||||
|
|
||||
|
### 1. Time & Date Standards |
||||
|
|
||||
|
- Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid |
||||
|
|
||||
|
"today/yesterday". |
||||
|
|
||||
|
- Include at least **one diagram** (Mermaid preferred). Choose the most |
||||
|
|
||||
|
fitting type: |
||||
|
|
||||
|
- `sequenceDiagram` (protocols/flows), `flowchart`, `stateDiagram`, |
||||
|
|
||||
|
`gantt` (timelines), or `classDiagram` (schemas). |
||||
|
|
||||
|
### 2. Evidence Requirements |
||||
|
|
||||
|
- **Reproducible Steps**: Every claim must have copy-paste commands |
||||
|
|
||||
|
- **Verifiable Outputs**: Include expected results, status codes, or |
||||
|
|
||||
|
error messages |
||||
|
|
||||
|
- **Cite evidence** for *Works/Doesn't* items (timestamps, filenames, |
||||
|
|
||||
|
line numbers, IDs/status codes, or logs). |
||||
|
|
||||
|
## Required Sections |
||||
|
|
||||
|
Follow this exact order **after** the Base Contract's **Objective → Result |
||||
|
→ Use/Run** headers: |
||||
|
|
||||
|
1. **Artifacts & Links** - Repos/PRs, design docs, datasets/HARs/pcaps, |
||||
|
|
||||
|
scripts/tools, dashboards. |
||||
|
|
||||
|
2. **Environment & Preconditions** - OS/runtime, versions/build IDs, |
||||
|
|
||||
|
services/endpoints/URLs, credentials/auth mode. |
||||
|
|
||||
|
3. **Architecture / Process Overview** - Short prose + **one diagram** |
||||
|
|
||||
|
selected from the list above. |
||||
|
|
||||
|
4. **Interfaces & Contracts** - Choose one: API-based (endpoint table), |
||||
|
|
||||
|
Data/Files (I/O contract), or Systems/Hardware (interfaces). |
||||
|
|
||||
|
5. **Repro: End-to-End Procedure** - Minimal copy-paste steps with |
||||
|
|
||||
|
code/commands and **expected outputs**. |
||||
|
6. **What Works (with Evidence)** - Each item: **Time (UTC)** • |
||||
|
**Artifact/Req IDs** • **Status/Result** • **Where to verify**. |
||||
|
7. **What Doesn't (Evidence & Hypotheses)** - Each failure: locus, |
||||
|
evidence snippet; short hypothesis and **next probe**. |
||||
|
8. **Risks, Limits, Assumptions** - SLOs/limits, rate/size caps, |
||||
|
security boundaries, retries/backoff/idempotency patterns. |
||||
|
9. **Next Steps (Owner • Exit Criteria • Target Date)** - Actionable, |
||||
|
assigned, and time-bound. |
||||
|
|
||||
|
## Quality Standards |
||||
|
|
||||
|
### Do |
||||
|
|
||||
|
- **Do** quantify progress only against a defined scope with acceptance |
||||
|
|
||||
|
criteria. |
||||
|
|
||||
|
- **Do** include minimal sample payloads/headers or I/O schemas; redact |
||||
|
|
||||
|
sensitive values. |
||||
|
|
||||
|
- **Do** keep commentary lean; if timeboxed, move depth to **Deferred |
||||
|
|
||||
|
for depth**. |
||||
|
|
||||
|
- **Do** use specific, actionable language that guides implementation. |
||||
|
|
||||
|
### Don't |
||||
|
|
||||
|
- **Don't** use marketing language or meta narration ("Perfect!", |
||||
|
|
||||
|
"tool called", "new chat"). |
||||
|
|
||||
|
- **Don't** include IDE-specific chatter or internal rules unrelated to |
||||
|
|
||||
|
the task. |
||||
|
|
||||
|
- **Don't** assume reader knowledge; provide context for all technical |
||||
|
|
||||
|
decisions. |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Creating Technical Guides |
||||
|
|
||||
|
- [ ] **Scope Definition**: Clearly define problem, audience, and scope |
||||
|
- [ ] **Evidence Collection**: Gather specific timestamps, file references, and logs |
||||
|
- [ ] **Diagram Planning**: Plan appropriate diagram type for the technical process |
||||
|
- [ ] **Template Selection**: Choose relevant sections from required sections list |
||||
|
|
||||
|
### During Guide Creation |
||||
|
|
||||
|
- [ ] **Evidence Integration**: Include UTC timestamps and verifiable evidence |
||||
|
- [ ] **Diagram Creation**: Create Mermaid diagram that illustrates the process |
||||
|
- [ ] **Repro Steps**: Write copy-paste ready commands with expected outputs |
||||
|
- [ ] **Section Completion**: Fill in all required sections completely |
||||
|
|
||||
|
### After Guide Creation |
||||
|
|
||||
|
- [ ] **Validation**: Run through the validation checklist below |
||||
|
- [ ] **Evidence Review**: Verify all claims have supporting evidence |
||||
|
- [ ] **Repro Testing**: Test reproduction steps to ensure they work |
||||
|
- [ ] **Peer Review**: Share with technical leads for feedback |
||||
|
|
||||
|
## Validation Checklist |
||||
|
|
||||
|
Before publishing, verify: |
||||
|
|
||||
|
- [ ] **Diagram included** and properly formatted (Mermaid syntax valid) |
||||
|
- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for |
||||
|
each endpoint |
||||
|
- [ ] **Environment section** includes all required dependencies and |
||||
|
versions |
||||
|
- [ ] Every Works/Doesn't item has **UTC timestamp**, **status/result**, |
||||
|
and **verifiable evidence** |
||||
|
- [ ] **Repro steps** are copy-paste ready with expected outputs |
||||
|
- [ ] Base **Output Contract** sections satisfied |
||||
|
(Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References) |
||||
|
|
||||
|
## Integration Points |
||||
|
|
||||
|
### Base Context Integration |
||||
|
|
||||
|
- Apply historical comment management rules (see |
||||
|
|
||||
|
`.cursor/rules/development/historical_comment_management.mdc`) |
||||
|
|
||||
|
- Apply realistic time estimation rules (see |
||||
|
|
||||
|
`.cursor/rules/development/realistic_time_estimation.mdc`) |
||||
|
|
||||
|
### Competence Hooks |
||||
|
|
||||
|
- **Why this works**: Structured approach ensures completeness and |
||||
|
|
||||
|
reproducibility |
||||
|
|
||||
|
- **Common pitfalls**: Skipping evidence requirements, vague language |
||||
|
|
||||
|
- **Next skill unlock**: Practice creating Mermaid diagrams for different |
||||
|
|
||||
|
use cases |
||||
|
|
||||
|
- **Teach-back**: Explain how you would validate this guide's |
||||
|
|
||||
|
reproducibility |
||||
|
|
||||
|
### Collaboration Hooks |
||||
|
|
||||
|
- **Reviewers**: Technical leads, subject matter experts |
||||
|
|
||||
|
- **Stakeholders**: Development teams, DevOps, QA teams |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human |
||||
|
Competence First* |
||||
|
|
||||
|
**Priority**: Critical |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: base_context.mdc |
||||
|
**Stakeholders**: All AI interactions, Development teams |
||||
|
|
||||
|
## Example Diagram Template |
||||
|
|
||||
|
```mermaid |
||||
|
|
||||
|
<one suitable diagram: sequenceDiagram | flowchart | stateDiagram | gantt | |
||||
|
classDiagram> |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Note**: Replace the placeholder with an actual diagram that illustrates |
||||
|
the technical process, architecture, or workflow being documented. |
@ -0,0 +1,99 @@ |
|||||
|
|
||||
|
alwaysApply: false |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
# Minimalist Solution Principle (Cursor MDC) |
||||
|
|
||||
|
role: Engineering assistant optimizing for least-complex changes |
||||
|
focus: Deliver the smallest viable diff that fully resolves the current |
||||
|
bug/feature. Defer generalization unless justified with evidence. |
||||
|
language: Match repository languages and conventions |
||||
|
|
||||
|
## Rules |
||||
|
|
||||
|
1. **Default to the least complex solution.** Fix the problem directly |
||||
|
where it occurs; avoid new layers, indirection, or patterns unless |
||||
|
strictly necessary. |
||||
|
2. **Keep scope tight.** Implement only what is needed to satisfy the |
||||
|
acceptance criteria and tests for *this* issue. |
||||
|
3. **Avoid speculative abstractions.** Use the **Rule of Three**: |
||||
|
don't extract helpers/patterns until the third concrete usage proves |
||||
|
the shape. |
||||
|
4. **No drive-by refactors.** Do not rename, reorder, or reformat |
||||
|
unrelated code in the same change set. |
||||
|
5. **Minimize surface area.** Prefer local changes over cross-cutting |
||||
|
rewires; avoid new public APIs unless essential. |
||||
|
6. **Be dependency-frugal.** Do not add packages or services for |
||||
|
single, simple needs unless there's a compelling, documented reason. |
||||
|
7. **Targeted tests only.** Add the smallest set of tests that prove |
||||
|
the fix and guard against regression; don't rewrite suites. |
||||
|
8. **Document the "why enough."** Include a one-paragraph note |
||||
|
explaining why this minimal solution is sufficient *now*. |
||||
|
|
||||
|
## Future-Proofing Requires Evidence + Discussion |
||||
|
|
||||
|
Any added complexity "for the future" **must** include: |
||||
|
|
||||
|
- A referenced discussion/ADR (or issue link) summarizing the decision. |
||||
|
- **Substantial evidence**, e.g.: |
||||
|
- Recurring incidents or tickets that this prevents (list IDs). |
||||
|
- Benchmarks or profiling showing a real bottleneck. |
||||
|
- Concrete upcoming requirements with dates/owners, not hypotheticals. |
||||
|
- Risk assessment comparing maintenance cost vs. expected benefit. |
||||
|
- A clear trade-off table showing why minimal won't suffice. |
||||
|
|
||||
|
If this evidence is not available, **ship the minimal fix** and open a |
||||
|
follow-up discussion item. |
||||
|
|
||||
|
## PR / Change Checklist (enforced by reviewer + model) |
||||
|
|
||||
|
- [ ] Smallest diff that fully fixes the issue (attach `git diff --stat` |
||||
|
if useful). |
||||
|
- [ ] No unrelated refactors or formatting. |
||||
|
- [ ] No new dependencies, or justification + ADR link provided. |
||||
|
- [ ] Abstractions only if ≥3 call sites or strong evidence says |
||||
|
otherwise (cite). |
||||
|
- [ ] Targeted tests proving the fix/regression guard. |
||||
|
- [ ] Short "Why this is enough now" note in the PR description. |
||||
|
- [ ] Optional: "Future Work (non-blocking)" section listing deferred |
||||
|
ideas. |
||||
|
|
||||
|
## Assistant Output Contract |
||||
|
|
||||
|
When proposing a change, provide: |
||||
|
|
||||
|
1. **Minimal Plan**: 3–6 bullet steps scoped to the immediate fix. |
||||
|
2. **Patch Sketch**: Focused diffs/snippets touching only necessary |
||||
|
files. |
||||
|
3. **Risk & Rollback**: One paragraph each on risk, quick rollback, |
||||
|
and test points. |
||||
|
4. **(If proposing complexity)**: Link/inline ADR summary + evidence + |
||||
|
trade-offs; otherwise default to minimal. |
||||
|
|
||||
|
One paragraph each on risk, quick rollback, and test points. |
||||
|
5. **(If proposing complexity)**: Link/inline ADR summary + evidence + |
||||
|
trade-offs; otherwise default to minimal. |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Proposing Changes |
||||
|
|
||||
|
- [ ] **Problem Analysis**: Clearly understand the specific issue scope |
||||
|
- [ ] **Evidence Review**: Gather evidence that justifies the change |
||||
|
- [ ] **Complexity Assessment**: Evaluate if change requires added complexity |
||||
|
- [ ] **Alternative Research**: Consider simpler solutions first |
||||
|
|
||||
|
### During Change Design |
||||
|
|
||||
|
- [ ] **Minimal Scope**: Design solution that addresses only the current issue |
||||
|
- [ ] **Evidence Integration**: Include specific evidence for any complexity |
||||
|
- [ ] **Dependency Review**: Minimize new dependencies and packages |
||||
|
- [ ] **Testing Strategy**: Plan minimal tests that prove the fix |
||||
|
|
||||
|
### After Change Design |
||||
|
|
||||
|
- [ ] **Self-Review**: Verify solution follows minimalist principles |
||||
|
- [ ] **Evidence Validation**: Confirm all claims have supporting evidence |
||||
|
- [ ] **Complexity Justification**: Document why minimal approach suffices |
||||
|
- [ ] **Future Work Planning**: Identify deferred improvements for later |
@ -1,8 +1,62 @@ |
|||||
|
# Legacy Dexie Database — Migration Guidelines |
||||
|
|
||||
|
> **Agent role**: Reference this file when working with legacy Dexie |
||||
|
> database code or migration patterns. |
||||
|
|
||||
|
## Overview |
||||
|
|
||||
|
All references in the codebase to Dexie apply only to migration from |
||||
|
IndexedDb to Absurd SQL. Dexie is no longer used for new development. |
||||
|
|
||||
|
## Migration Status |
||||
|
|
||||
|
- **Legacy Code**: Existing Dexie implementations being migrated |
||||
|
- **Target**: Absurd SQL with IndexedDB backend |
||||
|
- **Timeline**: Gradual migration as features are updated |
||||
|
|
||||
|
## Key Principles |
||||
|
|
||||
|
- **No New Dexie**: All new database operations use Absurd SQL |
||||
|
- **Migration Path**: Legacy code should be migrated when updated |
||||
|
- **Backward Compatibility**: Maintain existing functionality during |
||||
|
migration |
||||
|
|
||||
|
## Integration Points |
||||
|
|
||||
|
- Apply these rules when updating database-related code |
||||
|
- Use during feature development and refactoring |
||||
|
- Include in database architecture decisions |
||||
|
|
||||
--- |
--- |
||||
globs: **/databaseUtil.ts,**/AccountViewView.vue,**/ContactsView.vue,**/DatabaseMigration.vue,**/NewIdentifierView.vue |
|
||||
alwaysApply: false |
|
||||
--- |
|
||||
# What to do with Dexie |
|
||||
|
|
||||
All references in the codebase to Dexie apply only to migration from IndexedDb to |
**Status**: Legacy migration guidelines |
||||
Sqlite and will be deprecated in future versions. |
**Priority**: Low |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: absurd-sql.mdc |
||||
|
**Stakeholders**: Database team, Development team |
||||
|
|
||||
|
All references in the codebase to Dexie apply only to migration from IndexedDb |
||||
|
to Sqlite and will be deprecated in future versions. |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Legacy Dexie Work |
||||
|
|
||||
|
- [ ] **Migration Analysis**: Identify legacy Dexie code that needs migration |
||||
|
- [ ] **Target Planning**: Plan migration to Absurd SQL with IndexedDB backend |
||||
|
- [ ] **Backward Compatibility**: Plan to maintain existing functionality |
||||
|
- [ ] **Testing Strategy**: Plan testing approach for migration |
||||
|
|
||||
|
### During Legacy Dexie Migration |
||||
|
|
||||
|
- [ ] **No New Dexie**: Ensure no new Dexie code is introduced |
||||
|
- [ ] **Migration Implementation**: Implement migration to Absurd SQL |
||||
|
- [ ] **Functionality Preservation**: Maintain existing functionality during migration |
||||
|
- [ ] **Error Handling**: Implement proper error handling for migration |
||||
|
|
||||
|
### After Legacy Dexie Migration |
||||
|
|
||||
|
- [ ] **Functionality Testing**: Verify all functionality still works correctly |
||||
|
- [ ] **Performance Validation**: Ensure performance meets or exceeds legacy |
||||
|
- [ ] **Documentation Update**: Update database documentation |
||||
|
- [ ] **Legacy Cleanup**: Remove deprecated Dexie code |
||||
|
@ -0,0 +1,177 @@ |
|||||
|
# Complexity Assessment — Evaluation Frameworks |
||||
|
|
||||
|
> **Agent role**: Reference this file for |
||||
|
complexity evaluation frameworks when assessing project complexity. |
||||
|
|
||||
|
## 📊 Complexity Assessment Framework |
||||
|
|
||||
|
### **Technical Complexity Factors** |
||||
|
|
||||
|
#### **Code Changes** |
||||
|
|
||||
|
- **Simple**: Text, styling, configuration updates |
||||
|
|
||||
|
- **Medium**: New components, refactoring existing code |
||||
|
|
||||
|
- **Complex**: Architecture changes, new patterns, integrations |
||||
|
|
||||
|
- **Unknown**: New technologies, APIs, or approaches |
||||
|
|
||||
|
#### **Platform Impact** |
||||
|
|
||||
|
- **Single platform**: Web-only or mobile-only changes |
||||
|
|
||||
|
- **Two platforms**: Web + mobile or web + desktop |
||||
|
|
||||
|
- **Three platforms**: Web + mobile + desktop |
||||
|
|
||||
|
- **Cross-platform consistency**: Ensuring behavior matches across all platforms |
||||
|
|
||||
|
#### **Testing Requirements** |
||||
|
|
||||
|
- **Basic**: Unit tests for new functionality |
||||
|
|
||||
|
- **Comprehensive**: Integration tests, cross-platform testing |
||||
|
|
||||
|
- **User acceptance**: User testing, feedback integration |
||||
|
|
||||
|
- **Performance**: Load testing, optimization validation |
||||
|
|
||||
|
### **Dependency Complexity** |
||||
|
|
||||
|
#### **Internal Dependencies** |
||||
|
|
||||
|
- **Low**: Self-contained changes, no other components affected |
||||
|
|
||||
|
- **Medium**: Changes affect related components or services |
||||
|
|
||||
|
- **High**: Changes affect core architecture or multiple systems |
||||
|
|
||||
|
- **Critical**: Changes affect data models or core business logic |
||||
|
|
||||
|
#### **External Dependencies** |
||||
|
|
||||
|
- **None**: No external services or APIs involved |
||||
|
|
||||
|
- **Low**: Simple API calls or service integrations |
||||
|
|
||||
|
- **Medium**: Complex integrations with external systems |
||||
|
|
||||
|
- **High**: Third-party platform dependencies or complex APIs |
||||
|
|
||||
|
#### **Infrastructure Dependencies** |
||||
|
|
||||
|
- **None**: No infrastructure changes required |
||||
|
|
||||
|
- **Low**: Configuration updates or environment changes |
||||
|
|
||||
|
- **Medium**: New services or infrastructure components |
||||
|
|
||||
|
- **High**: Platform migrations or major infrastructure changes |
||||
|
|
||||
|
## 🔍 Complexity Evaluation Process |
||||
|
|
||||
|
### **Step 1: Technical Assessment** |
||||
|
|
||||
|
1. **Identify scope of changes** - what files/components are affected |
||||
|
|
||||
|
2. **Assess platform impact** - which platforms need updates |
||||
|
|
||||
|
3. **Evaluate testing needs** - what testing is required |
||||
|
|
||||
|
4. **Consider performance impact** - will this affect performance |
||||
|
|
||||
|
### **Step 2: Dependency Mapping** |
||||
|
|
||||
|
1. **Map internal dependencies** - what other components are affected |
||||
|
|
||||
|
2. **Identify external dependencies** - what external services are involved |
||||
|
|
||||
|
3. **Assess infrastructure needs** - what infrastructure changes are required |
||||
|
|
||||
|
4. **Evaluate risk factors** - what could go wrong |
||||
|
|
||||
|
### **Step 3: Complexity Classification** |
||||
|
|
||||
|
1. **Assign complexity levels** to each factor |
||||
|
|
||||
|
2. **Identify highest complexity** areas that need attention |
||||
|
|
||||
|
3. **Plan mitigation strategies** for high-complexity areas |
||||
|
|
||||
|
4. **Set realistic expectations** based on complexity assessment |
||||
|
|
||||
|
## 📋 Complexity Assessment Checklist |
||||
|
|
||||
|
- [ ] Technical scope identified and mapped |
||||
|
|
||||
|
- [ ] Platform impact assessed across all targets |
||||
|
|
||||
|
- [ ] Testing requirements defined and planned |
||||
|
|
||||
|
- [ ] Internal dependencies mapped and evaluated |
||||
|
|
||||
|
- [ ] External dependencies identified and assessed |
||||
|
|
||||
|
- [ ] Infrastructure requirements evaluated |
||||
|
|
||||
|
- [ ] Risk factors identified and mitigation planned |
||||
|
|
||||
|
- [ ] Complexity levels assigned to all factors |
||||
|
|
||||
|
- [ ] Realistic expectations set based on assessment |
||||
|
|
||||
|
## 🎯 Complexity Reduction Strategies |
||||
|
|
||||
|
### **Scope Reduction** |
||||
|
|
||||
|
- Break large features into smaller, manageable pieces |
||||
|
|
||||
|
- Focus on core functionality first, add polish later |
||||
|
|
||||
|
- Consider phased rollout to reduce initial complexity |
||||
|
|
||||
|
### **Dependency Management** |
||||
|
|
||||
|
- Minimize external dependencies when possible |
||||
|
|
||||
|
- Use abstraction layers to isolate complex integrations |
||||
|
|
||||
|
- Plan for dependency failures and fallbacks |
||||
|
|
||||
|
### **Testing Strategy** |
||||
|
|
||||
|
- Start with basic testing and expand coverage |
||||
|
|
||||
|
- Use automated testing to reduce manual testing complexity |
||||
|
|
||||
|
- Plan for iterative testing and feedback cycles |
||||
|
|
||||
|
## **See also** |
||||
|
|
||||
|
- `.cursor/rules/development/realistic_time_estimation.mdc` for the core principles |
||||
|
|
||||
|
- `.cursor/rules/development/planning_examples.mdc` for planning examples |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Complexity Assessment |
||||
|
|
||||
|
- [ ] **Problem Scope**: Clearly define the problem to be assessed |
||||
|
- [ ] **Stakeholder Identification**: Identify all parties affected by complexity |
||||
|
- [ ] **Context Analysis**: Understand technical and business context |
||||
|
- [ ] **Assessment Criteria**: Define what factors determine complexity |
||||
|
|
||||
|
### During Complexity Assessment |
||||
|
|
||||
|
- [ ] **Technical Mapping**: Map technical scope and platform impact |
||||
|
- [ ] **Dependency Analysis**: Identify internal and external dependencies |
||||
|
- [ ] **Risk Evaluation**: Assess infrastructure needs and risk factors |
||||
|
- [ ] **Complexity Classification**: Assign complexity levels to all factors |
||||
|
|
||||
|
### After Complexity Assessment |
||||
|
|
||||
|
- [ ] **Mitigation Planning**: Plan strategies for high-complexity areas |
||||
|
- [ ] **Expectation Setting**: Set realistic expectations based on assessment |
||||
|
- [ ] **Documentation**: Document assessment process and findings |
||||
|
- [ ] **Stakeholder Communication**: Share results and recommendations |
@ -0,0 +1,177 @@ |
|||||
|
# Dependency Management — Best Practices |
||||
|
|
||||
|
> **Agent role**: Reference this file for dependency management strategies and |
||||
|
best practices when working with software projects. |
||||
|
|
||||
|
## Dependency Management Best Practices |
||||
|
|
||||
|
### Pre-build Validation |
||||
|
|
||||
|
- **Check Critical Dependencies**: |
||||
|
|
||||
|
Validate essential tools before executing build |
||||
|
scripts |
||||
|
|
||||
|
- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to |
||||
|
|
||||
|
avoid PATH issues |
||||
|
|
||||
|
- **Environment Consistency**: Ensure all team members have identical dependency |
||||
|
|
||||
|
versions |
||||
|
|
||||
|
### Common Pitfalls |
||||
|
|
||||
|
- **Missing npm install**: Team members cloning without running `npm install` |
||||
|
|
||||
|
- **PATH Issues**: Direct command execution vs. npm script execution differences |
||||
|
|
||||
|
- **Version Mismatches**: Different Node.js/npm versions across team members |
||||
|
|
||||
|
### Validation Strategies |
||||
|
|
||||
|
- **Dependency Check Scripts**: Implement pre-build validation for critical |
||||
|
|
||||
|
dependencies |
||||
|
|
||||
|
- **Environment Requirements**: |
||||
|
|
||||
|
Document and enforce minimum Node.js/npm versions |
||||
|
|
||||
|
- **Onboarding Checklist**: Standardize team member setup procedures |
||||
|
|
||||
|
### Error Messages and Guidance |
||||
|
|
||||
|
- **Specific Error Context**: |
||||
|
|
||||
|
Provide clear guidance when dependency issues occur |
||||
|
|
||||
|
- **Actionable Solutions**: Direct users to specific commands (`npm install`, |
||||
|
|
||||
|
`npm run check:dependencies`) |
||||
|
|
||||
|
- **Environment Diagnostics**: Implement comprehensive environment validation |
||||
|
|
||||
|
tools |
||||
|
|
||||
|
### Build Script Enhancements |
||||
|
|
||||
|
- **Early Validation**: Check dependencies before starting build processes |
||||
|
|
||||
|
- **Graceful Degradation**: Continue builds when possible but warn about issues |
||||
|
|
||||
|
- **Helpful Tips**: Remind users about dependency management best practices |
||||
|
|
||||
|
## Environment Setup Guidelines |
||||
|
|
||||
|
### Required Tools |
||||
|
|
||||
|
- **Node.js**: Minimum version requirements and LTS recommendations |
||||
|
|
||||
|
- **npm**: Version compatibility and global package management |
||||
|
|
||||
|
- **Platform-specific tools**: Android SDK, Xcode, etc. |
||||
|
|
||||
|
### Environment Variables |
||||
|
|
||||
|
- **NODE_ENV**: Development, testing, production environments |
||||
|
|
||||
|
- **PATH**: Ensure tools are accessible from command line |
||||
|
|
||||
|
- **Platform-specific**: Android SDK paths, Xcode command line tools |
||||
|
|
||||
|
### Validation Commands |
||||
|
|
||||
|
```bash |
||||
|
|
||||
|
# Check Node.js version |
||||
|
|
||||
|
node --version |
||||
|
|
||||
|
# Check npm version |
||||
|
|
||||
|
npm --version |
||||
|
|
||||
|
# Check global packages |
||||
|
|
||||
|
npm list -g --depth=0 |
||||
|
|
||||
|
# Validate platform tools |
||||
|
|
||||
|
npx capacitor doctor |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## Dependency Troubleshooting |
||||
|
|
||||
|
### Common Issues |
||||
|
|
||||
|
1. **Permission Errors**: Use `sudo` sparingly, prefer `npm config set prefix` |
||||
|
|
||||
|
2. **Version Conflicts**: Use `npm ls` to identify dependency conflicts |
||||
|
|
||||
|
3. **Cache Issues**: Clear npm cache with `npm cache clean --force` |
||||
|
|
||||
|
4. **Lock File Issues**: Delete `package-lock.json` and `node_modules`, |
||||
|
|
||||
|
then reinstall |
||||
|
|
||||
|
### Resolution Strategies |
||||
|
|
||||
|
- **Dependency Audit**: Run `npm audit` to identify security issues |
||||
|
|
||||
|
- **Version Pinning**: Use exact versions for critical dependencies |
||||
|
|
||||
|
- **Peer Dependency Management**: Ensure compatible versions across packages |
||||
|
|
||||
|
- **Platform-specific Dependencies**: Handle different requirements per platform |
||||
|
|
||||
|
## Best Practices for Teams |
||||
|
|
||||
|
### Onboarding |
||||
|
|
||||
|
- **Environment Setup Script**: Automated setup for new team members |
||||
|
|
||||
|
- **Version Locking**: Use `package-lock.json` and `yarn.lock` consistently |
||||
|
|
||||
|
- **Documentation**: Clear setup instructions with troubleshooting steps |
||||
|
|
||||
|
### Maintenance |
||||
|
|
||||
|
- **Regular Updates**: Schedule dependency updates and security patches |
||||
|
|
||||
|
- **Testing**: Validate changes don't break existing functionality |
||||
|
|
||||
|
- **Rollback Plan**: Maintain ability to revert to previous working versions |
||||
|
|
||||
|
**See also**: |
||||
|
`.cursor/rules/development/software_development.mdc` for core development principles. |
||||
|
|
||||
|
**Status**: Active dependency management guidelines |
||||
|
**Priority**: Medium |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: software_development.mdc |
||||
|
**Stakeholders**: Development team, DevOps team |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Dependency Changes |
||||
|
|
||||
|
- [ ] **Current State Review**: Check current dependency versions and status |
||||
|
- [ ] **Impact Analysis**: Assess impact of dependency changes on codebase |
||||
|
- [ ] **Compatibility Check**: Verify compatibility with existing code |
||||
|
- [ ] **Security Review**: Review security implications of dependency changes |
||||
|
|
||||
|
### During Dependency Management |
||||
|
|
||||
|
- [ ] **Version Selection**: Choose appropriate dependency versions |
||||
|
- [ ] **Testing**: Test with new dependency versions |
||||
|
- [ ] **Documentation**: Update dependency documentation |
||||
|
- [ ] **Team Communication**: Communicate changes to team members |
||||
|
|
||||
|
### After Dependency Changes |
||||
|
|
||||
|
- [ ] **Comprehensive Testing**: Test all functionality with new dependencies |
||||
|
- [ ] **Documentation Update**: Update all relevant documentation |
||||
|
- [ ] **Deployment Planning**: Plan and execute deployment strategy |
||||
|
- [ ] **Monitoring**: Monitor for issues after deployment |
@ -0,0 +1,119 @@ |
|||||
|
# Historical Comment Management — Code Clarity Guidelines |
||||
|
|
||||
|
> **Agent role**: When encountering historical comments about removed |
||||
|
> methods, deprecated patterns, or architectural changes, apply these |
||||
|
> guidelines to maintain code clarity and developer guidance. |
||||
|
|
||||
|
## Overview |
||||
|
|
||||
|
Historical comments should either be **removed entirely** or **transformed |
||||
|
into actionable guidance** for future developers. Avoid keeping comments |
||||
|
that merely state what was removed without explaining why or what to do |
||||
|
instead. |
||||
|
|
||||
|
## Decision Framework |
||||
|
|
||||
|
### When to Remove Comments |
||||
|
|
||||
|
- **Obsolete Information**: Comment describes functionality that no |
||||
|
longer exists |
||||
|
- **Outdated Context**: Comment refers to old patterns that are no |
||||
|
longer relevant |
||||
|
- **No Actionable Value**: Comment doesn't help future developers |
||||
|
make decisions |
||||
|
|
||||
|
### When to Transform Comments |
||||
|
|
||||
|
- **Migration Guidance**: Future developers might need to understand |
||||
|
the evolution |
||||
|
- **Alternative Approaches**: The comment can guide future |
||||
|
implementation choices |
||||
|
- **Historical Context**: Understanding the change helps with |
||||
|
current decisions |
||||
|
|
||||
|
## Transformation Patterns |
||||
|
|
||||
|
### 1. **Removed Method** → **Alternative Approach** |
||||
|
|
||||
|
```typescript |
||||
|
// Before: Historical comment |
||||
|
// turnOffNotifyingFlags method removed - notification state is now |
||||
|
// managed by NotificationSection component |
||||
|
|
||||
|
// After: Actionable guidance |
||||
|
// Note: Notification state management has been migrated to |
||||
|
// NotificationSection component |
||||
|
``` |
||||
|
|
||||
|
### 2. **Deprecated Pattern** → **Current Best Practice** |
||||
|
|
||||
|
```typescript |
||||
|
// Before: Historical comment |
||||
|
// Database access has been migrated from direct IndexedDB calls to |
||||
|
// PlatformServiceMixin |
||||
|
|
||||
|
// After: Actionable guidance |
||||
|
// This provides better platform abstraction and consistent error |
||||
|
// handling across web/mobile/desktop |
||||
|
|
||||
|
// When adding new database operations, use this.$getContact(), |
||||
|
// this.$saveSettings(), etc. |
||||
|
``` |
||||
|
|
||||
|
## Best Practices |
||||
|
|
||||
|
### 1. **Use Actionable Language**: Guide future decisions, not just |
||||
|
|
||||
|
document history |
||||
|
|
||||
|
### 2. **Provide Alternatives**: Always suggest what to use instead |
||||
|
|
||||
|
### 3. **Update Related Docs**: If removing from code, consider |
||||
|
|
||||
|
adding to documentation |
||||
|
|
||||
|
### 4. **Keep Context**: Include enough information to understand |
||||
|
|
||||
|
why the change was made |
||||
|
|
||||
|
## Integration Points |
||||
|
|
||||
|
- Apply these rules when reviewing code changes |
||||
|
- Use during code cleanup and refactoring |
||||
|
- Include in code review checklists |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: |
||||
|
|
||||
|
- `.cursor/rules/development/historical_comment_patterns.mdc` for detailed |
||||
|
transformation examples and patterns |
||||
|
|
||||
|
**Status**: Active comment management guidelines |
||||
|
**Priority**: Medium |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: None |
||||
|
**Stakeholders**: Development team, Code reviewers |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Comment Review |
||||
|
|
||||
|
- [ ] **Code Analysis**: Review code for historical or outdated comments |
||||
|
- [ ] **Context Understanding**: Understand the current state of the codebase |
||||
|
- [ ] **Pattern Identification**: Identify comments that need transformation or removal |
||||
|
- [ ] **Documentation Planning**: Plan where to move important historical context |
||||
|
|
||||
|
### During Comment Management |
||||
|
|
||||
|
- [ ] **Transformation**: Convert historical comments to actionable guidance |
||||
|
- [ ] **Alternative Provision**: Suggest current best practices and alternatives |
||||
|
- [ ] **Context Preservation**: Maintain enough information to understand changes |
||||
|
- [ ] **Documentation Update**: Move important context to appropriate documentation |
||||
|
|
||||
|
### After Comment Management |
||||
|
|
||||
|
- [ ] **Code Review**: Ensure transformed comments provide actionable value |
||||
|
- [ ] **Documentation Sync**: Verify related documentation is updated |
||||
|
- [ ] **Team Communication**: Share comment transformation patterns with team |
||||
|
- [ ] **Process Integration**: Include comment management in code review checklists |
@ -0,0 +1,139 @@ |
|||||
|
# Historical Comment Patterns — Transformation Examples |
||||
|
|
||||
|
> **Agent role**: Reference this file for specific patterns and |
||||
|
examples when transforming historical comments into actionable guidance. |
||||
|
|
||||
|
## 🔄 Transformation Patterns |
||||
|
|
||||
|
### 1. From Removal Notice to Migration Note |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// ❌ REMOVE THIS |
||||
|
// turnOffNotifyingFlags method removed - |
||||
|
notification state is now managed by NotificationSection component |
||||
|
|
||||
|
// ✅ TRANSFORM TO THIS |
||||
|
// Note: Notification state management has been migrated to NotificationSection |
||||
|
component |
||||
|
// which handles its own lifecycle and persistence via PlatformServiceMixin |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### 2. From Deprecation Notice to Implementation Guide |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// ❌ REMOVE THIS |
||||
|
// This will be handled by the NewComponent now |
||||
|
// No need to call oldMethod() as it's no longer needed |
||||
|
|
||||
|
// ✅ TRANSFORM TO THIS |
||||
|
// Note: This functionality has been migrated to NewComponent |
||||
|
// which provides better separation of concerns and testability |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### 3. From Historical Note to Architectural Context |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// ❌ REMOVE THIS |
||||
|
// Old approach: used direct database calls |
||||
|
// New approach: uses service layer |
||||
|
|
||||
|
// ✅ TRANSFORM TO THIS |
||||
|
// Note: Database access has been abstracted through service layer |
||||
|
// for better testability and platform independence |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## 🚫 Anti-Patterns to Remove |
||||
|
|
||||
|
- Comments that only state what was removed |
||||
|
|
||||
|
- Comments that don't explain the current approach |
||||
|
|
||||
|
- Comments that reference non-existent methods |
||||
|
|
||||
|
- Comments that are self-evident from the code |
||||
|
|
||||
|
- Comments that don't help future decision-making |
||||
|
|
||||
|
## 📚 Examples |
||||
|
|
||||
|
### Good Historical Comment (Keep & Transform) |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// Note: Database access has been migrated from direct IndexedDB calls to |
||||
|
PlatformServiceMixin |
||||
|
// This provides better platform abstraction and |
||||
|
consistent error handling across web/mobile/desktop |
||||
|
// When adding new database operations, use this.$getContact(), |
||||
|
this.$saveSettings(), etc. |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### Bad Historical Comment (Remove) |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// Old method getContactFromDB() removed - now handled by PlatformServiceMixin |
||||
|
// No need to call the old method anymore |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## 🎯 When to Use Each Pattern |
||||
|
|
||||
|
### Migration Notes |
||||
|
|
||||
|
- Use when functionality has moved to a different component/service |
||||
|
|
||||
|
- Explain the new location and why it's better |
||||
|
|
||||
|
- Provide guidance on how to use the new approach |
||||
|
|
||||
|
### Implementation Guides |
||||
|
|
||||
|
- Use when patterns have changed significantly |
||||
|
|
||||
|
- Explain the architectural benefits |
||||
|
|
||||
|
- Show how to implement the new pattern |
||||
|
|
||||
|
### Architectural Context |
||||
|
|
||||
|
- Use when the change represents a system-wide improvement |
||||
|
|
||||
|
- Explain the reasoning behind the change |
||||
|
|
||||
|
- Help future developers understand the evolution |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: `.cursor/rules/development/historical_comment_management.mdc` for |
||||
|
the core decision framework and best practices. |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Comment Review |
||||
|
|
||||
|
- [ ] **Code Analysis**: Review code for historical or outdated comments |
||||
|
- [ ] **Pattern Identification**: Identify comments that need transformation or removal |
||||
|
- [ ] **Context Understanding**: Understand the current state of the codebase |
||||
|
- [ ] **Transformation Planning**: Plan how to transform or remove comments |
||||
|
|
||||
|
### During Comment Transformation |
||||
|
|
||||
|
- [ ] **Pattern Selection**: Choose appropriate transformation pattern |
||||
|
- [ ] **Content Creation**: Create actionable guidance for future developers |
||||
|
- [ ] **Alternative Provision**: Suggest current best practices and approaches |
||||
|
- [ ] **Context Preservation**: Maintain enough information to understand changes |
||||
|
|
||||
|
### After Comment Transformation |
||||
|
|
||||
|
- [ ] **Code Review**: Ensure transformed comments provide actionable value |
||||
|
- [ ] **Pattern Documentation**: Document transformation patterns for team use |
||||
|
- [ ] **Team Communication**: Share comment transformation patterns with team |
||||
|
- [ ] **Process Integration**: Include comment patterns in code review checklists |
@ -0,0 +1,358 @@ |
|||||
|
--- |
||||
|
alwaysApply: false |
||||
|
--- |
||||
|
|
||||
|
# Logging Migration — Patterns and Examples |
||||
|
|
||||
|
> **Agent role**: Reference this file for specific migration patterns and |
||||
|
examples when converting console.* calls to logger usage. |
||||
|
|
||||
|
## Migration — Auto‑Rewrites (Apply Every Time) |
||||
|
|
||||
|
### Exact Transforms |
||||
|
|
||||
|
- `console.debug(...)` → `logger.debug(...)` |
||||
|
|
||||
|
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when |
||||
|
|
||||
|
clearly stateful) |
||||
|
|
||||
|
- `console.info(...)` → `logger.info(...)` |
||||
|
|
||||
|
- `console.warn(...)` → `logger.warn(...)` |
||||
|
|
||||
|
- `console.error(...)` → `logger.error(...)` |
||||
|
|
||||
|
### Multi-arg Handling |
||||
|
|
||||
|
- First arg becomes `message` (stringify safely if non-string). |
||||
|
|
||||
|
- Remaining args map 1:1 to `...args`: |
||||
|
|
||||
|
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)` |
||||
|
|
||||
|
### Sole `Error` |
||||
|
|
||||
|
- `console.error(err)` → `logger.error(err.message, err)` |
||||
|
|
||||
|
### Object-wrapping Cleanup |
||||
|
|
||||
|
Replace `{{ userId, meta }}` wrappers with separate args: |
||||
|
`logger.info('User signed in', userId, meta)` |
||||
|
|
||||
|
## Level Guidelines with Examples |
||||
|
|
||||
|
### DEBUG Examples |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
logger.debug('[HomeView] reloadFeedOnChange() called'); |
||||
|
logger.debug('[HomeView] Current filter settings', |
||||
|
settings.filterFeedByVisible, |
||||
|
settings.filterFeedByNearby, |
||||
|
settings.searchBoxes?.length ?? 0); |
||||
|
logger.debug('[FeedFilters] Toggling nearby filter', |
||||
|
this.isNearby, this.settingChanged, this.activeDid); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Avoid**: Vague messages (`'Processing data'`). |
||||
|
|
||||
|
### INFO Examples |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); |
||||
|
logger.info('[StartView] User selected new seed generation'); |
||||
|
logger.info('[SearchAreaView] Search box stored', |
||||
|
searchBox.name, searchBox.bbox); |
||||
|
logger.info('[ContactQRScanShowView] Contact registration OK', |
||||
|
contact.did); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Avoid**: Diagnostic details that belong in `debug`. |
||||
|
|
||||
|
### WARN Examples |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
logger.warn('[ContactQRScanShowView] Invalid scan result – no value', |
||||
|
resultType); |
||||
|
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); |
||||
|
logger.warn('[ContactQRScanShowView] JWT missing "own" field'); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Avoid**: Hard failures (those are `error`). |
||||
|
|
||||
|
### ERROR Examples |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
logger.error('[HomeView Settings] initializeIdentity() failed', err); |
||||
|
logger.error('[StartView] Failed to load initialization data', error); |
||||
|
logger.error('[ContactQRScanShowView] Error processing contact QR', |
||||
|
error, rawValue); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Avoid**: Expected user cancels (use `info`/`debug`). |
||||
|
|
||||
|
## Context Hygiene Examples |
||||
|
|
||||
|
### Component Context |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
const log = logger.withContext('UserService'); |
||||
|
log.info('User created', userId); |
||||
|
log.error('Failed to create user', error); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
If not using `withContext`, prefix message with `[ComponentName]`. |
||||
|
|
||||
|
### Emoji Guidelines |
||||
|
|
||||
|
Recommended set for visual scanning: |
||||
|
|
||||
|
- Start/finish: 🚀 / ✅ |
||||
|
|
||||
|
- Retry/loop: 🔄 |
||||
|
|
||||
|
- External call: 📡 |
||||
|
|
||||
|
- Data/metrics: 📊 |
||||
|
|
||||
|
- Inspection: 🔍 |
||||
|
|
||||
|
## Quick Before/After |
||||
|
|
||||
|
### **Before** |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
console.log('User signed in', user.id, meta); |
||||
|
console.error('Failed to update profile', err); |
||||
|
console.info('Filter toggled', this.hasVisibleDid); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### **After** |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
import { logger } from '@/utils/logger'; |
||||
|
|
||||
|
logger.info('User signed in', user.id, meta); |
||||
|
logger.error('Failed to update profile', err); |
||||
|
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## Checklist (for every PR) |
||||
|
|
||||
|
- [ ] No `console.*` (or properly pragma'd in the allowed locations) |
||||
|
|
||||
|
- [ ] Correct import path for `logger` |
||||
|
|
||||
|
- [ ] Rest-parameter call shape (`message, ...args`) |
||||
|
|
||||
|
- [ ] Right level chosen (debug/info/warn/error) |
||||
|
|
||||
|
- [ ] No secrets / oversized payloads / throwaway context objects |
||||
|
|
||||
|
- [ ] Component context provided (scoped logger or `[Component]` prefix) |
||||
|
|
||||
|
**See also**: |
||||
|
`.cursor/rules/development/logging_standards.mdc` for the core standards and rules. |
||||
|
|
||||
|
# Logging Migration — Patterns and Examples |
||||
|
|
||||
|
> **Agent role**: Reference this file for specific migration patterns and |
||||
|
examples when converting console.* calls to logger usage. |
||||
|
|
||||
|
## Migration — Auto‑Rewrites (Apply Every Time) |
||||
|
|
||||
|
### Exact Transforms |
||||
|
|
||||
|
- `console.debug(...)` → `logger.debug(...)` |
||||
|
|
||||
|
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when |
||||
|
|
||||
|
clearly stateful) |
||||
|
|
||||
|
- `console.info(...)` → `logger.info(...)` |
||||
|
|
||||
|
- `console.warn(...)` → `logger.warn(...)` |
||||
|
|
||||
|
- `console.error(...)` → `logger.error(...)` |
||||
|
|
||||
|
### Multi-arg Handling |
||||
|
|
||||
|
- First arg becomes `message` (stringify safely if non-string). |
||||
|
|
||||
|
- Remaining args map 1:1 to `...args`: |
||||
|
|
||||
|
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)` |
||||
|
|
||||
|
### Sole `Error` |
||||
|
|
||||
|
- `console.error(err)` → `logger.error(err.message, err)` |
||||
|
|
||||
|
### Object-wrapping Cleanup |
||||
|
|
||||
|
Replace `{{ userId, meta }}` wrappers with separate args: |
||||
|
`logger.info('User signed in', userId, meta)` |
||||
|
|
||||
|
## Level Guidelines with Examples |
||||
|
|
||||
|
### DEBUG Examples |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
logger.debug('[HomeView] reloadFeedOnChange() called'); |
||||
|
logger.debug('[HomeView] Current filter settings', |
||||
|
settings.filterFeedByVisible, |
||||
|
settings.filterFeedByNearby, |
||||
|
settings.searchBoxes?.length ?? 0); |
||||
|
logger.debug('[FeedFilters] Toggling nearby filter', |
||||
|
this.isNearby, this.settingChanged, this.activeDid); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Avoid**: Vague messages (`'Processing data'`). |
||||
|
|
||||
|
### INFO Examples |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); |
||||
|
logger.info('[StartView] User selected new seed generation'); |
||||
|
logger.info('[SearchAreaView] Search box stored', |
||||
|
searchBox.name, searchBox.bbox); |
||||
|
logger.info('[ContactQRScanShowView] Contact registration OK', |
||||
|
contact.did); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Avoid**: Diagnostic details that belong in `debug`. |
||||
|
|
||||
|
### WARN Examples |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
logger.warn('[ContactQRScanShowView] Invalid scan result – no value', |
||||
|
resultType); |
||||
|
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); |
||||
|
logger.warn('[ContactQRScanShowView] JWT missing "own" field'); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Avoid**: Hard failures (those are `error`). |
||||
|
|
||||
|
### ERROR Examples |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
logger.error('[HomeView Settings] initializeIdentity() failed', err); |
||||
|
logger.error('[StartView] Failed to load initialization data', error); |
||||
|
logger.error('[ContactQRScanShowView] Error processing contact QR', |
||||
|
error, rawValue); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
**Avoid**: Expected user cancels (use `info`/`debug`). |
||||
|
|
||||
|
## Context Hygiene Examples |
||||
|
|
||||
|
### Component Context |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
const log = logger.withContext('UserService'); |
||||
|
log.info('User created', userId); |
||||
|
log.error('Failed to create user', error); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
If not using `withContext`, prefix message with `[ComponentName]`. |
||||
|
|
||||
|
### Emoji Guidelines |
||||
|
|
||||
|
Recommended set for visual scanning: |
||||
|
|
||||
|
- Start/finish: 🚀 / ✅ |
||||
|
|
||||
|
- Retry/loop: 🔄 |
||||
|
|
||||
|
- External call: 📡 |
||||
|
|
||||
|
- Data/metrics: 📊 |
||||
|
|
||||
|
- Inspection: 🔍 |
||||
|
|
||||
|
## Quick Before/After |
||||
|
|
||||
|
### **Before** |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
console.log('User signed in', user.id, meta); |
||||
|
console.error('Failed to update profile', err); |
||||
|
console.info('Filter toggled', this.hasVisibleDid); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### **After** |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
import { logger } from '@/utils/logger'; |
||||
|
|
||||
|
logger.info('User signed in', user.id, meta); |
||||
|
logger.error('Failed to update profile', err); |
||||
|
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## Checklist (for every PR) |
||||
|
|
||||
|
- [ ] No `console.*` (or properly pragma'd in the allowed locations) |
||||
|
|
||||
|
- [ ] Correct import path for `logger` |
||||
|
|
||||
|
- [ ] Rest-parameter call shape (`message, ...args`) |
||||
|
|
||||
|
- [ ] Right level chosen (debug/info/warn/error) |
||||
|
|
||||
|
- [ ] No secrets / oversized payloads / throwaway context objects |
||||
|
|
||||
|
- [ ] Component context provided (scoped logger or `[Component]` prefix) |
||||
|
|
||||
|
**See also**: |
||||
|
`.cursor/rules/development/logging_standards.mdc` for the core standards and rules. |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Logging Migration |
||||
|
|
||||
|
- [ ] **Code Review**: Identify all `console.*` calls in the codebase |
||||
|
- [ ] **Logger Import**: Verify logger utility is available and accessible |
||||
|
- [ ] **Context Planning**: Plan component context for each logging call |
||||
|
- [ ] **Level Assessment**: Determine appropriate log levels for each call |
||||
|
|
||||
|
### During Logging Migration |
||||
|
|
||||
|
- [ ] **Import Replacement**: Replace `console.*` with `logger.*` calls |
||||
|
- [ ] **Context Addition**: Add component context using scoped logger or prefix |
||||
|
- [ ] **Level Selection**: Choose appropriate log level (debug/info/warn/error) |
||||
|
- [ ] **Parameter Format**: Use rest-parameter call shape (`message, ...args`) |
||||
|
|
||||
|
### After Logging Migration |
||||
|
|
||||
|
- [ ] **Console Check**: Ensure no `console.*` methods remain (unless pragma'd) |
||||
|
- [ ] **Context Validation**: Verify all logging calls have proper context |
||||
|
- [ ] **Level Review**: Confirm log levels are appropriate for each situation |
||||
|
- [ ] **Testing**: Test logging functionality across all platforms |
@ -0,0 +1,160 @@ |
|||||
|
# Planning Examples — No Time Estimates |
||||
|
|
||||
|
> **Agent role**: Reference this file for detailed planning examples and |
||||
|
anti-patterns when creating project plans. |
||||
|
|
||||
|
## 🎯 Example Planning (No Time Estimates) |
||||
|
|
||||
|
### **Example 1: Simple Feature** |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
Phase 1: Core implementation |
||||
|
|
||||
|
- Basic functionality |
||||
|
|
||||
|
- Single platform support |
||||
|
|
||||
|
- Unit tests |
||||
|
|
||||
|
Phase 2: Platform expansion |
||||
|
|
||||
|
- Multi-platform support |
||||
|
|
||||
|
- Integration tests |
||||
|
|
||||
|
Phase 3: Polish |
||||
|
|
||||
|
- User testing |
||||
|
|
||||
|
- Edge case handling |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### **Example 2: Complex Cross-Platform Feature** |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
Phase 1: Foundation |
||||
|
|
||||
|
- Architecture design |
||||
|
|
||||
|
- Core service implementation |
||||
|
|
||||
|
- Basic web platform support |
||||
|
|
||||
|
Phase 2: Platform Integration |
||||
|
|
||||
|
- Mobile platform support |
||||
|
|
||||
|
- Desktop platform support |
||||
|
|
||||
|
- Cross-platform consistency |
||||
|
|
||||
|
Phase 3: Testing & Polish |
||||
|
|
||||
|
- Comprehensive testing |
||||
|
|
||||
|
- Error handling |
||||
|
|
||||
|
- User experience refinement |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## 🚫 Anti-Patterns to Avoid |
||||
|
|
||||
|
- **"This should take X days"** - Red flag for time estimation |
||||
|
|
||||
|
- **"Just a few hours"** - Ignores complexity and testing |
||||
|
|
||||
|
- **"Similar to X"** - Without considering differences |
||||
|
|
||||
|
- **"Quick fix"** - Nothing is ever quick in software |
||||
|
|
||||
|
- **"No testing needed"** - Testing always takes effort |
||||
|
|
||||
|
## ✅ Best Practices |
||||
|
|
||||
|
### **When Planning:** |
||||
|
|
||||
|
1. **Break down everything** - no work is too small to plan |
||||
|
|
||||
|
2. **Consider all platforms** - web, mobile, desktop differences |
||||
|
|
||||
|
3. **Include testing strategy** - unit, integration, and user testing |
||||
|
|
||||
|
4. **Account for unknowns** - there are always surprises |
||||
|
|
||||
|
5. **Focus on dependencies** - what blocks what |
||||
|
|
||||
|
### **When Presenting Plans:** |
||||
|
|
||||
|
1. **Show the phases** - explain the logical progression |
||||
|
|
||||
|
2. **Highlight dependencies** - what could block progress |
||||
|
|
||||
|
3. **Define milestones** - clear success criteria |
||||
|
|
||||
|
4. **Identify risks** - what could go wrong |
||||
|
|
||||
|
5. **Suggest alternatives** - ways to reduce scope or complexity |
||||
|
|
||||
|
## 🔄 Continuous Improvement |
||||
|
|
||||
|
### **Track Progress** |
||||
|
|
||||
|
- Record planned vs. actual phases completed |
||||
|
|
||||
|
- Identify what took longer than expected |
||||
|
|
||||
|
- Learn from complexity misjudgments |
||||
|
|
||||
|
- Adjust planning process based on experience |
||||
|
|
||||
|
### **Learn from Experience** |
||||
|
|
||||
|
- **Underestimated complexity**: Increase complexity categories |
||||
|
|
||||
|
- **Missed dependencies**: Improve dependency mapping |
||||
|
|
||||
|
- **Platform surprises**: Better platform research upfront |
||||
|
|
||||
|
## 🎯 Integration with Harbor Pilot |
||||
|
|
||||
|
This rule works in conjunction with: |
||||
|
|
||||
|
- **Project Planning**: Focuses on phases and milestones |
||||
|
|
||||
|
- **Resource Allocation**: Based on complexity, not time |
||||
|
|
||||
|
- **Risk Management**: Identifies blockers and dependencies |
||||
|
|
||||
|
- **Stakeholder Communication**: Sets progress-based expectations |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: `.cursor/rules/development/realistic_time_estimation.mdc` for |
||||
|
the core principles and framework. |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Planning |
||||
|
|
||||
|
- [ ] **Requirements Review**: Understand all requirements completely |
||||
|
- [ ] **Stakeholder Input**: Gather input from all stakeholders |
||||
|
- [ ] **Complexity Assessment**: Evaluate technical and business complexity |
||||
|
- [ ] **Platform Analysis**: Consider requirements across all target platforms |
||||
|
|
||||
|
### During Planning |
||||
|
|
||||
|
- [ ] **Phase Definition**: Define clear phases and milestones |
||||
|
- [ ] **Dependency Mapping**: Map dependencies between tasks |
||||
|
- [ ] **Risk Identification**: Identify potential risks and challenges |
||||
|
- [ ] **Testing Strategy**: Plan comprehensive testing approach |
||||
|
|
||||
|
### After Planning |
||||
|
|
||||
|
- [ ] **Stakeholder Review**: Review plan with stakeholders |
||||
|
- [ ] **Documentation**: Document plan clearly with phases and milestones |
||||
|
- [ ] **Team Communication**: Communicate plan to team |
||||
|
- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms |
@ -0,0 +1,128 @@ |
|||||
|
# Realistic Time Estimation — Development Guidelines |
||||
|
|
||||
|
> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, |
||||
|
> milestones, and complexity levels. Time estimates are consistently wrong |
||||
|
> and create unrealistic expectations. |
||||
|
|
||||
|
## Purpose |
||||
|
|
||||
|
Development time estimates are consistently wrong and create unrealistic |
||||
|
expectations. This rule ensures we focus on phases, milestones, and |
||||
|
complexity rather than trying to predict specific timeframes. |
||||
|
|
||||
|
## Critical Rule |
||||
|
|
||||
|
**NEVER provide specific time estimates** (hours, days, weeks) for |
||||
|
development tasks. Instead, use: |
||||
|
|
||||
|
- **Complexity levels** (Low, Medium, High, Critical) |
||||
|
|
||||
|
- **Phases and milestones** with clear acceptance criteria |
||||
|
|
||||
|
- **Platform-specific considerations** (Web, Mobile, Desktop) |
||||
|
|
||||
|
- **Testing requirements** and validation steps |
||||
|
|
||||
|
## Planning Framework |
||||
|
|
||||
|
### Complexity Assessment |
||||
|
|
||||
|
- **Low**: Simple changes, existing patterns, minimal testing |
||||
|
|
||||
|
- **Medium**: New features, moderate testing, some integration |
||||
|
|
||||
|
- **High**: Complex features, extensive testing, multiple platforms |
||||
|
|
||||
|
- **Critical**: Core architecture changes, full regression testing |
||||
|
|
||||
|
### Platform Categories |
||||
|
|
||||
|
- **Web**: Browser compatibility, responsive design, accessibility |
||||
|
|
||||
|
- **Mobile**: Native APIs, platform-specific testing, deployment |
||||
|
|
||||
|
- **Desktop**: Electron integration, system APIs, distribution |
||||
|
|
||||
|
### Testing Strategy |
||||
|
|
||||
|
- **Unit tests**: Core functionality validation |
||||
|
|
||||
|
- **Integration tests**: Component interaction testing |
||||
|
|
||||
|
- **E2E tests**: User workflow validation |
||||
|
|
||||
|
- **Platform tests**: Cross-platform compatibility |
||||
|
|
||||
|
## Process Guidelines |
||||
|
|
||||
|
### Planning Phase |
||||
|
|
||||
|
1. **Scope Definition**: Clear requirements and acceptance criteria |
||||
|
|
||||
|
2. **Complexity Assessment**: Evaluate technical and business complexity |
||||
|
|
||||
|
3. **Phase Breakdown**: Divide into logical, testable phases |
||||
|
|
||||
|
4. **Milestone Definition**: Define success criteria for each phase |
||||
|
|
||||
|
### Execution Phase |
||||
|
|
||||
|
1. **Phase 1**: Foundation and core implementation |
||||
|
|
||||
|
2. **Phase 2**: Feature completion and integration |
||||
|
|
||||
|
3. **Phase 3**: Testing, refinement, and documentation |
||||
|
|
||||
|
4. **Phase 4**: Deployment and validation |
||||
|
|
||||
|
### Validation Phase |
||||
|
|
||||
|
1. **Acceptance Testing**: Verify against defined criteria |
||||
|
|
||||
|
2. **Platform Testing**: Validate across target platforms |
||||
|
|
||||
|
3. **Performance Testing**: Ensure performance requirements met |
||||
|
|
||||
|
4. **Documentation**: Update relevant documentation |
||||
|
|
||||
|
## Remember |
||||
|
|
||||
|
**Your first estimate is wrong. Your second estimate is probably still |
||||
|
wrong. Focus on progress, not deadlines.** |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: |
||||
|
|
||||
|
- `.cursor/rules/development/planning_examples.mdc` for detailed planning examples |
||||
|
|
||||
|
- `.cursor/rules/development/complexity_assessment.mdc` for complexity evaluation |
||||
|
|
||||
|
**Status**: Active development guidelines |
||||
|
**Priority**: High |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: None |
||||
|
**Stakeholders**: Development team, Project managers |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Time Estimation |
||||
|
|
||||
|
- [ ] **Requirements Analysis**: Understand all requirements and acceptance criteria |
||||
|
- [ ] **Complexity Assessment**: Evaluate technical and business complexity |
||||
|
- [ ] **Platform Review**: Identify requirements across all target platforms |
||||
|
- [ ] **Stakeholder Input**: Gather input from all affected parties |
||||
|
|
||||
|
### During Time Estimation |
||||
|
|
||||
|
- [ ] **Phase Breakdown**: Divide work into logical, testable phases |
||||
|
- [ ] **Complexity Classification**: Assign complexity levels (Low/Medium/High/Critical) |
||||
|
- [ ] **Platform Considerations**: Account for platform-specific requirements |
||||
|
- [ ] **Testing Strategy**: Plan comprehensive testing approach |
||||
|
|
||||
|
### After Time Estimation |
||||
|
|
||||
|
- [ ] **Milestone Definition**: Define success criteria for each phase |
||||
|
- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms |
||||
|
- [ ] **Documentation**: Document estimation process and assumptions |
||||
|
- [ ] **Stakeholder Communication**: Share estimation approach and progress focus |
@ -0,0 +1,146 @@ |
|||||
|
# Time Handling in Development Workflow |
||||
|
|
||||
|
**Author**: Matthew Raymer |
||||
|
**Date**: 2025-08-17 |
||||
|
**Status**: 🎯 **ACTIVE** - Production Ready |
||||
|
|
||||
|
## Overview |
||||
|
|
||||
|
This guide establishes **how time should be referenced and used** across the |
||||
|
development workflow. It is not tied to any one project, but applies to **all |
||||
|
feature development, issue investigations, ADRs, and documentation**. |
||||
|
|
||||
|
## General Principles |
||||
|
|
||||
|
- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over |
||||
|
|
||||
|
relative references like "last week." |
||||
|
|
||||
|
- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in |
||||
|
|
||||
|
docs, issues, ADRs, and commits. |
||||
|
|
||||
|
- **Time zones**: Default to **UTC** unless explicitly tied to user-facing |
||||
|
|
||||
|
behavior. |
||||
|
|
||||
|
- **Precision**: Only specify as much precision as needed (date vs. datetime vs. |
||||
|
|
||||
|
timestamp). |
||||
|
|
||||
|
- **Consistency**: Align time references across ADRs, commits, and investigation |
||||
|
|
||||
|
reports. |
||||
|
|
||||
|
## In Documentation & ADRs |
||||
|
|
||||
|
- Record decision dates using **absolute ISO dates**. |
||||
|
|
||||
|
- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` → |
||||
|
|
||||
|
`2025-08-17`). |
||||
|
|
||||
|
- Avoid ambiguous terms like *recently*, *last month*, or *soon*. |
||||
|
|
||||
|
- For time-based experiments (e.g., A/B tests), always include: |
||||
|
|
||||
|
- Start date |
||||
|
|
||||
|
- Expected duration |
||||
|
|
||||
|
- Review date checkpoint |
||||
|
|
||||
|
## In Code & Commits |
||||
|
|
||||
|
- Use **UTC timestamps** in logs, DB migrations, and serialized formats. |
||||
|
|
||||
|
- In commits, link changes to **date-bound ADRs or investigation docs**. |
||||
|
|
||||
|
- For migrations, include both **applied date** and **intended version window**. |
||||
|
|
||||
|
- Use constants for known fixed dates; avoid hardcoding arbitrary strings. |
||||
|
|
||||
|
## In Investigations & Research |
||||
|
|
||||
|
- Capture **when** an issue occurred (absolute time or version tag). |
||||
|
|
||||
|
- When describing failures: note whether they are **time-sensitive** (e.g., |
||||
|
|
||||
|
after |
||||
|
migrations, cache expirations). |
||||
|
|
||||
|
- Record diagnostic timelines in ISO format (not relative). |
||||
|
|
||||
|
- For performance regressions, annotate both **baseline timeframe** and |
||||
|
|
||||
|
**measurement timeframe**. |
||||
|
|
||||
|
## Collaboration Hooks |
||||
|
|
||||
|
- During reviews, verify **time references are clear, absolute, and |
||||
|
|
||||
|
standardized**. |
||||
|
|
||||
|
- In syncs, reframe relative terms ("this week") into shared absolute |
||||
|
|
||||
|
references. |
||||
|
|
||||
|
- Tag ADRs with both **date created** and **review by** checkpoints. |
||||
|
|
||||
|
## Self-Check Before Submitting |
||||
|
|
||||
|
- [ ] Did I check the time using the **developer's actual system time and |
||||
|
|
||||
|
timezone**? |
||||
|
|
||||
|
- [ ] Am I using absolute ISO dates? |
||||
|
|
||||
|
- [ ] Is UTC assumed unless specified otherwise? |
||||
|
|
||||
|
- [ ] Did I avoid ambiguous relative terms? |
||||
|
|
||||
|
- [ ] If duration matters, did I specify both start and end? |
||||
|
|
||||
|
- [ ] For future work, did I include a review/revisit date? |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: |
||||
|
|
||||
|
- `.cursor/rules/development/time_implementation.mdc` for |
||||
|
|
||||
|
detailed implementation instructions |
||||
|
|
||||
|
- `.cursor/rules/development/time_examples.mdc` for practical examples and patterns |
||||
|
|
||||
|
**Status**: Active time handling guidelines |
||||
|
**Priority**: High |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: None |
||||
|
**Stakeholders**: Development team, Documentation team |
||||
|
|
||||
|
**Maintainer**: Matthew Raymer |
||||
|
**Next Review**: 2025-09-17 |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Time-Related Work |
||||
|
|
||||
|
- [ ] **Time Context**: Understand what time information is needed |
||||
|
- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) |
||||
|
- [ ] **Platform Check**: Identify platform-specific time requirements |
||||
|
- [ ] **User Context**: Consider user's timezone and preferences |
||||
|
|
||||
|
### During Time Implementation |
||||
|
|
||||
|
- [ ] **UTC Usage**: Use UTC for all system and log timestamps |
||||
|
- [ ] **Format Consistency**: Apply consistent time formatting patterns |
||||
|
- [ ] **Timezone Handling**: Properly handle timezone conversions |
||||
|
- [ ] **User Display**: Format times appropriately for user display |
||||
|
|
||||
|
### After Time Implementation |
||||
|
|
||||
|
- [ ] **Validation**: Verify time formats are correct and consistent |
||||
|
- [ ] **Testing**: Test time handling across different scenarios |
||||
|
- [ ] **Documentation**: Update relevant documentation with time patterns |
||||
|
- [ ] **Review**: Confirm implementation follows time standards |
@ -0,0 +1,243 @@ |
|||||
|
# Time Examples — Practical Patterns |
||||
|
|
||||
|
> **Agent role**: Reference this file for practical examples and |
||||
|
patterns when working with time handling in development. |
||||
|
|
||||
|
## Examples |
||||
|
|
||||
|
### Good |
||||
|
|
||||
|
- "Feature flag rollout started on `2025-08-01` and will be reviewed on |
||||
|
|
||||
|
`2025-08-21`." |
||||
|
|
||||
|
- "Migration applied on `2025-07-15T14:00Z`." |
||||
|
|
||||
|
- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` / |
||||
|
|
||||
|
`2025-08-17T14:00Z (UTC)`." |
||||
|
|
||||
|
### Bad |
||||
|
|
||||
|
- "Feature flag rolled out last week." |
||||
|
|
||||
|
- "Migration applied recently." |
||||
|
|
||||
|
- "Now is August, so we assume this was last month." |
||||
|
|
||||
|
### More Examples |
||||
|
|
||||
|
#### Issue Reports |
||||
|
|
||||
|
- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue |
||||
|
|
||||
|
persisted until `2025-08-17T15:45:00Z`." |
||||
|
|
||||
|
- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a |
||||
|
|
||||
|
while." |
||||
|
|
||||
|
#### Release Planning |
||||
|
|
||||
|
- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing |
||||
|
|
||||
|
window: `2025-08-20` to `2025-08-24`." |
||||
|
|
||||
|
- ❌ **Bad**: "Feature X will be released next week after testing." |
||||
|
|
||||
|
#### Performance Monitoring |
||||
|
|
||||
|
- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`. |
||||
|
|
||||
|
Regression detected on `2025-08-15T14:00:00Z`." |
||||
|
|
||||
|
- ❌ **Bad**: "Performance was good last week but got worse this week." |
||||
|
|
||||
|
## Technical Implementation Examples |
||||
|
|
||||
|
### Database Storage |
||||
|
|
||||
|
```sql |
||||
|
|
||||
|
-- ✅ Good: Store in UTC |
||||
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
||||
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP |
||||
|
|
||||
|
-- ❌ Bad: Store in local time |
||||
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, |
||||
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### API Responses |
||||
|
|
||||
|
```json |
||||
|
|
||||
|
// ✅ Good: Include both UTC and local time |
||||
|
{ |
||||
|
"eventTime": "2025-08-17T14:00:00Z", |
||||
|
"localTime": "2025-08-17T10:00:00-04:00", |
||||
|
"timezone": "America/New_York" |
||||
|
} |
||||
|
|
||||
|
// ❌ Bad: Only local time |
||||
|
{ |
||||
|
"eventTime": "2025-08-17T10:00:00-04:00" |
||||
|
} |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### Logging |
||||
|
|
||||
|
```python |
||||
|
|
||||
|
# ✅ Good: Log in UTC with timezone info |
||||
|
|
||||
|
logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)") |
||||
|
|
||||
|
# ❌ Bad: Log in local time |
||||
|
|
||||
|
logger.info(f"User action at {datetime.now()}") |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## Timezone Handling Examples |
||||
|
|
||||
|
### Good Timezone Usage |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// ✅ Good: Store UTC, convert for display |
||||
|
const eventTime = new Date().toISOString(); // Store in UTC |
||||
|
const localTime = new Date().toLocaleString('en-US', { |
||||
|
timeZone: 'America/New_York' |
||||
|
}); // Convert for display |
||||
|
|
||||
|
// ✅ Good: Include timezone context |
||||
|
const timestamp = { |
||||
|
utc: "2025-08-17T14:00:00Z", |
||||
|
local: "2025-08-17T10:00:00-04:00", |
||||
|
timezone: "America/New_York" |
||||
|
}; |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### Bad Timezone Usage |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// ❌ Bad: Assume timezone |
||||
|
const now = new Date(); // Assumes system timezone |
||||
|
|
||||
|
// ❌ Bad: Mix formats |
||||
|
const timestamp = "2025-08-17 10:00 AM"; // Ambiguous format |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## Common Patterns |
||||
|
|
||||
|
### Date Range References |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// ✅ Good: Explicit date ranges |
||||
|
const dateRange = { |
||||
|
start: "2025-08-01T00:00:00Z", |
||||
|
end: "2025-08-31T23:59:59Z" |
||||
|
}; |
||||
|
|
||||
|
// ❌ Bad: Relative ranges |
||||
|
const dateRange = { |
||||
|
start: "beginning of month", |
||||
|
end: "end of month" |
||||
|
}; |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### Duration References |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// ✅ Good: Specific durations |
||||
|
const duration = { |
||||
|
value: 30, |
||||
|
unit: "days", |
||||
|
startDate: "2025-08-01T00:00:00Z" |
||||
|
}; |
||||
|
|
||||
|
// ❌ Bad: Vague durations |
||||
|
const duration = "about a month"; |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
### Version References |
||||
|
|
||||
|
```typescript |
||||
|
|
||||
|
// ✅ Good: Version with date |
||||
|
const version = { |
||||
|
number: "1.2.3", |
||||
|
releaseDate: "2025-08-17T10:00:00Z", |
||||
|
buildDate: "2025-08-17T09:30:00Z" |
||||
|
}; |
||||
|
|
||||
|
// ❌ Bad: Version without context |
||||
|
const version = "latest"; |
||||
|
|
||||
|
``` |
||||
|
|
||||
|
## References |
||||
|
|
||||
|
- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601) |
||||
|
|
||||
|
- [IANA Timezone Database](https://www.iana.org/time-zones) |
||||
|
|
||||
|
- [ADR Template](./adr_template.md) |
||||
|
|
||||
|
- [Research & Diagnostic Workflow](./research_diagnostic.mdc) |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**Rule of Thumb**: Every time reference in development artifacts should be |
||||
|
**clear in 6 months without context**, and aligned to the **developer's actual |
||||
|
current time**. |
||||
|
|
||||
|
**Technical Rule of Thumb**: **Store in UTC, display in local time, always |
||||
|
include timezone context.** |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: |
||||
|
|
||||
|
- `.cursor/rules/development/time.mdc` for core principles |
||||
|
|
||||
|
- `.cursor/rules/development/time_implementation.mdc` for implementation instructions |
||||
|
|
||||
|
**Status**: Active examples and patterns |
||||
|
**Priority**: Medium |
||||
|
**Estimated Effort**: Ongoing reference |
||||
|
**Dependencies**: time.mdc, time_implementation.mdc |
||||
|
**Stakeholders**: Development team, Documentation team |
||||
|
|
||||
|
## Model Implementation Checklist |
||||
|
|
||||
|
### Before Time Implementation |
||||
|
|
||||
|
- [ ] **Time Context**: Understand what time information needs to be implemented |
||||
|
- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) |
||||
|
- [ ] **Platform Check**: Identify platform-specific time requirements |
||||
|
- [ ] **User Context**: Consider user's timezone and display preferences |
||||
|
|
||||
|
### During Time Implementation |
||||
|
|
||||
|
- [ ] **UTC Storage**: Use UTC for all system and log timestamps |
||||
|
- [ ] **Format Consistency**: Apply consistent time formatting patterns |
||||
|
- [ ] **Timezone Handling**: Properly handle timezone conversions |
||||
|
- [ ] **User Display**: Format times appropriately for user display |
||||
|
|
||||
|
### After Time Implementation |
||||
|
|
||||
|
- [ ] **Format Validation**: Verify time formats are correct and consistent |
||||
|
- [ ] **Cross-Platform Testing**: Test time handling across different platforms |
||||
|
- [ ] **Documentation**: Update relevant documentation with time patterns |
||||
|
- [ ] **User Experience**: Confirm time display is clear and user-friendly |
@ -1,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,175 @@ |
|||||
|
# 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. |
||||
|
|
||||
|
## 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 |
||||
|
|
||||
|
## 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 |
||||
|
|
||||
|
## 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 |
||||
|
|
||||
|
### 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 |
||||
|
|
||||
|
### 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 |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**See also**: |
||||
|
|
||||
|
- `.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,219 @@ |
|||||
|
# Markdown Templates & Examples |
||||
|
|
||||
|
> **Agent role**: Reference this file for document templates, structure, |
||||
|
> and examples when creating new documentation. |
||||
|
|
||||
|
## 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. |
||||
|
|
||||
|
## 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 |
||||
|
``` |
||||
|
|
||||
|
### 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. |
||||
|
|
||||
|
## Requirements |
||||
|
|
||||
|
### Functional Requirements |
||||
|
|
||||
|
- [ ] Requirement 1 |
||||
|
- [ ] Requirement 2 |
||||
|
|
||||
|
### Non-Functional Requirements |
||||
|
|
||||
|
- [ ] Performance requirement |
||||
|
- [ ] Security requirement |
||||
|
|
||||
|
## Technical Design |
||||
|
|
||||
|
### Architecture |
||||
|
|
||||
|
Description of the technical architecture. |
||||
|
|
||||
|
### 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 |
||||
|
- [ ] 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/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 |
|
@ -1,49 +0,0 @@ |
|||||
--- |
|
||||
description: Enforce minimalist fixes for bugs/features; future-proofing requires prior discussion and strong evidence. |
|
||||
globs: "**/*" |
|
||||
alwaysApply: true |
|
||||
--- |
|
||||
|
|
||||
# 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. |
|
@ -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,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 |
@ -0,0 +1,53 @@ |
|||||
|
{ |
||||
|
// Markdownlint configuration for TimeSafari .cursor/rules |
||||
|
"config": { |
||||
|
// Core formatting rules that can be auto-fixed |
||||
|
"MD013": { |
||||
|
"line_length": 80, |
||||
|
"code_blocks": false, |
||||
|
"tables": false, |
||||
|
"headings": false |
||||
|
}, |
||||
|
"MD012": true, // No multiple consecutive blank lines |
||||
|
"MD022": true, // Headings should be surrounded by blank lines |
||||
|
"MD031": true, // Fenced code blocks should be surrounded by blank lines |
||||
|
"MD032": true, // Lists should be surrounded by blank lines |
||||
|
"MD047": true, // Files should end with a single newline |
||||
|
"MD009": true, // No trailing spaces |
||||
|
"MD010": true, // No hard tabs |
||||
|
"MD004": { "style": "dash" }, // Consistent list markers |
||||
|
"MD029": { "style": "ordered" }, // Ordered list item prefix |
||||
|
|
||||
|
// Disable rules that conflict with existing content structure |
||||
|
"MD041": false, // First line heading requirement |
||||
|
"MD025": false, // Multiple top-level headings |
||||
|
"MD024": false, // Duplicate headings |
||||
|
"MD036": false, // Emphasis as headings |
||||
|
"MD003": false, // Heading style consistency |
||||
|
"MD040": false, // Fenced code language |
||||
|
"MD055": false, // Table pipe style |
||||
|
"MD056": false, // Table column count |
||||
|
"MD034": false, // Bare URLs |
||||
|
"MD023": false // Heading indentation |
||||
|
}, |
||||
|
|
||||
|
"globs": [ |
||||
|
".cursor/rules/**/*.mdc", |
||||
|
"*.md", |
||||
|
"*.markdown", |
||||
|
"scripts/**/*.md", |
||||
|
"src/**/*.md", |
||||
|
"test-playwright/**/*.md", |
||||
|
"resources/**/*.md", |
||||
|
"doc/**/*.md", |
||||
|
"ios/**/*.md", |
||||
|
"electron/**/*.md" |
||||
|
], |
||||
|
"ignores": [ |
||||
|
"node_modules/**", |
||||
|
".git/**", |
||||
|
"**/node_modules/**", |
||||
|
"**/dist/**", |
||||
|
"**/build/**" |
||||
|
] |
||||
|
} |
@ -1 +1,27 @@ |
|||||
{"MD013": {"code_blocks": false}} |
{ |
||||
|
"MD013": { |
||||
|
"line_length": 80, |
||||
|
"code_blocks": false, |
||||
|
"tables": false, |
||||
|
"headings": false |
||||
|
}, |
||||
|
"MD012": true, |
||||
|
"MD022": true, |
||||
|
"MD031": true, |
||||
|
"MD032": true, |
||||
|
"MD047": true, |
||||
|
"MD009": true, |
||||
|
"MD010": true, |
||||
|
"MD004": { "style": "dash" }, |
||||
|
"MD029": { "style": "ordered" }, |
||||
|
"MD041": false, |
||||
|
"MD025": false, |
||||
|
"MD024": false, |
||||
|
"MD036": false, |
||||
|
"MD003": false, |
||||
|
"MD040": false, |
||||
|
"MD055": false, |
||||
|
"MD056": false, |
||||
|
"MD034": false, |
||||
|
"MD023": false |
||||
|
} |
File diff suppressed because it is too large
Loading…
Reference in new issue