Docs Audit And Refresh
Overview
Audit docs/ from the repository outward: inspect the current implementation,
identify documentation gaps or inaccuracies, and update the relevant pages. Keep
the work inside docs/ and treat code, tests, and current configuration
surfaces as the authoritative source.
Read references/audit-checklist.md before a
broad audit so the scan stays focused on high-signal areas.
Workflow
1. Build a current-state inventory
Inspect the repository areas that define user-facing or developer-facing
behavior.
- Read the relevant code, tests, schemas, and package surfaces.
- Focus on shipped behavior, stable configuration, exposed commands,
integrations, and developer workflows.
- Use the existing docs tree as a map of intended coverage, not as proof that
coverage is complete.
2. Compare implementation against docs/
Look for three classes of issues:
- Missing documentation for an existing feature, setting, tool, or workflow
- Incorrect documentation that contradicts the current codebase
- Stale documentation that uses old names, defaults, paths, or examples
Prefer proving a gap with repository evidence before editing. Use current code
and tests instead of intuition.
3. Prioritize by reader impact
Fix the highest-cost issues first:
- Broken onboarding, setup, auth, installation, or command flows
- Wrong settings, defaults, paths, or feature behavior
- Entirely missing documentation for a real surface area
- Lower-impact clarity or organization improvements
4. Refresh the docs
Update the smallest correct set of pages under docs/.
- Edit existing pages first
- Add new pages only for clear, durable gaps
- Update the nearest
_meta.ts when adding or moving pages
- Keep examples executable and aligned with the current repository structure
- Remove dead or misleading text instead of layering warnings on top
5. Validate the refresh
Before finishing:
- Search
docs/ for old terminology and replaced config keys
- Check neighboring pages for conflicting guidance
- Confirm new pages appear in the right
_meta.ts
- Re-read critical examples, commands, and paths against code or tests
- Verify bundled skill doc indices still match the current
docs/ tree.
The qc-helper bundled skill
(packages/core/src/skills/bundled/qc-helper/SKILL.md) maintains a
hardcoded table mapping topics to doc file paths. If you added, moved,
renamed, or removed a page under docs/users/, that table must be updated
to match. Check the Features and Configuration tables in the SKILL.md
against the actual files in docs/users/features/ and
docs/users/configuration/. Other bundled or project skills may also
reference doc paths — search for docs/users/ across .qwen/skills/ and
packages/core/src/skills/bundled/ to catch them.
Audit standards
- Favor breadth-first discovery, then depth on confirmed gaps.
- Do not rewrite large areas without evidence that they are wrong or missing.
- Keep README files out of scope for edits; limit changes to
docs/.
- Call out residual gaps if the audit finds issues that are too large to solve
in one pass.
Deliverable
Produce a focused docs refresh that makes the current repository more accurate
and complete. Summarize the audited surfaces and the concrete pages updated.
1---
2name: docs-audit-and-refresh
3description: Audit the repository's docs/ content against the current codebase,
4 find missing, incorrect, or stale documentation, and refresh the affected
5 pages. Use when the user asks to review docs coverage, find outdated docs,
6 compare docs with the current repo, or fix documentation drift across
7 features, settings, tools, or integrations.
8metadata:
9 source: https://skillmd.com/skills/qwenlm/docs-audit-and-refresh
10---
11
12# Docs Audit And Refresh
13
14## Overview
15
16Audit `docs/` from the repository outward: inspect the current implementation,
17identify documentation gaps or inaccuracies, and update the relevant pages. Keep
18the work inside `docs/` and treat code, tests, and current configuration
19surfaces as the authoritative source.
20
21Read [references/audit-checklist.md](references/audit-checklist.md) before a
22broad audit so the scan stays focused on high-signal areas.
23
24## Workflow
25
26### 1. Build a current-state inventory
27
28Inspect the repository areas that define user-facing or developer-facing
29behavior.
30
31- Read the relevant code, tests, schemas, and package surfaces.
32- Focus on shipped behavior, stable configuration, exposed commands,
33 integrations, and developer workflows.
34- Use the existing docs tree as a map of intended coverage, not as proof that
35 coverage is complete.
36
37### 2. Compare implementation against `docs/`
38
39Look for three classes of issues:
40
41- Missing documentation for an existing feature, setting, tool, or workflow
42- Incorrect documentation that contradicts the current codebase
43- Stale documentation that uses old names, defaults, paths, or examples
44
45Prefer proving a gap with repository evidence before editing. Use current code
46and tests instead of intuition.
47
48### 3. Prioritize by reader impact
49
50Fix the highest-cost issues first:
51
521. Broken onboarding, setup, auth, installation, or command flows
532. Wrong settings, defaults, paths, or feature behavior
543. Entirely missing documentation for a real surface area
554. Lower-impact clarity or organization improvements
56
57### 4. Refresh the docs
58
59Update the smallest correct set of pages under `docs/`.
60
61- Edit existing pages first
62- Add new pages only for clear, durable gaps
63- Update the nearest `_meta.ts` when adding or moving pages
64- Keep examples executable and aligned with the current repository structure
65- Remove dead or misleading text instead of layering warnings on top
66
67### 5. Validate the refresh
68
69Before finishing:
70
71- Search `docs/` for old terminology and replaced config keys
72- Check neighboring pages for conflicting guidance
73- Confirm new pages appear in the right `_meta.ts`
74- Re-read critical examples, commands, and paths against code or tests
75- Verify bundled skill doc indices still match the current `docs/` tree.
76 The `qc-helper` bundled skill
77 (`packages/core/src/skills/bundled/qc-helper/SKILL.md`) maintains a
78 hardcoded table mapping topics to doc file paths. If you added, moved,
79 renamed, or removed a page under `docs/users/`, that table must be updated
80 to match. Check the Features and Configuration tables in the SKILL.md
81 against the actual files in `docs/users/features/` and
82 `docs/users/configuration/`. Other bundled or project skills may also
83 reference doc paths — search for `docs/users/` across `.qwen/skills/` and
84 `packages/core/src/skills/bundled/` to catch them.
85
86## Audit standards
87
88- Favor breadth-first discovery, then depth on confirmed gaps.
89- Do not rewrite large areas without evidence that they are wrong or missing.
90- Keep README files out of scope for edits; limit changes to `docs/`.
91- Call out residual gaps if the audit finds issues that are too large to solve
92 in one pass.
93
94## Deliverable
95
96Produce a focused docs refresh that makes the current repository more accurate
97and complete. Summarize the audited surfaces and the concrete pages updated.