documentation-generation
Registry Trigger
Use when
- task mode generates or updates README API docs ADR changelog runbook or migration notes
- review mode assesses documentation accuracy freshness or audience impact
Do not use when
- no task-local documentation generation decision is required
- an implementation diff has no separate documentation artifact
Skill Role
Support source-grounded documentation work with an explicit role boundary.
- Task mode (
task-agent): Produce the changed owning documentation source from current evidence.
- Review mode (
review-agent): Return a documentation verdict and findings from non-mutating inspection.
High-Value Rules
- Trace factual claims to current source, schemas, generated artifacts, tests, command output, accepted decisions, or release plans.
- Match depth to audience: operators need recovery actions, API consumers need semantics, contributors need validation, and users need impact.
- Classify deprecated, experimental, environment-specific, unverified, or inferred behavior explicitly in affected documentation.
- Update misleading documentation with behavior or record an owner and release consequence.
- Make examples executable, generated, or explicitly illustrative with proof limits.
- State compatibility, order, rollback, forward-fix, and ownership when versions diverge.
Anti-Patterns
- Treating repository discovery or prior summaries as factual proof.
- Keeping stale docs because code validation passes.
- Publishing generated examples without checking their compatibility promise.
- Claiming no documentation impact without naming considered audiences.
Stop Conditions
Escalate public APIs, security posture, compliance, migrations, production configuration, incident procedures, release impact, or operator recovery. Stop for exposed secrets, source conflicts, unvalidated generation, or ownerless release documentation.
Output Contract
- Task mode (
task-agent): changed source-grounded documentation artifact; audience and behavior mapping; validation result; proof limits; residual documentation debt
- Review mode (
review-agent): documentation verdict; severity-ranked findings; reviewed and unverified scope; proof limits; no mutation
Targeted References
| Path |
Type |
Load when |
Do not load when |
Required by |
Required output |
| benchmarks and patterns |
benchmark-pattern |
Source mapping, generation, command safety, or no-docs decisions need depth |
A small wording fix has one current authoritative source |
task-agent, review-agent |
option-comparison, selected-approach |
| checklist |
decision-checklist |
Documentation changes APIs, migrations, operations, examples, or compatibility |
No audience-facing behavior or procedure changes |
task-agent, review-agent |
checklist-result, residual-risk |
| evidence patterns |
evidence-pattern |
Documentation claims need fresh source, generator, or example validation |
No factual or no-docs claim awaits proof |
task-agent, review-agent |
evidence-record, proof-limit, residual-risk |
1---2name: documentation-generation3description: `task-agent`: change source-owned documentation; `review-agent`: assess documentation without mutation. Skip tasks requiring neither documentation change nor review.4---5
6# documentation-generation
7
8## Registry Trigger
9
10**Use when**
11
12- task mode generates or updates README API docs ADR changelog runbook or migration notes
13- review mode assesses documentation accuracy freshness or audience impact
14
15**Do not use when**
16
17- no task-local documentation generation decision is required
18- an implementation diff has no separate documentation artifact
19
20## Skill Role
21
22Support source-grounded documentation work with an explicit role boundary.
23
24- **Task mode (`task-agent`):** Produce the changed owning documentation source from current evidence.
25- **Review mode (`review-agent`):** Return a documentation verdict and findings from non-mutating inspection.
26
27## High-Value Rules
28
29- Trace factual claims to current source, schemas, generated artifacts, tests, command output, accepted decisions, or release plans.
30- Match depth to audience: operators need recovery actions, API consumers need semantics, contributors need validation, and users need impact.
31- Classify deprecated, experimental, environment-specific, unverified, or inferred behavior explicitly in affected documentation.
32- Update misleading documentation with behavior or record an owner and release consequence.
33- Make examples executable, generated, or explicitly illustrative with proof limits.
34- State compatibility, order, rollback, forward-fix, and ownership when versions diverge.
35
36## Anti-Patterns
37
38- Treating repository discovery or prior summaries as factual proof.
39- Keeping stale docs because code validation passes.
40- Publishing generated examples without checking their compatibility promise.
41- Claiming no documentation impact without naming considered audiences.
42
43## Stop Conditions
44
45Escalate public APIs, security posture, compliance, migrations, production configuration, incident procedures, release impact, or operator recovery. Stop for exposed secrets, source conflicts, unvalidated generation, or ownerless release documentation.
46
47## Output Contract
48
49- **Task mode (`task-agent`):** changed source-grounded documentation artifact; audience and behavior mapping; validation result; proof limits; residual documentation debt
50- **Review mode (`review-agent`):** documentation verdict; severity-ranked findings; reviewed and unverified scope; proof limits; no mutation
51
52## Targeted References
53
54| Path | Type | Load when | Do not load when | Required by | Required output |
55|---|---|---|---|---|---|
56| [benchmarks and patterns](references/benchmarks-and-patterns.md) | benchmark-pattern | Source mapping, generation, command safety, or no-docs decisions need depth | A small wording fix has one current authoritative source | task-agent, review-agent | option-comparison, selected-approach |
57| [checklist](references/checklist.md) | decision-checklist | Documentation changes APIs, migrations, operations, examples, or compatibility | No audience-facing behavior or procedure changes | task-agent, review-agent | checklist-result, residual-risk |
58| [evidence patterns](references/evidence-patterns.md) | evidence-pattern | Documentation claims need fresh source, generator, or example validation | No factual or no-docs claim awaits proof | task-agent, review-agent | evidence-record, proof-limit, residual-risk |
machenjie