feat: Add documentation meta-rule system with educational focus

- Create meta_documentation.mdc for comprehensive doc workflows - Add meta_rule_usage_guide.md for practical meta-rule usage - Enhance existing markdown rules with educational standards - Transform docs from technical reference to educational resources Emphasizes human competence over technical description, provides systematic workflows for all documentation tasks.
2025-08-24 02:42:48 +00:00
parent 9967fe97e6
commit c2aaf3a20d
6 changed files with 644 additions and 22 deletions
--- a/.cursor/rules/README.md
+++ b/.cursor/rules/README.md
@@ -86,6 +86,7 @@ Rules for creating and maintaining documentation.
 - **`markdown_templates.mdc`** - Document templates and examples
 - **`markdown_workflow.mdc`** - Markdown validation and workflow
 - **`documentation.mdc`** - Documentation generation principles
+- **`meta_rule_usage_guide.md`** - How to use meta-rules in practice

 ### **`templates/`** - Templates and Examples

@@ -98,6 +99,7 @@ Template files and examples for various documentation types.
 High-level meta-rules that bundle related sub-rules for specific workflows.

 - **`meta_core_always_on.mdc`** - Core rules that apply to every single prompt
+- **`meta_documentation.mdc`** - Documentation writing and education workflow
 - **`meta_feature_planning.mdc`** - Feature planning workflow bundling
 - **`meta_bug_diagnosis.mdc`** - Bug investigation workflow bundling
 - **`meta_bug_fixing.mdc`** - Bug fix implementation workflow bundling
@@ -111,6 +113,8 @@ High-level meta-rules that bundle related sub-rules for specific workflows.
 3. **Context-Specific**: Use rules from appropriate subdirectories based on
   your task
 4. **Meta-Rules**: Use workflow-specific meta-rules for specialized tasks
+   - **Documentation**: Use `meta_documentation.mdc` for all documentation work
+   - **Getting Started**: See `docs/meta_rule_usage_guide.md` for comprehensive usage instructions
 5. **Cross-References**: All files contain updated cross-references to
   reflect the new structure
 6. **Validation**: All files pass markdown validation and maintain
@@ -125,6 +129,7 @@ High-level meta-rules that bundle related sub-rules for specific workflows.
 5. **Consistent cross-references** - All file links updated and working
 6. **Workflow bundling** - Meta-rules provide high-level workflow guidance
 7. **Feedback integration** - Built-in feedback mechanisms for continuous improvement
+8. **Educational focus** - Documentation emphasizes human competence over technical description

 ## File Naming Convention

--- a/.cursor/rules/core/harbor_pilot_universal.mdc
+++ b/.cursor/rules/core/harbor_pilot_universal.mdc
@@ -19,15 +19,12 @@
 ## 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
@@ -41,15 +38,12 @@ evidence-backed steps**.
 ### 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
@@ -57,11 +51,9 @@ evidence-backed steps**.
 - **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
@@ -70,23 +62,18 @@ 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**.
@@ -102,15 +89,12 @@ Follow this exact order **after** the Base Contract's **Objective → Result
 ### 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.
@@ -118,15 +102,12 @@ Follow this exact order **after** the Base Contract's **Objective → Result
 ### 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
@@ -182,17 +163,14 @@ Before publishing, verify:
 ### 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
--- a/.cursor/rules/docs/markdown_core.mdc
+++ b/.cursor/rules/docs/markdown_core.mdc
@@ -10,6 +10,9 @@ This file combines core markdown formatting standards with automation
 guidelines. AI agents must follow these rules DURING content generation,
 not apply them after the fact.

+**Primary Focus**: Create educational content that increases human
+competence, not just technical descriptions.
+
 ## AI Generation Guidelines

 ### **MANDATORY**: Follow These Rules While Writing
@@ -21,6 +24,8 @@ When generating markdown content, you MUST:
   code blocks
 3. **Structure**: Use proper heading hierarchy and document templates
 4. **Formatting**: Apply consistent formatting patterns immediately
+5. **Educational Value**: Focus on increasing reader competence and
+   understanding

 ### **DO NOT**: Generate content that violates these rules

@@ -28,6 +33,8 @@ When generating markdown content, you MUST:
 - ❌ Create content without proper blank line spacing
 - ❌ Use inconsistent formatting patterns
 - ❌ Assume post-processing will fix violations
+- ❌ Focus only on technical details without educational context
+- ❌ Assume reader has extensive prior knowledge

 ### **DO**: Generate compliant content from the start

@@ -35,6 +42,9 @@ When generating markdown content, you MUST:
 - ✅ Add blank lines around all structural elements
 - ✅ Use established templates and patterns
 - ✅ Apply formatting standards immediately
+- ✅ Explain concepts before implementation details
+- ✅ Provide context and motivation for technical choices
+- ✅ Include examples that illustrate key concepts

 ## Core Formatting Standards

@@ -99,6 +109,24 @@ When generating markdown content, you MUST:
 - **Indentation**: 2 spaces for nested items
 - **Blank lines**: Surround lists with blank lines

+## Educational Content Standards
+
+### **Content Structure for Learning**
+
+- **Concept First**: Explain what something is before how to use it
+- **Context Matters**: Explain why and when to use a feature
+- **Progressive Disclosure**: Start simple, add complexity gradually
+- **Real Examples**: Use concrete, relatable scenarios
+- **Common Questions**: Anticipate and answer reader questions
+
+### **Writing for Understanding**
+
+- **Conversational Tone**: Write as if explaining to a colleague
+- **Active Voice**: "You can do this" not "This can be done"
+- **Question Format**: "What happens when..." to engage thinking
+- **Analogies**: Use familiar concepts to explain complex ideas
+- **Limitations**: Clearly state what solutions don't do
+
 ## Code Block Standards

 ### Inline Code
@@ -146,6 +174,8 @@ When generating markdown content, you MUST:
 - [ ] **Headings**: Use ATX-style with proper hierarchy (H1 for title only)
 - [ ] **Lists**: Use consistent markers (- for unordered, 1. for ordered)
 - [ ] **Code**: Specify language for fenced blocks, use backticks for inline
+- [ ] **Educational Focus**: Plan content structure for learning progression
+- [ ] **Audience Consideration**: Identify target reader knowledge level

 ### After Generating Markdown Content

@@ -153,6 +183,8 @@ When generating markdown content, you MUST:
 - [ ] **Auto-fix**: Use `npm run markdown:fix` if any issues found
 - [ ] **Review**: Confirm content follows established templates and patterns
 - [ ] **Cross-reference**: Link to related documentation and templates
+- [ ] **Educational Review**: Verify content increases reader competence
+- [ ] **Example Validation**: Ensure examples illustrate key concepts clearly

 ### Quality Assurance

@@ -160,11 +192,14 @@ When generating markdown content, you MUST:
 - [ ] **Consistency**: Formatting matches existing documentation style
 - [ ] **Completeness**: All required sections and information included
 - [ ] **Accuracy**: Technical details are correct and up-to-date
+- [ ] **Educational Value**: Content increases reader understanding and competence
+- [ ] **Context Clarity**: Reader understands when and why to use the information

 ---

 **See also**:

+- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow
 - `.cursor/rules/docs/markdown_templates.mdc` for document templates
 - `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows

--- a/.cursor/rules/docs/markdown_templates.mdc
+++ b/.cursor/rules/docs/markdown_templates.mdc
@@ -2,6 +2,9 @@

 > **Agent role**: Reference this file for document templates, structure,
 > and examples when creating new documentation.
+>
+> **Focus**: Create educational content that increases human competence,
+> not just technical descriptions.

 ## Document Templates

@@ -18,10 +21,16 @@

 Brief description of the document's purpose and scope.

+**Educational Goal**: What will the reader learn and how will it increase
+their competence?
+
 ## Current State

 Description of current situation or problem.

+**Why This Matters**: Explain the business value and user benefit of
+addressing this situation.
+
 ## Implementation Plan

 ### Phase 1: Foundation
@@ -29,12 +38,18 @@ Description of current situation or problem.
 - [ ] Task 1
 - [ ] Task 2

+**Learning Context**: What concepts should the reader understand before
+proceeding with implementation?
+
 ## Next Steps

 1. **Review and approve plan**
 2. **Begin implementation**
 3. **Test and validate**

+**Continued Learning**: Where can the reader go next to deepen their
+understanding?
+
 ---

 **Status**: Ready for implementation
@@ -57,6 +72,9 @@ Description of current situation or problem.

 Brief description of the technical specification.

+**Business Context**: Why is this specification needed and what problem
+does it solve for users?
+
 ## Requirements

 ### Functional Requirements
@@ -75,6 +93,9 @@ Brief description of the technical specification.

 Description of the technical architecture.

+**Design Rationale**: Why was this architecture chosen over alternatives?
+What are the trade-offs and benefits?
+
 ### Data Models

 ```typescript
@@ -98,6 +119,79 @@ interface APIResponse<T> {
 ## Testing Strategy

 - [ ] Unit tests
+
+**Learning from Testing**: What insights does testing provide about the
+system's behavior and design?
+
+---
+
+## Educational Documentation Template
+
+### **Concept Explanation Template**
+
+```markdown
+## What is [Concept Name]?
+
+Brief, clear definition of the concept.
+
+## Why Does [Concept Name] Matter?
+
+Explain the business value and user benefit.
+
+## How Does [Concept Name] Work?
+
+High-level explanation of the mechanism.
+
+## When Would You Use [Concept Name]?
+
+Real-world scenarios and use cases.
+
+## Common Misconceptions
+
+Address typical misunderstandings.
+
+## Examples
+
+Concrete examples that illustrate the concept.
+
+## Next Steps
+
+Where to learn more about related concepts.
+```
+
+### **Tutorial Template**
+
+```markdown
+## Learning Objective
+
+What the reader will accomplish by the end.
+
+## Prerequisites
+
+What the reader should know before starting.
+
+## Step-by-Step Guide
+
+1. **Step 1**: What to do and why
+2. **Step 2**: What to do and why
+3. **Step 3**: What to do and why
+
+## Verification
+
+How to confirm the tutorial was successful.
+
+## Troubleshooting
+
+Common issues and how to resolve them.
+
+## What You've Learned
+
+Summary of key concepts and skills.
+
+## Next Steps
+
+Where to apply this knowledge next.
+```
 - [ ] Integration tests
 - [ ] E2E tests

@@ -209,6 +303,7 @@ Standard implementation plans follow Phase 1 (Foundation), Phase 2

 **See also**:

+- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow
 - `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
 - `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows

--- a/.cursor/rules/meta_documentation.mdc
+++ b/.cursor/rules/meta_documentation.mdc
@@ -0,0 +1,237 @@
+# Meta-Rule: Documentation Writing & Education
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Documentation writing and education workflow
+
+## Purpose
+
+This meta-rule bundles documentation-related rules to create comprehensive,
+educational documentation that increases human competence rather than just
+providing technical descriptions.
+
+## When to Use
+
+**Use this meta-rule when**:
+- Writing new documentation
+- Updating existing documentation
+- Creating technical guides
+- Writing migration documentation
+- Creating architectural documentation
+- Writing user guides or tutorials
+
+## Bundled Rules
+
+### **Core Documentation Standards**
+
+- **`docs/markdown_core.mdc`** - Core markdown formatting and automation
+- **`docs/markdown_templates.mdc`** - Document templates and structure
+- **`docs/markdown_workflow.mdc`** - Documentation validation workflows
+
+### **Documentation Principles**
+
+- **`core/base_context.mdc`** - Human competence first principles
+- **`core/less_complex.mdc`** - Minimalist solution guidelines
+- **`development/software_development.mdc`** - Development documentation standards
+
+### **Context-Specific Rules**
+
+- **`app/timesafari.mdc`** - TimeSafari application context
+- **`app/timesafari_development.mdc`** - Development documentation patterns
+- **`architecture/architectural_patterns.mdc`** - Architecture documentation
+
+## Core Documentation Philosophy
+
+### **Education Over Technical Description**
+
+**Primary Goal**: Increase human competence and understanding
+**Secondary Goal**: Provide accurate technical information
+**Approach**: Explain the "why" before the "how"
+
+### **Human Competence Principles**
+
+1. **Context First**: Explain the problem before the solution
+2. **Learning Path**: Structure content for progressive understanding
+3. **Real Examples**: Use concrete, relatable examples
+4. **Common Pitfalls**: Warn about typical mistakes and misconceptions
+5. **Decision Context**: Explain why certain choices were made
+
+### **Documentation Hierarchy**
+
+1. **Conceptual Understanding** - What is this and why does it matter?
+2. **Context and Motivation** - When and why would you use this?
+3. **Technical Implementation** - How do you implement it?
+4. **Examples and Patterns** - What does it look like in practice?
+5. **Troubleshooting** - What can go wrong and how to fix it?
+
+## Implementation Guidelines
+
+### **Document Structure**
+
+**Mandatory Sections**:
+- **Overview**: Clear purpose and scope with educational context
+- **Why This Matters**: Business value and user benefit explanation
+- **Core Concepts**: Fundamental understanding before implementation
+- **Implementation**: Step-by-step technical guidance
+- **Examples**: Real-world usage patterns
+- **Common Issues**: Troubleshooting and prevention
+- **Next Steps**: Where to go from here
+
+**Optional Sections**:
+- **Background**: Historical context and evolution
+- **Alternatives**: Other approaches and trade-offs
+- **Advanced Topics**: Deep dive into complex scenarios
+- **References**: Additional learning resources
+
+### **Writing Style**
+
+**Educational Approach**:
+- **Conversational tone**: Write as if explaining to a colleague
+- **Progressive disclosure**: Start simple, add complexity gradually
+- **Active voice**: "You can do this" not "This can be done"
+- **Question format**: "What happens when..." to engage thinking
+- **Analogies**: Use familiar concepts to explain complex ideas
+
+**Technical Accuracy**:
+- **Precise language**: Use exact technical terms consistently
+- **Code examples**: Working, tested code snippets
+- **Version information**: Specify applicable versions and platforms
+- **Limitations**: Clearly state what the solution doesn't do
+
+### **Content Quality Standards**
+
+**Educational Value**:
+- [ ] **Concept clarity**: Reader understands the fundamental idea
+- [ ] **Context relevance**: Reader knows when to apply the knowledge
+- [ ] **Practical application**: Reader can implement the solution
+- [ ] **Problem prevention**: Reader avoids common mistakes
+- [ ] **Next steps**: Reader knows where to continue learning
+
+**Technical Accuracy**:
+- [ ] **Fact verification**: All technical details are correct
+- [ ] **Code validation**: Examples compile and run correctly
+- [ ] **Version compatibility**: Platform and version requirements clear
+- [ ] **Security consideration**: Security implications addressed
+- [ ] **Performance notes**: Performance characteristics documented
+
+## Document Types and Templates
+
+### **Technical Guides**
+
+**Focus**: Implementation and technical details
+**Structure**: Problem → Solution → Implementation → Examples
+**Education**: Explain the "why" behind technical choices
+
+### **Migration Documentation**
+
+**Focus**: Process and workflow guidance
+**Structure**: Context → Preparation → Steps → Validation → Troubleshooting
+**Education**: Help users understand migration benefits and risks
+
+### **Architecture Documentation**
+
+**Focus**: System design and decision rationale
+**Structure**: Problem → Constraints → Alternatives → Decision → Implementation
+**Education**: Explain design trade-offs and decision factors
+
+### **User Guides**
+
+**Focus**: Task completion and user empowerment
+**Structure**: Goal → Prerequisites → Steps → Verification → Next Steps
+**Education**: Help users understand the system's capabilities
+
+## Quality Assurance
+
+### **Review Checklist**
+
+**Educational Quality**:
+- [ ] **Clear learning objective**: What will the reader learn?
+- [ ] **Appropriate complexity**: Matches target audience knowledge
+- [ ] **Progressive disclosure**: Information builds logically
+- [ ] **Practical examples**: Real-world scenarios and use cases
+- [ ] **Common questions**: Anticipates and answers reader questions
+
+**Technical Quality**:
+- [ ] **Accuracy**: All technical details verified
+- [ ] **Completeness**: Covers all necessary information
+- [ ] **Consistency**: Terminology and formatting consistent
+- [ ] **Currency**: Information is up-to-date
+- [ ] **Accessibility**: Clear for target audience
+
+### **Validation Workflows**
+
+1. **Content Review**: Subject matter expert review
+2. **Educational Review**: Learning effectiveness assessment
+3. **Technical Review**: Accuracy and completeness validation
+4. **User Testing**: Real user comprehension testing
+5. **Continuous Improvement**: Regular updates based on feedback
+
+## Success Metrics
+
+### **Educational Effectiveness**
+
+- **Comprehension**: Users understand the concepts
+- **Application**: Users can implement the solutions
+- **Confidence**: Users feel capable and empowered
+- **Efficiency**: Users complete tasks faster
+- **Satisfaction**: Users find documentation helpful
+
+### **Technical Quality**
+
+- **Accuracy**: Zero technical errors
+- **Completeness**: All necessary information included
+- **Consistency**: Uniform style and format
+- **Maintainability**: Easy to update and extend
+- **Accessibility**: Clear for target audience
+
+## Common Pitfalls
+
+### **Educational Mistakes**
+
+- **Assumption overload**: Assuming too much prior knowledge
+- **Information dump**: Overwhelming with details
+- **Context missing**: Not explaining why something matters
+- **Example poverty**: Insufficient practical examples
+- **Feedback missing**: No way to verify understanding
+
+### **Technical Mistakes**
+
+- **Outdated information**: Not keeping content current
+- **Incomplete coverage**: Missing important details
+- **Inconsistent terminology**: Using different terms for same concepts
+- **Poor examples**: Non-working or confusing code
+- **Missing validation**: No way to verify correctness
+
+## Feedback and Improvement
+
+### **Continuous Learning**
+
+- **User feedback**: Collect and analyze user comments
+- **Usage metrics**: Track document usage and effectiveness
+- **Review cycles**: Regular content review and updates
+- **Community input**: Engage users in documentation improvement
+- **Best practices**: Stay current with documentation standards
+
+### **Quality Metrics**
+
+- **Readability scores**: Measure content clarity
+- **User satisfaction**: Survey-based quality assessment
+- **Task completion**: Success rate of documented procedures
+- **Support reduction**: Decrease in help requests
+- **Knowledge retention**: Long-term user understanding
+
+---
+
+**See also**:
+
+- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
+- `.cursor/rules/docs/markdown_templates.mdc` for document templates
+- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows
+- `.cursor/rules/docs/meta_rule_usage_guide.md` for how to use meta-rules
+- `.cursor/rules/core/base_context.mdc` for human competence principles
+
+**Status**: Active documentation meta-rule
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: Documentation team, Development team, Users
--- a/doc/meta_rule_usage_guide.md
+++ b/doc/meta_rule_usage_guide.md
@@ -0,0 +1,272 @@
+# Meta-Rule Usage Guide: How to Use Meta-Rules in Practice
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Comprehensive meta-rule usage guide
+
+## Overview
+
+This guide explains how to use the TimeSafari meta-rule system in practice.
+Meta-rules are high-level rule bundles that provide workflow-specific guidance
+for different types of tasks.
+
+**Educational Goal**: Help developers understand when and how to apply
+meta-rules to maximize their effectiveness and avoid common mistakes.
+
+## Why Meta-Rules Matter
+
+**Meta-rules solve the problem of rule overload** by bundling related rules
+into logical workflows. Instead of manually selecting 10+ individual rules,
+you apply 1-3 meta-rules that automatically include everything you need.
+
+### **Benefits of Using Meta-Rules**
+
+- **Faster Setup**: No need to manually select individual rules
+- **Better Coverage**: Ensures you don't miss important rules
+- **Workflow Consistency**: Standardized approaches across the team
+- **Learning Efficiency**: Learn workflows, not individual rules
+- **Quality Assurance**: Built-in validation and feedback mechanisms
+
+## Meta-Rule Selection Strategy
+
+### **Step 1: Always Start with Core Always-On**
+
+**Every single interaction** starts with:
+```
+meta_core_always_on.mdc
+```
+
+This provides the foundation: human competence principles, time standards,
+version control, and application context.
+
+### **Step 2: Identify Your Primary Task Type**
+
+Choose the meta-rule that matches your main objective:
+
+| **Task Type** | **Primary Meta-Rule** | **When to Use** |
+|---------------|------------------------|------------------|
+| **Research/Investigation** | `meta_research.mdc` | Bug diagnosis, feasibility research, code analysis |
+| **Feature Planning** | `meta_feature_planning.mdc` | New feature design, requirements analysis |
+| **Feature Implementation** | `meta_feature_implementation.mdc` | Building features, coding, testing |
+| **Bug Diagnosis** | `meta_bug_diagnosis.mdc` | Investigating issues, root cause analysis |
+| **Bug Fixing** | `meta_bug_fixing.mdc` | Implementing fixes, validation |
+| **Documentation** | `meta_documentation.mdc` | Writing docs, creating guides, tutorials |
+
+### **Step 3: Add Context-Specific Meta-Rules (Optional)**
+
+For complex tasks, you might combine multiple meta-rules:
+
+```
+meta_core_always_on + meta_research + meta_bug_diagnosis
+```
+
+## Practical Usage Examples
+
+### **Example 1: Bug Investigation**
+
+**Scenario**: User reports that the contact list isn't loading properly
+
+**Meta-Rule Selection**:
+```
+meta_core_always_on + meta_research + meta_bug_diagnosis
+```
+
+**What This Gives You**:
+- **Core Always-On**: Human competence focus, time standards, context
+- **Research**: Systematic investigation methodology, evidence collection
+- **Bug Diagnosis**: Defect analysis framework, root cause identification
+
+**Workflow**:
+1. Apply core always-on for foundation
+2. Use research meta-rule for systematic investigation
+3. Apply bug diagnosis for defect analysis
+4. Follow the bundled workflow automatically
+
+### **Example 2: Feature Development**
+
+**Scenario**: Building a new contact search feature
+
+**Meta-Rule Selection**:
+```
+meta_core_always_on + meta_feature_planning + meta_feature_implementation
+```
+
+**What This Gives You**:
+- **Core Always-On**: Foundation principles and context
+- **Feature Planning**: Requirements analysis, architecture planning
+- **Feature Implementation**: Development workflow, testing strategy
+
+**Workflow**:
+1. Start with core always-on
+2. Use feature planning for design and requirements
+3. Switch to feature implementation for coding and testing
+
+### **Example 3: Documentation Creation**
+
+**Scenario**: Writing a migration guide for the new database system
+
+**Meta-Rule Selection**:
+```
+meta_core_always_on + meta_documentation
+```
+
+**What This Gives You**:
+- **Core Always-On**: Foundation and context
+- **Documentation**: Educational focus, templates, quality standards
+
+**Workflow**:
+1. Apply core always-on for foundation
+2. Use documentation meta-rule for educational content creation
+3. Follow educational templates and quality standards
+
+## Meta-Rule Application Process
+
+### **1. Load the Meta-Rule**
+
+When you start a task, explicitly state which meta-rules you're applying:
+
+```
+"I'm applying meta_core_always_on + meta_research for this bug investigation."
+```
+
+### **2. Follow the Bundled Workflow**
+
+Each meta-rule provides a complete workflow. Follow it step-by-step:
+
+- **Research Meta-Rule**: Investigation → Evidence → Analysis → Conclusion
+- **Feature Planning**: Requirements → Architecture → Strategy → Validation
+- **Bug Diagnosis**: Problem → Evidence → Root Cause → Solution
+
+### **3. Use the Bundled Rules**
+
+Meta-rules automatically include all necessary sub-rules. You don't need to
+manually select individual rules - they're already bundled.
+
+### **4. Validate Against Success Criteria**
+
+Each meta-rule includes success criteria. Use these to validate your work:
+
+- [ ] **Educational Quality**: Content increases human competence
+- [ ] **Technical Quality**: All technical details are accurate
+- [ ] **Workflow Completion**: All required steps completed
+- [ ] **Quality Standards**: Meets defined quality criteria
+
+## Common Meta-Rule Combinations
+
+### **Research + Diagnosis**
+```
+meta_core_always_on + meta_research + meta_bug_diagnosis
+```
+**Use for**: Complex bug investigations requiring systematic analysis
+
+### **Planning + Implementation**
+```
+meta_core_always_on + meta_feature_planning + meta_feature_implementation
+```
+**Use for**: End-to-end feature development from concept to deployment
+
+### **Research + Planning**
+```
+meta_core_always_on + meta_research + meta_feature_planning
+```
+**Use for**: Feasibility research and solution design
+
+### **Documentation + Context**
+```
+meta_core_always_on + meta_documentation + [context-specific]
+```
+**Use for**: Creating comprehensive, educational documentation
+
+## Best Practices
+
+### **✅ Do These Things**
+
+- **Always start with core always-on** - it's the foundation
+- **Choose the primary meta-rule** that matches your main task
+- **Follow the bundled workflow** step-by-step
+- **Use success criteria** to validate your work
+- **Collect feedback** on meta-rule effectiveness
+
+### **❌ Avoid These Mistakes**
+
+- **Don't skip core always-on** - you'll lose the foundation
+- **Don't apply too many meta-rules** - stick to 2-3 maximum
+- **Don't ignore the bundled workflow** - follow it systematically
+- **Don't forget validation** - use the success criteria
+- **Don't skip feedback collection** - it improves the system
+
+## Troubleshooting Common Issues
+
+### **Problem**: Meta-rules seem to conflict
+
+**Solution**: Meta-rules are designed to work together. If you see conflicts,
+you're probably applying too many. Stick to 2-3 meta-rules maximum.
+
+### **Problem**: I don't know which meta-rule to use
+
+**Solution**: Start with your primary task type. If you're investigating a bug,
+use research + bug diagnosis. If you're building a feature, use feature
+planning + implementation.
+
+### **Problem**: The meta-rule workflow seems too complex
+
+**Solution**: Meta-rules bundle complexity into manageable workflows. Follow
+the steps one at a time. The complexity is already organized for you.
+
+### **Problem**: I'm not seeing the expected behavior
+
+**Solution**: Ensure you're following the meta-rule workflow step-by-step.
+Meta-rules provide guidance, but you still need to execute the workflow.
+
+## Feedback and Improvement
+
+### **Rate Your Experience**
+
+After using a meta-rule, provide feedback:
+
+- **Effectiveness**: How well did the meta-rule work? (1-5 scale)
+- **Time Saved**: How much time did it save you?
+- **Quality Improvement**: Did it improve your work quality?
+- **Recommendation**: Would you recommend it to others?
+
+### **Continuous Improvement**
+
+Meta-rules evolve based on feedback:
+
+- **Usage patterns** - How teams use the rules
+- **Effectiveness ratings** - What works and what doesn't
+- **Integration feedback** - How well rules work together
+- **Quality metrics** - Impact on work quality
+
+## Quick Reference
+
+### **Meta-Rule Selection Matrix**
+
+| **Task** | **Primary** | **Secondary** | **Tertiary** |
+|----------|-------------|---------------|---------------|
+| **Bug Investigation** | `meta_research` | `meta_bug_diagnosis` | - |
+| **Feature Development** | `meta_feature_planning` | `meta_feature_implementation` | - |
+| **Documentation** | `meta_documentation` | - | - |
+| **Complex Research** | `meta_research` | `meta_bug_diagnosis` | `meta_feature_planning` |
+
+### **Always Remember**
+
+1. **Start with core always-on** - foundation for everything
+2. **Choose your primary meta-rule** - matches your main task
+3. **Follow the bundled workflow** - step-by-step execution
+4. **Validate against success criteria** - ensure quality
+5. **Provide feedback** - help improve the system
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_rule_architecture.md` for meta-rule structure overview
+- `.cursor/rules/meta_core_always_on.mdc` for foundation rules
+- `.cursor/rules/README.md` for complete rule organization
+
+**Status**: Active usage guide
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All meta-rules
+**Stakeholders**: Development team, Documentation team