crowd-funder-for-time-pwa/doc/meta_rule_usage_guide.md

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

## Workflow Flexibility: Phase-Based, Not Waterfall

**Important**: Meta-rules represent **workflow phases**, not a rigid sequence. You can:

### **Jump Between Phases Freely**
- **Start with diagnosis** if you already know the problem
- **Go back to research** if your fix reveals new issues  
- **Switch to planning** mid-implementation if scope changes
- **Document at any phase** - not just at the end

### **Mode Switching by Invoking Meta-Rules**
Each meta-rule invocation **automatically switches your workflow mode**:

```
Research Mode → Invoke @meta_bug_diagnosis → Diagnosis Mode
Diagnosis Mode → Invoke @meta_bug_fixing → Fixing Mode
Planning Mode → Invoke @meta_feature_implementation → Implementation Mode
```

### **Phase Constraints, Not Sequence Constraints**
- **Within each phase**: Clear constraints on what you can/cannot do
- **Between phases**: Complete freedom to move as needed
- **No forced order**: Choose the phase that matches your current need

### **Example of Flexible Workflow**
```
1. Start with @meta_research (investigation mode)
2. Jump to @meta_bug_diagnosis (diagnosis mode) 
3. Realize you need more research → back to @meta_research
4. Complete diagnosis → @meta_bug_fixing (implementation mode)
5. Find new issues → back to @meta_bug_diagnosis
6. Complete fix → @meta_documentation (documentation mode)
```

**The "sticky" part means**: Each phase has clear boundaries, but you control when to enter/exit phases.

## Practical Usage Examples

### **Example 1: Bug Investigation (Flexible Flow)**

**Scenario**: User reports that the contact list isn't loading properly

**Initial 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

**Flexible Workflow**:
1. Apply core always-on for foundation
2. Use research meta-rule for systematic investigation
3. Switch to bug diagnosis when you have enough evidence
4. **Can go back to research** if diagnosis reveals new questions
5. **Can jump to bug fixing** if root cause is obvious
6. **Can document findings** at any phase

### **Example 2: Feature Development (Iterative Flow)**

**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

**Iterative Workflow**:
1. Start with core always-on
2. Use feature planning for design and requirements
3. Switch to feature implementation for coding and testing
4. **Can return to planning** if implementation reveals design issues
5. **Can go back to research** if you need to investigate alternatives
6. **Can document progress** throughout the process

### **Example 3: Documentation Creation (Parallel Flow)**

**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

**Parallel Workflow**:
1. Apply core always-on for foundation
2. Use documentation meta-rule for educational content creation
3. **Can research** while documenting if you need more information
4. **Can plan** documentation structure as you write
5. **Can implement** examples or code snippets as needed
6. 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