400-documentation-standards

description: WHEN creating or updating BIG BRAIN components ENSURE proper documentation standards are followed globs: ["/*.mdc", "/*.md"] alwaysApply: true

TL;DR: This rule defines documentation standards for BIG BRAIN components, ensuring consistent, complete, and high-quality documentation that persists across memory resets.

1.0.0

1. **TL;DR Summary**
   - Concise overview (1-3 sentences)
   - Placed at the beginning after description
   - Formatted with blockquote for visual emphasis
   - Example: `> **TL;DR:** This component provides verification mechanisms for memory file integrity.`

2. **Version Information**
   - Clear version number
   - Located near the top
   - Follows semantic versioning (MAJOR.MINOR.PATCH)
   - Format: `<version>1.0.0</version>`

3. **Context Description**
   - Explains the purpose and importance
   - Provides essential background
   - Clarifies when/why the component is needed
   - Format: `<context>Description here...</context>`

4. **Requirements List**
   - Explicit enumeration of what the component must accomplish
   - Individual requirements clearly tagged
   - Concise, action-oriented statements
   - Format:
     ```
     <requirements>
       <requirement>First requirement</requirement>
       <requirement>Second requirement</requirement>
     </requirements>
     ```

5. **Implementation Details**
   - Organized in separate named sections
   - Progressive disclosure (most important first)
   - Visual hierarchy with headers, lists, tables
   - Format:
     ```
     <details>
       <section-name>SECTION NAME</section-name>
       <content>
         Section content here...
       </content>
     </details>
     ```

6. **Version History**
   - Table of changes by version
   - Author of each change
   - Date of modification
   - Brief description of changes
   - Format:
     ```
     ## 📝 Version History

     | Version | Date       | Author    | Changes                 |
     | ------- | ---------- | --------- | ----------------------- |
     | 1.0.0   | 2025-03-24 | BIG BRAIN | Initial implementation  |
     ```

1. **Markdown Structure**
   - Use ATX-style headers (`#`, `##`, etc.)
   - Use fenced code blocks with language identifiers
   - Use unordered lists for collections without sequence
   - Use ordered lists for sequential steps
   - Use tables for structured data

2. **Visual Hierarchy**
   - Consistent emoji markers for section types:
     - 📌 for key points
     - 🔍 for implementation details
     - 📋 for checklists
     - 🧠 for insights
     - ⏭️ for next steps
     - 📝 for version history
   - Use horizontal rules (`---`) to separate major sections
   - Use indentation for hierarchical information
   - Use bold and italics for emphasis