maintaining-core-documentation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: maintaining-core-documentation
description: |
  Creates, maintains, and synchronises core project documentation (README, TODO, DESIGN, Architecture, Testing, Deployment). Use when the user needs to write, update, or structure project documentation based on codebase changes, or whenever asked to perform documentation reviews or updates.
metadata:
  author: Darren "Dazbo" Lester
  repository: https://github.com/derailed-dash/dazbo-agent-skills
---

# Maintaining Core Documentation

This skill provides a comprehensive framework for the creation and maintenance of high-quality, professional technical documentation for any software project or repository.

## Table of Contents

- [Triggers](#triggers)
- [Mandatory Initialization](#mandatory-initialization)
- [Core Principles](#core-principles)
- [Technical Writer Skill Synergy](#technical-writer-skill-synergy)
- [Document Maintenance Guide](#document-maintenance-guide)
- [Formatting Rules](#formatting-rules)
- [Documentation Review Process](#documentation-review-process)

## Triggers

This skill should be triggered whenever:

- The user requests to create or review documentation.
- The user adds / changes / deletes functionality, or makes significant changes to the codebase.
- The user makes any changes to testing.
- The user makes any changes to deployment.

## Mandatory Initialization

Before performing ANY documentation task, you MUST check for the presence of the `technical-writer` skill, by following the guidance in the `Technical Writer Skill Synergy` section below.

## Core Principles

1.  **Persona & Style**: Maintain a tone that is professional ("Expert Architect"), technical but welcoming. Use a high-level architectural perspective when explaining the "Why" behind design decisions.
2.  **Cross-Document Synchronisation**: Changes to a core property (like a project ID, a URL, or a file path) must be propagated to *all* applicable documentation files immediately.
3.  **Read Existing Documentation**: Always read the existing documentation files to understand the current state and intent of the project.
4.  **Tech Stack**: If the file `conductor/tech-stack.md` is present, read it to understand the intended tech stack.
5.  **Technical Accuracy**: Do not assume that the existing documentation is accurate or up-to-date. Verify the codebase, configuration settings (e.g. `config.py`, `Makefile`, `*.tfvars`, `pyproject.toml`), environment variable names, and command flags, before updating documentation.
6.  **Ask About Unknowns**:
    - Ask questions to help establish design choices and technology selection.
    - Ask questions to help establish the rationale for any design decisions that are missing rationale.
7.  **Technical Writer Synergy**: When performing documentation maintenance, you MUST make use of the `technical-writer` skill IF (and only IF) the `technical-writer` skill is present. If it is not found, follow the **Technical Writer Skill Synergy** section below.

## Technical Writer Skill Synergy

The `technical-writer` skill improves the quality of your documentation review and creation.

1. Determine `technical-writer` skill availability:
   **Skill exists?** → Load the skill and collaborate on formatting.
   **Skill missing?** → Follow the "Installation workflow" below.

2. Installation workflow:
   - Check availability using `npx skills ls -g`.
   - Recommend the skill to the user.
   - If approved, install via: `npx skills add https://github.com/shubhamsaboo/awesome-llm-apps --skill technical-writer -g -y`

## Document Maintenance Guide

Here are the core documents that should be maintained by this skill. You MUST review EACH of these core documents and update them as needed.

### 1. `README.md` (The "Storefront")

*   **Focus**: Rapid onboarding and high-level project purpose.
*   **Template**: [README.md.template](./references/README.md.template)
*   **Sample**: [README.md](./references/samples/README.md)
*   **Key Sections**: Overview, Key Links (Blogs/Liv