Docs Update From Diff
Overview
Inspect local diffs, derive the documentation impact, and update only the
repository's docs/ pages. Treat the current code as the source of truth and
keep changes scoped, specific, and navigable.
Read references/docs-surface.md before editing if
the affected feature does not map cleanly to an existing docs section.
Workflow
1. Build the change set
Start from local Git state, not from assumptions.
- Inspect
git status --short, git diff --stat, and targeted git diff
output.
- Focus on non-doc changes first so the documentation delta is grounded in
code.
- Ignore
README.md and other non-docs/ content unless they help confirm
intent.
2. Derive the docs impact
For every changed behavior, extract the user-facing or developer-facing facts
that documentation must reflect.
- New command, flag, config key, default, workflow, or limitation
- Renamed behavior or removed behavior
- Changed examples, paths, or setup steps
- New feature that belongs in an existing page but is not mentioned yet
Prefer updating an existing page over creating a new page. Create a new page
only when the feature introduces a stable topic that would make an existing page
harder to follow.
3. Find the right docs location
Map each change to the smallest correct documentation surface:
- End-user behavior:
docs/users/**
- Developer internals, SDKs, contributor workflow, tooling:
docs/developers/**
- Shared landing or navigation changes: root
docs/** and _meta.ts
If you add a new page, update the nearest _meta.ts in the same docs section so
the page is discoverable.
4. Write the update
Edit documentation with the following bar:
- State the current behavior, not the implementation history
- Use concrete commands, file paths, setting keys, and defaults from the diff
- Remove or rewrite stale text instead of stacking caveats on top of it
- Keep examples aligned with the current CLI and repository layout
- Preserve the repository's existing docs tone and heading structure
5. Cross-check before finishing
Verify that the updated docs cover the actual delta:
- Search
docs/ for old names, removed flags, or outdated examples
- Confirm links and relative paths still make sense
- Confirm any new page is included in the relevant
_meta.ts
- Re-read the changed docs against the code diff, not against memory
- If the diff added, moved, renamed, or removed a page under
docs/users/,
verify the qc-helper bundled skill's topic-to-path index tables
(packages/core/src/skills/bundled/qc-helper/SKILL.md) are updated to
match. This skill ships with the CLI and uses hardcoded doc-path tables at
runtime — stale entries cause /qc-helper to miss the right documentation.
Also check project-level skills under .qwen/skills/ for hardcoded
docs/users/ references that may need updating.
Practical heuristics
- If a change affects commands, also check quickstart, workflows, and feature
pages for drift.
- If a change affects configuration, also check
docs/users/configuration/settings.md, feature pages, and auth/provider docs.
- If a change affects tools or agent behavior, check both
docs/users/features/** and docs/developers/tools/** when relevant.
- If tests reveal expected behavior more clearly than implementation code, use
tests to confirm wording.
- If the change adds, moves, renames, or removes a docs page, also update
hardcoded doc-path consumers:
qc-helper's SKILL.md index tables,
_meta.ts navigation files, and any project-level skills under
.qwen/skills/ that reference docs/users/ paths.
Deliverable
Produce the docs edits under docs/ that make the current local changes
understandable to a reader who has not seen the diff. Keep the final summary
short and identify which pages were updated.
1---
2name: docs-update-from-diff
3description: Review local code changes with git diff and update the official
4 docs under docs/ to match. Use when the user asks to document current
5 uncommitted work, sync docs with local changes, update docs after a feature or
6 refactor, or when phrases like "git diff", "local changes", "update docs", or
7 "official docs" appear.
8metadata:
9 source: https://skillmd.com/skills/qwenlm/docs-update-from-diff
10---
11
12# Docs Update From Diff
13
14## Overview
15
16Inspect local diffs, derive the documentation impact, and update only the
17repository's `docs/` pages. Treat the current code as the source of truth and
18keep changes scoped, specific, and navigable.
19
20Read [references/docs-surface.md](references/docs-surface.md) before editing if
21the affected feature does not map cleanly to an existing docs section.
22
23## Workflow
24
25### 1. Build the change set
26
27Start from local Git state, not from assumptions.
28
29- Inspect `git status --short`, `git diff --stat`, and targeted `git diff`
30 output.
31- Focus on non-doc changes first so the documentation delta is grounded in
32 code.
33- Ignore `README.md` and other non-`docs/` content unless they help confirm
34 intent.
35
36### 2. Derive the docs impact
37
38For every changed behavior, extract the user-facing or developer-facing facts
39that documentation must reflect.
40
41- New command, flag, config key, default, workflow, or limitation
42- Renamed behavior or removed behavior
43- Changed examples, paths, or setup steps
44- New feature that belongs in an existing page but is not mentioned yet
45
46Prefer updating an existing page over creating a new page. Create a new page
47only when the feature introduces a stable topic that would make an existing page
48harder to follow.
49
50### 3. Find the right docs location
51
52Map each change to the smallest correct documentation surface:
53
54- End-user behavior: `docs/users/**`
55- Developer internals, SDKs, contributor workflow, tooling:
56 `docs/developers/**`
57- Shared landing or navigation changes: root `docs/**` and `_meta.ts`
58
59If you add a new page, update the nearest `_meta.ts` in the same docs section so
60the page is discoverable.
61
62### 4. Write the update
63
64Edit documentation with the following bar:
65
66- State the current behavior, not the implementation history
67- Use concrete commands, file paths, setting keys, and defaults from the diff
68- Remove or rewrite stale text instead of stacking caveats on top of it
69- Keep examples aligned with the current CLI and repository layout
70- Preserve the repository's existing docs tone and heading structure
71
72### 5. Cross-check before finishing
73
74Verify that the updated docs cover the actual delta:
75
76- Search `docs/` for old names, removed flags, or outdated examples
77- Confirm links and relative paths still make sense
78- Confirm any new page is included in the relevant `_meta.ts`
79- Re-read the changed docs against the code diff, not against memory
80- If the diff added, moved, renamed, or removed a page under `docs/users/`,
81 verify the `qc-helper` bundled skill's topic-to-path index tables
82 (`packages/core/src/skills/bundled/qc-helper/SKILL.md`) are updated to
83 match. This skill ships with the CLI and uses hardcoded doc-path tables at
84 runtime — stale entries cause `/qc-helper` to miss the right documentation.
85 Also check project-level skills under `.qwen/skills/` for hardcoded
86 `docs/users/` references that may need updating.
87
88## Practical heuristics
89
90- If a change affects commands, also check quickstart, workflows, and feature
91 pages for drift.
92- If a change affects configuration, also check
93 `docs/users/configuration/settings.md`, feature pages, and auth/provider docs.
94- If a change affects tools or agent behavior, check both
95 `docs/users/features/**` and `docs/developers/tools/**` when relevant.
96- If tests reveal expected behavior more clearly than implementation code, use
97 tests to confirm wording.
98- If the change adds, moves, renames, or removes a docs page, also update
99 hardcoded doc-path consumers: `qc-helper`'s SKILL.md index tables,
100 `_meta.ts` navigation files, and any project-level skills under
101 `.qwen/skills/` that reference `docs/users/` paths.
102
103## Deliverable
104
105Produce the docs edits under `docs/` that make the current local changes
106understandable to a reader who has not seen the diff. Keep the final summary
107short and identify which pages were updated.