documentation-architecture

name	documentation-architecture
description	Use when the main deliverable is maintainable documentation such as repository rules, onboarding guides, runbooks, ADRs, or architecture notes.

Documentation Architecture

Use this skill when documentation is the primary output, or when code changes require documentation to stay in sync.

Define before writing

1. audience — who will read this? (developers, agents, ops, new hires)
2. source of truth — which file is canonical for this topic?
3. mandatory versus optional guidance — what must be followed vs. what is a recommendation?
4. what stays short versus what moves into focused docs
5. tool-specific files that need alignment

Automatic documentation maintenance

Documentation rots when it is only updated manually. These rules ensure agents keep docs current as a side effect of normal work, not as a separate task.

Decision record — capture after decisions

Trigger: any agent makes an architectural or behavioral decision during implementation.

Action: record the decision according to prompt-budget.yml -> decision_log.policy using the format in docs/operating-rules.md -> Decision log. In adopted projects this usually means appending to DECISIONS.md; in this template repo it means recording in the task summary, handoff artifact, or trace file.

Agents must not skip this step. If a decision was made but not recorded, the risk-reviewer should flag it.

ARCHITECTURE.md — auto-update after structural changes

Trigger: any of these events during implementation:

• A new module or directory is created
• A module is moved, renamed, or deleted
• A module boundary changes (e.g., a service is split or merged)
• A new external dependency or integration is added
• Data flow between modules changes

Action: update the relevant section of ARCHITECTURE.md. If the file does not exist, create it with this structure:

# Architecture

## Module map

| Directory          | Purpose                          |
|--------------------|----------------------------------|
| src/api/           | HTTP handlers and route definitions |
| src/services/      | Business logic                   |
| ...                | ...                              |

## Key interfaces and contracts

- [Interface name] — [file path] — [what it defines]

## Data flow

[Brief description or diagram of how data moves through the system]

## External dependencies

| Dependency   | Purpose        | Notes                    |
|--------------|----------------|--------------------------|
| PostgreSQL   | Primary store  | Managed via migrations   |
| ...          | ...            | ...                      |

## Known technical debt

- [Description] — [file path or module] — [why it exists]

project/project-manifest.md — auto-append after constraint discovery

Trigger: during implementation, an agent discovers an unwritten rule that is enforced by the codebase (e.g., "all handlers use middleware X", "dates are always UTC").

Action: add it to project/project-manifest.md.

Documentation sync check

After any code change that affects architecture, contracts, or decisions, agents must verify:

1. Decisions made in this task are recorded according to prompt-budget.yml -> decision_log.policy
2. ARCHITECTURE.md reflects any structural changes
3. project/project-manifest.md includes any newly discovered project-local rules
4. Tool-specific files (.claude/agents/, .github/copilot-instructions.md) are still aligned with the source-of-truth docs

If any are stale, update them before marking the task complete.

Writing guidelines

• Keep each doc focused on one topic. Split rather than append endlessly.
• Use tables for structured data (module maps, decisions, risks).
• Prefer concrete examples over abstract principles.
• Date all decision entries.
• Write for the next agent session, not just the current one — assume no prior context.

Use this skill when

• writing repository instructions
• updating onboarding or process docs
• generating ADRs, runbooks, or architecture notes
• keeping agent-facing and human-facing docs aligned
• code changes require documentation sync (structural changes, new decisions, new constraints)

Conformance self-check

Before marking documentation work as complete, verify:

• Audience and source of truth were identified before writing
• Each doc focuses on one topic; no unbounded appending
• Decisions made in this task are recorded according to prompt-budget.yml -> decision_log.policy
• ARCHITECTURE.md reflects any structural changes
• Tool-specific files (.claude/agents/, .github/copilot-instructions.md) are aligned with source-of-truth docs
• Tables are used for structured data; examples are concrete, not abstract