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.
This commit is contained in:
Matthew Raymer
272
doc/meta_rule_usage_guide.md
Normal file
272
doc/meta_rule_usage_guide.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user