manage-markdown-docs

name	manage-markdown-docs
description	Standardize markdown document creation and updates with proper headers and footers. Use when creating OR updating any markdown file that is NOT a subagent, command, or skill definition. Ensures consistent metadata, classification, and change tracking.

Ensure all markdown documents have consistent structure with proper header metadata and footer change history. Standardizes documentation across projects regardless of type (workspace, monorepo, ontology, etc.). - Research notes and findings - Analysis reports - Context documents - Design documents - Meeting notes - Technical documentation - Any general-purpose markdown file

<does_not_apply_to>

• Subagent definitions (agents/*.md)
• Slash commands (commands/*.md)
• Skills (SKILL.md files)
• README.md files (these have their own conventions)
• CLAUDE.md files
• CHANGELOG.md files </does_not_apply_to>

<quick_start> <workflow_new_document> When CREATING a new markdown file:

1. Check if document type is excluded (subagent, command, skill) → MUST stop if excluded
2. If path provided by user, use it; otherwise determine appropriate location
3. Classify document type
4. Generate header with required metadata
5. Write document content
6. Add footer with change history (initial creation entry) </workflow_new_document>

<workflow_update_document> When UPDATING an existing markdown file:

1. Check if document type is excluded (subagent, command, skill) → MUST stop if excluded
2. If document lacks proper header/footer, add them
3. Make the requested content changes
4. Update the Change History table in footer with new entry </workflow_update_document>

<quality_requirements> Markdown Lint Compliance:

• All produced markdown must be free from lint errors
• Use consistent heading levels (no skipping levels)
• Blank lines before and after headings, code blocks, and lists
• No trailing whitespace
• Single blank line at end of file
• Properly closed code fences with language specifier

Diagrams:

• All diagrams MUST use Mermaid format
• Use fenced code blocks with mermaid language identifier
• Supported diagram types: flowchart, sequence, class, state, ER, gantt, pie, mindmap

Example:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

</quality_requirements>

<path_behavior> If user provides a specific file path:

• MUST use that path exactly
• NEVER suggest alternatives
• NEVER question the location

If NO path provided, determine based on document type and project structure. </path_behavior> </quick_start>

<document_classification> Classify every document into ONE of these categories:

**External Research Finding** - Information gathered from outside sources - Web research, API documentation, third-party analysis - Competitor analysis, market research - Directory suggestion: `research/` or `docs/research/` **Internal Analysis Report** - Analysis of internal systems, code, or processes - Performance reports, architecture reviews - Code quality assessments, technical debt analysis - Directory suggestion: `analysis/` or `docs/analysis/` **Contextual Document** - Background information for ongoing work - Project context, decision rationale - Historical context, migration notes - Directory suggestion: `context/` or `docs/context/` **Other** - Documents that don't fit above categories - Meeting notes, scratch documents, miscellaneous - Directory suggestion: `docs/` or project root

<header_template> Every document MUST start with this header structure:

---
document: [Document Name]
created: [YYYY-MM-DD HH:MM]
classification: [external-research | internal-analysis | contextual | other]
---

**Purpose**: [What this document is for]
**Author**: [Who created it - can be "Claude" or user name]
**Context**: [Why this document was created - what prompted it]

---

<field_guidance>

• document: Clear, descriptive name (not the filename)
• created: Current date and time when document is first created
• classification: One of the four categories above
• Purpose: 1-2 sentences on what the document achieves
• Author: Who or what produced this document
• Context: The triggering event or need that led to creation </field_guidance> </header_template>

<footer_template> Every document MUST end with this footer structure:

---

## Change History

| Date | Change | Author |
|------|--------|--------|
| [YYYY-MM-DD] | Initial creation | [Author] |

<update_behavior> After EVERY modification to the document:

1. Add a new row to the Change History table
2. Include date, brief description of change, and who made it
3. Keep entries in reverse chronological order (newest first)

Example after updates:

## Change History

| Date | Change | Author |
|------|--------|--------|
| 2024-03-15 | Added section on error handling | Claude |
| 2024-03-14 | Expanded API examples | User |
| 2024-03-14 | Initial creation | Claude |

</update_behavior> </footer_template>

<complete_example>

---
document: Authentication Flow Analysis
created: 2024-03-14 09:30
classification: internal-analysis
---

**Purpose**: Document the current authentication flow and identify potential improvements
**Author**: Claude
**Context**: User requested security review of login system

---

[Document content goes here...]

---

## Change History

| Date | Change | Author |
|------|--------|--------|
| 2024-03-14 | Initial creation | Claude |

</complete_example>

<success_criteria> Document is correctly structured when:

• Header contains all required fields (document, created, classification)
• Purpose, Author, and Context are clearly stated
• Classification matches document content
• Footer has Change History table
• Change History is updated after every modification
• Path respects user-provided location or follows classification-based suggestion
• Markdown is lint-free (proper spacing, heading levels, code fences)
• Any diagrams use Mermaid format </success_criteria>

<anti_patterns>

• Creating documents without headers
• Skipping change history updates
• Overriding user-specified paths
• Applying this to subagents, commands, or skills
• Using vague document names like "Notes" or "Document"
• Leaving Purpose/Author/Context empty
• Producing markdown with lint errors (missing blank lines, skipped heading levels)
• Using ASCII art, PlantUML, or other diagram formats instead of Mermaid
• Code fences without language specifiers

</anti_patterns>