forked from jsnbuchanan/crowd-funder-for-time-pwa
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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user