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

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