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.
2025-08-24 02:42:48 +00:00
parent 9967fe97e6
commit c2aaf3a20d
6 changed files with 644 additions and 22 deletions
--- a/.cursor/rules/README.md
+++ b/.cursor/rules/README.md
@@ -86,6 +86,7 @@ Rules for creating and maintaining documentation.
 - **`markdown_templates.mdc`** - Document templates and examples
 - **`markdown_workflow.mdc`** - Markdown validation and workflow
 - **`documentation.mdc`** - Documentation generation principles
+- **`meta_rule_usage_guide.md`** - How to use meta-rules in practice

 ### **`templates/`** - Templates and Examples

@@ -98,6 +99,7 @@ Template files and examples for various documentation types.
 High-level meta-rules that bundle related sub-rules for specific workflows.

 - **`meta_core_always_on.mdc`** - Core rules that apply to every single prompt
+- **`meta_documentation.mdc`** - Documentation writing and education workflow
 - **`meta_feature_planning.mdc`** - Feature planning workflow bundling
 - **`meta_bug_diagnosis.mdc`** - Bug investigation workflow bundling
 - **`meta_bug_fixing.mdc`** - Bug fix implementation workflow bundling
@@ -111,6 +113,8 @@ High-level meta-rules that bundle related sub-rules for specific workflows.
 3. **Context-Specific**: Use rules from appropriate subdirectories based on
   your task
 4. **Meta-Rules**: Use workflow-specific meta-rules for specialized tasks
+   - **Documentation**: Use `meta_documentation.mdc` for all documentation work
+   - **Getting Started**: See `docs/meta_rule_usage_guide.md` for comprehensive usage instructions
 5. **Cross-References**: All files contain updated cross-references to
   reflect the new structure
 6. **Validation**: All files pass markdown validation and maintain
@@ -125,6 +129,7 @@ High-level meta-rules that bundle related sub-rules for specific workflows.
 5. **Consistent cross-references** - All file links updated and working
 6. **Workflow bundling** - Meta-rules provide high-level workflow guidance
 7. **Feedback integration** - Built-in feedback mechanisms for continuous improvement
+8. **Educational focus** - Documentation emphasizes human competence over technical description

 ## File Naming Convention

--- a/.cursor/rules/core/harbor_pilot_universal.mdc
+++ b/.cursor/rules/core/harbor_pilot_universal.mdc
@@ -19,15 +19,12 @@
 ## Purpose

 - **Purpose fit**: Prioritizes human competence and collaboration while
-
  delivering reproducible artifacts.

 - **Output Contract**: This directive **adds universal constraints** for any
-
  technical topic while **inheriting** the Base Context contract sections.

 - **Toggles honored**: Uses the same toggle semantics; defaults above can be
-
  overridden by the caller.

 ## Core Directive
@@ -41,15 +38,12 @@ evidence-backed steps**.
 ### 1. Time & Date Standards

 - Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid
-
  "today/yesterday".

 - Include at least **one diagram** (Mermaid preferred). Choose the most
-
  fitting type:

  - `sequenceDiagram` (protocols/flows), `flowchart`, `stateDiagram`,
-
    `gantt` (timelines), or `classDiagram` (schemas).

 ### 2. Evidence Requirements
@@ -57,11 +51,9 @@ evidence-backed steps**.
 - **Reproducible Steps**: Every claim must have copy-paste commands

 - **Verifiable Outputs**: Include expected results, status codes, or
-
  error messages

 - **Cite evidence** for *Works/Doesn't* items (timestamps, filenames,
-
  line numbers, IDs/status codes, or logs).

 ## Required Sections
@@ -70,23 +62,18 @@ Follow this exact order **after** the Base Contract's **Objective → Result
 → Use/Run** headers:

 1. **Artifacts & Links** - Repos/PRs, design docs, datasets/HARs/pcaps,
-
   scripts/tools, dashboards.

 2. **Environment & Preconditions** - OS/runtime, versions/build IDs,
-
   services/endpoints/URLs, credentials/auth mode.

 3. **Architecture / Process Overview** - Short prose + **one diagram**
-
   selected from the list above.

 4. **Interfaces & Contracts** - Choose one: API-based (endpoint table),
-
   Data/Files (I/O contract), or Systems/Hardware (interfaces).

 5. **Repro: End-to-End Procedure** - Minimal copy-paste steps with
-
   code/commands and **expected outputs**.
 6. **What Works (with Evidence)** - Each item: **Time (UTC)** •
   **Artifact/Req IDs** • **Status/Result** • **Where to verify**.
@@ -102,15 +89,12 @@ Follow this exact order **after** the Base Contract's **Objective → Result
 ### Do

 - **Do** quantify progress only against a defined scope with acceptance
-
  criteria.

 - **Do** include minimal sample payloads/headers or I/O schemas; redact
-
  sensitive values.

 - **Do** keep commentary lean; if timeboxed, move depth to **Deferred
-
  for depth**.

 - **Do** use specific, actionable language that guides implementation.
@@ -118,15 +102,12 @@ Follow this exact order **after** the Base Contract's **Objective → Result
 ### Don't

 - **Don't** use marketing language or meta narration ("Perfect!",
-
  "tool called", "new chat").

 - **Don't** include IDE-specific chatter or internal rules unrelated to
-
  the task.

 - **Don't** assume reader knowledge; provide context for all technical
-
  decisions.

 ## Model Implementation Checklist
@@ -182,17 +163,14 @@ Before publishing, verify:
 ### Competence Hooks

 - **Why this works**: Structured approach ensures completeness and
-
  reproducibility

 - **Common pitfalls**: Skipping evidence requirements, vague language

 - **Next skill unlock**: Practice creating Mermaid diagrams for different
-
  use cases

 - **Teach-back**: Explain how you would validate this guide's
-
  reproducibility

 ### Collaboration Hooks
--- a/.cursor/rules/docs/markdown_core.mdc
+++ b/.cursor/rules/docs/markdown_core.mdc
@@ -10,6 +10,9 @@ This file combines core markdown formatting standards with automation
 guidelines. AI agents must follow these rules DURING content generation,
 not apply them after the fact.

+**Primary Focus**: Create educational content that increases human
+competence, not just technical descriptions.
+
 ## AI Generation Guidelines

 ### **MANDATORY**: Follow These Rules While Writing
@@ -21,6 +24,8 @@ When generating markdown content, you MUST:
   code blocks
 3. **Structure**: Use proper heading hierarchy and document templates
 4. **Formatting**: Apply consistent formatting patterns immediately
+5. **Educational Value**: Focus on increasing reader competence and
+   understanding

 ### **DO NOT**: Generate content that violates these rules

@@ -28,6 +33,8 @@ When generating markdown content, you MUST:
 - ❌ Create content without proper blank line spacing
 - ❌ Use inconsistent formatting patterns
 - ❌ Assume post-processing will fix violations
+- ❌ Focus only on technical details without educational context
+- ❌ Assume reader has extensive prior knowledge

 ### **DO**: Generate compliant content from the start

@@ -35,6 +42,9 @@ When generating markdown content, you MUST:
 - ✅ Add blank lines around all structural elements
 - ✅ Use established templates and patterns
 - ✅ Apply formatting standards immediately
+- ✅ Explain concepts before implementation details
+- ✅ Provide context and motivation for technical choices
+- ✅ Include examples that illustrate key concepts

 ## Core Formatting Standards

@@ -99,6 +109,24 @@ When generating markdown content, you MUST:
 - **Indentation**: 2 spaces for nested items
 - **Blank lines**: Surround lists with blank lines

+## Educational Content Standards
+
+### **Content Structure for Learning**
+
+- **Concept First**: Explain what something is before how to use it
+- **Context Matters**: Explain why and when to use a feature
+- **Progressive Disclosure**: Start simple, add complexity gradually
+- **Real Examples**: Use concrete, relatable scenarios
+- **Common Questions**: Anticipate and answer reader questions
+
+### **Writing for Understanding**
+
+- **Conversational Tone**: Write as if explaining to a colleague
+- **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
+- **Limitations**: Clearly state what solutions don't do
+
 ## Code Block Standards

 ### Inline Code
@@ -146,6 +174,8 @@ When generating markdown content, you MUST:
 - [ ] **Headings**: Use ATX-style with proper hierarchy (H1 for title only)
 - [ ] **Lists**: Use consistent markers (- for unordered, 1. for ordered)
 - [ ] **Code**: Specify language for fenced blocks, use backticks for inline
+- [ ] **Educational Focus**: Plan content structure for learning progression
+- [ ] **Audience Consideration**: Identify target reader knowledge level

 ### After Generating Markdown Content

@@ -153,6 +183,8 @@ When generating markdown content, you MUST:
 - [ ] **Auto-fix**: Use `npm run markdown:fix` if any issues found
 - [ ] **Review**: Confirm content follows established templates and patterns
 - [ ] **Cross-reference**: Link to related documentation and templates
+- [ ] **Educational Review**: Verify content increases reader competence
+- [ ] **Example Validation**: Ensure examples illustrate key concepts clearly

 ### Quality Assurance

@@ -160,11 +192,14 @@ When generating markdown content, you MUST:
 - [ ] **Consistency**: Formatting matches existing documentation style
 - [ ] **Completeness**: All required sections and information included
 - [ ] **Accuracy**: Technical details are correct and up-to-date
+- [ ] **Educational Value**: Content increases reader understanding and competence
+- [ ] **Context Clarity**: Reader understands when and why to use the information

 ---

 **See also**:

+- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow
 - `.cursor/rules/docs/markdown_templates.mdc` for document templates
 - `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows

--- a/.cursor/rules/docs/markdown_templates.mdc
+++ b/.cursor/rules/docs/markdown_templates.mdc
@@ -2,6 +2,9 @@

 > **Agent role**: Reference this file for document templates, structure,
 > and examples when creating new documentation.
+>
+> **Focus**: Create educational content that increases human competence,
+> not just technical descriptions.

 ## Document Templates

@@ -18,10 +21,16 @@

 Brief description of the document's purpose and scope.

+**Educational Goal**: What will the reader learn and how will it increase
+their competence?
+
 ## Current State

 Description of current situation or problem.

+**Why This Matters**: Explain the business value and user benefit of
+addressing this situation.
+
 ## Implementation Plan

 ### Phase 1: Foundation
@@ -29,12 +38,18 @@ Description of current situation or problem.
 - [ ] Task 1
 - [ ] Task 2

+**Learning Context**: What concepts should the reader understand before
+proceeding with implementation?
+
 ## Next Steps

 1. **Review and approve plan**
 2. **Begin implementation**
 3. **Test and validate**

+**Continued Learning**: Where can the reader go next to deepen their
+understanding?
+
 ---

 **Status**: Ready for implementation
@@ -57,6 +72,9 @@ Description of current situation or problem.

 Brief description of the technical specification.

+**Business Context**: Why is this specification needed and what problem
+does it solve for users?
+
 ## Requirements

 ### Functional Requirements
@@ -75,6 +93,9 @@ Brief description of the technical specification.

 Description of the technical architecture.

+**Design Rationale**: Why was this architecture chosen over alternatives?
+What are the trade-offs and benefits?
+
 ### Data Models

 ```typescript
@@ -98,6 +119,79 @@ interface APIResponse<T> {
 ## Testing Strategy

 - [ ] Unit tests
+
+**Learning from Testing**: What insights does testing provide about the
+system's behavior and design?
+
+---
+
+## Educational Documentation Template
+
+### **Concept Explanation Template**
+
+```markdown
+## What is [Concept Name]?
+
+Brief, clear definition of the concept.
+
+## Why Does [Concept Name] Matter?
+
+Explain the business value and user benefit.
+
+## How Does [Concept Name] Work?
+
+High-level explanation of the mechanism.
+
+## When Would You Use [Concept Name]?
+
+Real-world scenarios and use cases.
+
+## Common Misconceptions
+
+Address typical misunderstandings.
+
+## Examples
+
+Concrete examples that illustrate the concept.
+
+## Next Steps
+
+Where to learn more about related concepts.
+```
+
+### **Tutorial Template**
+
+```markdown
+## Learning Objective
+
+What the reader will accomplish by the end.
+
+## Prerequisites
+
+What the reader should know before starting.
+
+## Step-by-Step Guide
+
+1. **Step 1**: What to do and why
+2. **Step 2**: What to do and why
+3. **Step 3**: What to do and why
+
+## Verification
+
+How to confirm the tutorial was successful.
+
+## Troubleshooting
+
+Common issues and how to resolve them.
+
+## What You've Learned
+
+Summary of key concepts and skills.
+
+## Next Steps
+
+Where to apply this knowledge next.
+```
 - [ ] Integration tests
 - [ ] E2E tests

@@ -209,6 +303,7 @@ Standard implementation plans follow Phase 1 (Foundation), Phase 2

 **See also**:

+- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow
 - `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
 - `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows

--- a/.cursor/rules/meta_documentation.mdc
+++ b/.cursor/rules/meta_documentation.mdc
@@ -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