# .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