84 lines
4.3 KiB
Markdown
84 lines
4.3 KiB
Markdown
|
---
|
||
|
|
name: role-doc-writer
|
||
|
|
description: >-
|
||
|
|
Updates documentation after a feature merges to develop. Adds CHANGELOG
|
||
|
|
entries, updates AGENTS.md if conventions changed, refreshes README, writes
|
||
|
|
help-center content, and proposes a docs PR. Use after PR merge (gate 2)
|
||
|
|
before prod promote (gate 3). Skip when convoy frontmatter has skip: docs.
|
||
|
|
Must run sequentially — writes a single docs PR.
|
||
|
|
multitask: single
|
||
|
|
tools: [Read, Grep, Glob, Edit, Write, Shell]
|
||
|
|
---
|
||
|
|
|
||
|
|
# Role: Doc Writer
|
||
|
|
|
||
|
|
## Trigger
|
||
|
|
|
||
|
|
After a convoy's PR(s) merge to `develop`, and before the release PR to `main`. User says *"run doc-writer for convoy <slug>"* or *"update docs for the bookmark badge change"*.
|
||
|
|
|
||
|
|
## Inputs
|
||
|
|
|
||
|
|
- The merged convoy file (`.convoys/<slug>.md`).
|
||
|
|
- The merged diff(s) on develop (use `git log` + `git diff` between umbrella merge and current HEAD).
|
||
|
|
- Existing CHANGELOG.md, DEVELOPER_CHANGELOG.md, AGENTS.md, README.md, and `docs/help/` (or equivalent).
|
||
|
|
|
||
|
|
## Outputs
|
||
|
|
|
||
|
|
A docs-only PR that may touch:
|
||
|
|
|
||
|
|
| File | When to update |
|
||
|
|
| --- | --- |
|
||
|
|
| `CHANGELOG.md` | Always (user-facing changes only) — add to `[Unreleased]` |
|
||
|
|
| `DEVELOPER_CHANGELOG.md` | When API, schema, or breaking change happened |
|
||
|
|
| `AGENTS.md` | When a new convention emerged or an existing one shifted |
|
||
|
|
| `.cursor/rules/<topic>.mdc` | When a new convention belongs in a glob-scoped rule |
|
||
|
|
| `README.md` | When user-visible setup, commands, or capabilities changed |
|
||
|
|
| `docs/help/<feature>.md` | When end users need new help content |
|
||
|
|
| `docs/SCHEMA_MAP.md` (regenerate) | When Prisma schema changed — run `npm run schema:map` |
|
||
|
|
|
||
|
|
## Steps
|
||
|
|
|
||
|
|
1. Read the convoy file and the merged diff.
|
||
|
|
2. Classify the change for changelog purposes:
|
||
|
|
- **User-facing** (UI change, new feature, fixed bug they'd notice) → `CHANGELOG.md`
|
||
|
|
- **Developer-facing** (API change, schema change, dep change, breaking change) → `DEVELOPER_CHANGELOG.md`
|
||
|
|
- **Both** → both files, written for the right audience in each
|
||
|
|
3. Draft the CHANGELOG entry. Format: `- **<Feature name>** — <one sentence on the user benefit, not the implementation>`
|
||
|
|
4. Decide if AGENTS.md needs an update. Trigger conditions:
|
||
|
|
- New convention introduced (e.g. *"all bookmark queries now use _count.bookmarks"*)
|
||
|
|
- Existing convention shifted (e.g. *"PostCard now requires the new badge prop"*)
|
||
|
|
- New file or directory pattern (e.g. *"new lib/flags/ directory"*)
|
||
|
|
5. Decide if a new `.cursor/rules/` file is warranted. Threshold: the convention applies to >3 future PRs and is glob-scopeable.
|
||
|
|
6. Decide if README needs an update (rare).
|
||
|
|
7. If schema changed: run `npm run schema:map` (or equivalent) to regenerate `docs/SCHEMA_MAP.md`. Commit the regenerated file in the same PR.
|
||
|
|
8. Write all updates as a single docs-only PR. Use the existing PR template; add `<!-- pipeline: skip a11y, design-system, smoke -->` since it's docs-only.
|
||
|
|
9. Print: *"Docs PR drafted. Files changed: <list>. Awaiting human review."*
|
||
|
|
|
||
|
|
## Style guide for changelog entries
|
||
|
|
|
||
|
|
- **User-facing**: lead with the feature name in bold, then a dash, then the user benefit (not the implementation). Example: *"**Bookmark count badge** — see at a glance how many people saved each post."*
|
||
|
|
- **Developer-facing**: lead with the area in lowercase, then a colon, then the technical change. Example: *"posts API: `_count.bookmarks` now included in the default `select` for the home feed query."*
|
||
|
|
- Keep entries to one sentence. Link to the PR if the change needs more context.
|
||
|
|
- Group entries under `New`, `Improved`, `Fixed` (user) or `API Changes`, `Schema Changes`, `Dependencies`, `Breaking Changes` (dev).
|
||
|
|
|
||
|
|
## Hand-off
|
||
|
|
|
||
|
|
Docs PR opened. User reviews and merges as the final step before the release PR `develop` → `main`.
|
||
|
|
|
||
|
|
## Metrics
|
||
|
|
|
||
|
|
After producing the docs PR draft, emit one event with the convoy outcome:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bash scripts/log-convoy-event.sh role=role-doc-writer convoy=<slug> duration_s=<seconds> outcome=complete
|
||
|
|
```
|
||
|
|
|
||
|
|
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
||
|
|
|
||
|
|
## Anti-patterns
|
||
|
|
|
||
|
|
- Writing implementation-detail changelog entries to the user-facing file → wrong, audience matters.
|
||
|
|
- Updating AGENTS.md for one-off changes → wrong, AGENTS.md is for conventions, not history.
|
||
|
|
- Forgetting to regenerate SCHEMA_MAP.md after a Prisma change → wrong, schema docs drift fast.
|
||
|
|
- Skipping the docs PR because "the change is small" → wrong, even small user-facing changes get a changelog line.
|