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