61 lines
2.1 KiB
Markdown
61 lines
2.1 KiB
Markdown
---
|
|
description: "Audit documentation for standards. [Trigger: //lint]"
|
|
---
|
|
|
|
# Documentation Linter & Standardizer
|
|
|
|
**Trigger:** `/doc-lint`
|
|
|
|
## Goal
|
|
Audit documentation files for structural integrity, clarity, and adherence to the repository's style guide (`style.markdown.md`), ensuring a consistent voice across the lab.
|
|
|
|
## Cognitive Protocol: Meta-Prompting (Invariant checking)
|
|
*Reference: `.github/knowledge/example.Meta-Prompting.md`*
|
|
|
|
**Objective:** Treat the file `.github/instructions/style.markdown.md` as the "Golden Schema." Any deviation is an error.
|
|
|
|
### Phase 1: Context Loading
|
|
**Action:**
|
|
1. Read `.github/instructions/style.markdown.md` (The Standards).
|
|
2. Read the target file(s) specified by the user.
|
|
|
|
### Phase 2: The Audit (Chain of Thought)
|
|
*Reference: `example.CoT-Prompting.md`*
|
|
|
|
Deconstruct the target file against these 4 dimensions:
|
|
|
|
1. **Structural Integrity:**
|
|
* Are headers ATX-style (`##`) and Sentence Case?
|
|
* Is the Frontmatter valid (YAML format)?
|
|
* Are code blocks language-tagged (e.g., ````yaml`)?
|
|
|
|
2. **Clarity & Voice:**
|
|
* Is the tone "Professional but Frank"?
|
|
* Are lists used to break up "Walls of Text"?
|
|
* Are complex ideas explained with "Step-by-Step" logic?
|
|
|
|
3. **Hygiene:**
|
|
* Check for broken internal links.
|
|
* Check for "lazy" placeholders (e.g., "TODO: write this").
|
|
* Check for absolute paths (should be relative or env vars).
|
|
|
|
4. **Formatting (The Strict Check):**
|
|
* No trailing whitespace.
|
|
* Double spacing between sections.
|
|
* **Constraint:** No use of Latin abbreviations (e.g., "i.e.", "e.g.") -> Use "for example" or "specifically."
|
|
|
|
### Phase 3: The Report
|
|
Present findings in a structured "Linter Output":
|
|
|
|
#### 🔴 Critical Errors (Must Fix)
|
|
* *Line 12:* Missing language tag on code block.
|
|
* *Line 45:* Broken link `[Setup](./bad-path.md)`.
|
|
|
|
#### 🟡 Style Warnings (Should Fix)
|
|
* *Line 3:* Header "SETUP INSTRUCTIONS" is Screaming Caps (Change to "Setup instructions").
|
|
* *General:* Paragraph 2 is a wall of text; split into bullets.
|
|
|
|
#### 🟢 Auto-Fix Proposal
|
|
(Only if requested)
|
|
> "I can apply these fixes automatically. Reply **FIX** to execute."
|