| 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
- audience — who will read this? (developers, agents, ops, new hires)
- source of truth — which file is canonical for this topic?
- mandatory versus optional guidance — what must be followed vs. what is a recommendation?
- what stays short versus what moves into focused docs
- 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:
- Decisions made in this task are recorded according to
prompt-budget.yml -> decision_log.policy
ARCHITECTURE.md reflects any structural changesproject/project-manifest.md includes any newly discovered project-local rules- 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:
