crew-docs

Files (2)

• SKILL.md
• integrations.md

SKILL.md (first lines)

# Document maintenance

## The default is: do not touch

Updating every document on every change is how documentation becomes noise. A
CHANGELOG with an entry for each typo fix is unreadable; a README rewritten every
sprint stops being trusted because nobody can tell what actually changed.

So each document has a **trigger condition**, and if the condition is not met,
the document is left alone and that is the correct outcome.

**Diagrams are the exception, and only diagrams.** `docs/diagrams/*.mmd` carry
an anchor sha, so whether one is current is a fact rather than a judgement —
`/crew:diagram` refreshes those when `diagramsStale` or `diagramsMissing` fires
(see `crew-diagrams`). Nothing in the table below works that way. Whether a
change deserves a CHANGELOG entry depends on whether a user can observe it, and
no sha answers that, which is why these stay manual.

| Document | Update when | Never |
|---|---|---|
| `CHANGELOG.md` | Behaviour users or callers can observe changed | Refactors, formatting, internal renames |
| `README.md` | Setup, commands, or the mental model changed | Every ticket |
| `SECURITY.md` | Reporting process, supported versions, or a disclosed issue changed | Routine security fixes |
| `TODO.md` | Something deliberately deferred, with a reason | As a substitute for tickets |
| `docs/adr/` | A decision was made with a rejected alternative | Implementation detail |
| `docs/diagrams/` | The structure a diagram shows moved (see `crew-diagrams`); then `crew_diagrams.py embed` rewrites the README embeds | Cosmetic changes; never hand-edit a `crew-diagrams` section |
| `docs/runbooks/` | An operational procedure changed, or a new one was needed | Anything `make deploy` already does |

`/crew:implement` asks this question once per ticket. The honest answer is
usually "none of them."

## The decision is recorded, then checked

`/crew:docs <id>` writes `.work/tickets/<id>/docs.json` once: `{"reasons": {"<document>":
"<why not>"}, "deferred": [{"key", "why", "unblock"}]}`. `crew_docs_check.py --ticket <id>`
then prints each document `updated`, `not needed (<reason>)` or `MISSING`. A changed
marketplace entry's CHANGELOG line (its name and new version, under `[Unreleased]`) is
mechanical and no reason waives it; README and SECURITY.md are `not needed` only with a
recorded reason once a trigger fired; every deferral must reach TODO.md. ADRs and
runbooks stay judgement, reported `not measured`. It runs before review, never after.

## Generated blocks are not yours to edit

Some documentation is compiled from source. Editing the output is work that gets
destroyed on the next build, silently.

Before editing any markdown, check for these and stop if you are inside one:

```
<!-- BEGIN_TF_DOCS -->  ... <!-- END_TF_DOCS -->     terraform-docs
<!-- begin-openapi -->  ... <!-- end-openapi -->      openapi generators
<!-- AUTO-GENERATED -->                                various
```

For terraform-docs specifically, the content comes from the `/** */` header in
`main.tf`, from `footer.md`, and from the `description` fields on variables and
outputs. Change those. See `crew-terraform`.

If a README has such a block, hand-written prose belongs **above** it.

## CHANGELOG

Keep a Changelog format, semantic versions, newest first.

```markdown
## [Unreleased]
### Added
- Scheduled report Lambda replacing the sbmovement .NET job (ACME-1058)
### Fixed
- Header validation rejected files with a UTF-8 BOM
```

Write from the **ticket and the diff**, not from the conversation. One line per
user-visible change, in the language of someone using the thing rather than
someone who built it: "rejects files with a BOM" not "added BOM strip in
`validate_header()`".

Reference the ticket id. Do not paste commit hashes — they are in git already and
they make the file unreadable.

## SECURITY.md

Rarely changes, and that is fine. It should carry: how to report a vulnerability
and to whom, which versions get fixes, and expected response time.

**Never** log specific vulnerabilities here while they are unfixed. A public
`SECURITY.md` describing an open hole is a disclosure, not documentation. Fixed
issues go in the CHANGELOG once released.

## TODO.md

Only for work deliberately deferred with a reason, which is different from work
not yet started — that belongs in tickets.

```markdown
- [ ] Replace the polling loop with EventBridge — deferred until the SFTP
      migration lands, because the current trigger depends on the share path
```

Each entry says **why it is deferred and what would unblock it**. Without that,
it is an inbox that grows forever and gets deleted in frustration two years later.

`.work/SMOKE-GAPS.md` is the same idea for test coverage and stays separate.

## ADRs

One decision per file, append-only, never edited after acceptance. A superseded
decision gets a new ADR that references the old one — the record of having
changed your mind is the valuable part.

Write them when the alternative was real. "We used the standard library" is not
an ADR. "We chose stored procedures over application logic because the batch
window requires set-based operations" is.

## Doing the work

```
/crew:docs            # check what this change should touch, and do it
/crew:docs --audit    # report staleness across all docs, change nothing

From mbadali25/useful-claude-add-ons, GPL-2.0.

More from mbadali25/useful-claude-add-ons