project-documentation-structure.rules

Documentation Workflow (Agent Action)

1. Domain Knowledge Capture: When working on a feature or complex task, capture significant domain knowledge (design decisions, tricky implementation details, rationales, API usage notes, error handling strategies, configuration details) that isn't obvious from the code itself.

2. File Creation & Enhancement for Discoverability:

   • Action: Create new Markdown (.md) files for this knowledge within the appropriate subfolder (e.g., under docs/features/, docs/concepts/, docs/architecture/adr/). Use descriptive kebab-case filenames.
   • Action: Include Structured Metadata (YAML Frontmatter): At the very top of EVERY new or significantly updated documentation file, include or update a YAML frontmatter block. This is critical for search and indexing:

     ---
     title: "[Clear, Descriptive Title of Document]" # Human-readable title
     description: "[One-sentence summary focusing on key concepts and purpose]" # Concise explanation
     keywords: # Comprehensive list for keyword search (grep) and potential RAG indexing
       - "[primary topic]"
       - "[key technology involved, e.g., React, Vitest, Docker]"
       - "[feature name]"
       - "[related component name]"
       - "[core concept]"
       - "[synonym or alternative term]"
       - "[specific function name if relevant]"
       - "[error code if relevant]"
     related_features: ["[feature-folder-name]", "[another-feature]"] # Links to related feature doc folders (use folder names)
     related_concepts: ["[concept-folder-name]"] # Links to related concept doc folders
     related_adr: ["[adr-number]"] # Optional: Link to relevant ADRs
     last_updated: "[YYYY-MM-DD]" # Date of creation/last significant update
     # author: "[Agent/User Name - Optional]"
     ---
     

   • Action: Write a Concise Summary/Abstract: Immediately following the frontmatter, write a short paragraph (2-4 sentences) summarizing the document's main content and purpose. Naturally weave in the most important keywords from the frontmatter. This helps RAG context retrieval.
   • Action: Use Descriptive Headings: Structure the main document content using clear, keyword-rich Markdown headings (##, ###) that accurately reflect the information in each section. This helps both human readers and semantic search.
   • Action: Embed Cross-Links: Where relevant within the main content, add explicit Markdown links ([link text](mdc:relative/path/to/other/doc.md) or [link text](mdc:[root-relative-path])) to other related documentation files within /docs or even specific code files/sections. This strengthens the knowledge graph for RAG.
   • Action: Capture Detailed Knowledge: Populate the rest of the file with the detailed domain knowledge, decisions, implementation notes, etc., captured in Step 1, using clear language and code blocks where appropriate.

3. Index Updates: CRITICAL: After adding or significantly modifying a documentation file:

   • Action: ALWAYS update the corresponding [foldername].index.md file in its parent directory. Add/update the link using the title from the frontmatter and the description from the frontmatter for context.
   • Action: ALWAYS update the last_updated field in the frontmatter of the modified/created document itself.
   • Action: Consider if the root docs.index.md or higher-level indexes need updates to reflect the new content, especially for major additions. Ensure discoverability through navigation.

4. Review Existing Docs (Consultation): Before creating new documentation, use the consult-documentation-index rule/process to check relevant index files and potentially perform searches (grep or semantic using keywords) to see if similar information already exists. Update existing documents rather than creating duplicates whenever practical.