maintaining-core-documentation

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
• Mandatory Initialization
• Core Principles
• Technical Writer Skill Synergy
• Document Maintenance Guide
• Formatting Rules
• 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.