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