forked from jsnbuchanan/crowd-funder-for-time-pwa
c2aaf3a20d
- 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.
273 lines
9.1 KiB
Markdown
273 lines
9.1 KiB
Markdown
# 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
|