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.
This commit is contained in:
Matthew Raymer
2025-08-24 02:42:48 +00:00
parent 9967fe97e6
commit c2aaf3a20d
6 changed files with 644 additions and 22 deletions

View File

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