Browse Source
- 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.master
Matthew Raymer
1 day ago
6 changed files with 644 additions and 22 deletions
@ -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 |
|||
@ -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 |
|||
Loading…
Reference in new issue