Immutable. This exact content is served forever at /api/v1/blob/cd0daa8a385d5c43.
---
name: make-docs
description: >-
Use when the user wants architecture docs or behavioral specs, asks to explore a codebase for documentation, sync docs after changes, refresh existing docs against current code, or record an ADR. Branches: explore (survey, confirm, generate), update (since last docs stamp → sync), refresh (full re-survey vs existing docs/), adr (decision record).
metadata:
version: 0.2.0
author: "Diego Oliveira"
tags:
- docs
- architecture
- specs
- adr
---
# Make docs
Produces a documentation suite in `docs/`: **architecture** (how it is structured) and **specs** (what it does). Specs name only **observable** outcomes. An agent can implement or verify against them.
**Branches:** explore (survey → confirm → generate → verify). Update (delta since the docs stamp). Refresh (full re-survey vs existing `docs/`). Adr (one decision).
**Invariants:** Every claim in the suite cites a path, an observable command, or a config. Missing evidence: omit the section or ask. One language per suite; code identifiers and BCP 14 keywords (ALL CAPS) stay as in source. Hunters collect; the orchestrator writes. Unearned sections are omitted with no justification paragraph in the artifact.
**Reference budget:** The orchestrator opens a phase file when that phase starts. Each hunter gets exactly **1** hunter file. Orchestrator-only refs (`anti-slop`, `language`, `examples`, templates, confirm / generate / verify) are not hunter paths.
## Commands
| Invocation | Branch | Behavior |
| ---------- | ------ | -------- |
| `/make-docs explore` | **explore** | Survey → confirm → generate → verify |
| `/make-docs update` | **update** | `./references/phases/update.md` then verify |
| `/make-docs refresh` | **refresh** | `./references/phases/refresh.md` (survey → confirm → generate → verify) |
| `/make-docs adr` | **adr** | `./references/phases/adr.md` then verify if architecture.md moved |
Without a subcommand, treat as **explore** when `docs/` is missing or the user asked to generate a suite; treat as **update** when they asked to sync after changes and `docs/` exists; treat as **refresh** when they asked to regenerate existing docs against current code.
## Definition of Done
Done for each phase is the completion criterion in its READ file. Open the next phase file when that criterion is met.
### Branch explore
| Phase | Done when | READ |
| ----- | --------- | ---- |
| Survey | Evidence pack ready (hunters returned or `hunters: none` recorded); existing docs read | `./references/phases/survey.md` |
| Confirm | User confirmed the brief, or answered every unknown | `./references/phases/confirm.md` |
| Generate | Every confirmed file written from its template; unearned sections omitted; stamp set | `./references/phases/generate.md` |
| Verify | Every check in the verify file passes | `./references/phases/verify.md` |
### Branch update
| Phase | Done when | READ |
| ----- | --------- | ---- |
| Update | Every classified change reflected or waived in chat; stamp refreshed | `./references/phases/update.md` |
| Verify | Every check in the verify file passes | `./references/phases/verify.md` |
### Branch refresh
| Phase | Done when | READ |
| ----- | --------- | ---- |
| Refresh | Existing `docs/` reconciled to current code; ADRs kept unless contradicted; stamp refreshed | `./references/phases/refresh.md` |
Refresh runs survey → confirm → generate → verify against the current tree. Its READ file names that sequence.
### Branch adr
| Phase | Done when | READ |
| ----- | --------- | ---- |
| Adr | Names a _why_; gains + costs present; alternatives have reasons; architecture.md updated if boundaries moved | `./references/phases/adr.md` |
## Layout
```text
docs/
README.md # includes `> Updated on <ISO-date>`
architecture/
architecture.md
domains/
glossary.md
api.md # only if the project exposes an API
constraints.md
decisions/ # ADR-NNNN-<slug>.md
patterns.md
specs/
<domain>.md # one per behavioral domain
```
By repo size: **small:** README + architecture.md + decisions/; **medium/large:** full set; **monorepo:** root docs/ + one per service (nearest wins). Cut any file or section the survey did not **earn**. Fill every earned section from evidence. Example rows in templates are not defaults.
## Templates
Before writing a file, load its template from `references/`:
| Template | File |
| -------- | ---- |
| `references/template-readme.md` | `docs/README.md` |
| `references/template-architecture.md` | `docs/architecture/architecture.md` |
| `references/template-glossary.md` | `docs/architecture/domains/glossary.md` |
| `references/template-api.md` | `docs/architecture/domains/api.md` |
| `references/template-constraints.md` | `docs/architecture/domains/constraints.md` |
| `references/template-adr.md` | `docs/architecture/decisions/ADR-*.md` |
| `references/template-patterns.md` | `docs/architecture/patterns.md` |
| `references/template-spec.md` | `docs/specs/<domain>.md` |
## Specs
Specs describe **observable** behavior: outcomes a user or external system can see. Name domains after behavior (`auth`, `orders`), not folder layout.
- One requirement = one **SHALL** (split compound requirements).
- Requirement keywords follow BCP 14 ([RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174.html)): English tokens, ALL CAPS only. Full list and the incorporation sentence live in `./references/language.md`.
- Each requirement has at least one Scenario (Given/When/Then) that **exercises** it: a concrete case, not a rewording.
- Cover the case that would hurt most to see broken; name it explicitly.
- Pure refactor with no behavior change: no spec update. Record that in chat, not as filler in the spec file.
## Out of scope
Data model, observability, CI/CD. Survey lists them as unknowns when present. Confirm asks. Otherwise omit the files and do not narrate the omission in `docs/`.