---
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:

```markdown
# 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