You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**Information flow**: Conceptual content (trade-offs, when to use) should come before implementation details, not after
53
+
-**Admonition weight**: Tips, notes, and warnings should be supplementary. If an admonition contains primary feature documentation (full YAML examples, the only explanation of a field or concept), it should be promoted to a proper section or its own page. A good test: if this admonition is the only place a feature is documented, it's not a tip - it's a section that needs a heading and ToC visibility.
53
54
-**Diataxis alignment**: Don't mix tutorials, how-tos, reference, and concepts in one doc without clear separation
54
55
55
56
### LLM-Generated Content Patterns
@@ -79,6 +80,7 @@ The docs follow a product-area-based information architecture under `docs/toolhi
79
80
-**Inbound link coverage for new pages**: When a PR adds a new page, check that it is reachable beyond just the sidebar. New pages need inbound links from related pages (overviews, intros, feature lists, related how-to guides). A page with no inbound links is isolated in the user journey. For major new features, also check whether top-level intro/overview pages should mention the capability.
80
81
-**Introduction pages**: Each product section should have an Introduction as the first sidebar child. New sections must follow this pattern.
81
82
-**Progressive disclosure**: Core workflows should appear before advanced topics. Check that advanced content isn't mixed in with beginner-facing pages.
83
+
-**Pattern consistency for peer concepts**: When a PR introduces a new resource type, feature, or component that has established peers in the doc set, check whether it follows the same documentation pattern (dedicated page, equivalent depth of coverage, parallel sidebar placement). A new CRD documented only as a subsection of another page, when its peer CRDs each have their own page, is a structural gap.
82
84
-**Forward navigation path**: A reader should be able to follow "Next steps" links from the quickstart through core workflows without relying on the sidebar.
Copy file name to clipboardExpand all lines: .claude/skills/upstream-release-docs/SKILL.md
+15-4Lines changed: 15 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -85,17 +85,28 @@ For each PR identified in Phase 1 (skip internal/infra unless user requests):
85
85
- Do not attempt to fabricate the "why" or consumer story from code structure alone — this produces documentation that covers the "what" and "how" but misses the perspective and voice that only comes from understanding the product intent
86
86
- Incremental changes (new config options, default changes, annotation additions) can proceed without this step
87
87
88
-
5.**Read the actual source code at the release tag** to verify every claim made in the PR description:
88
+
5.**Check related repositories** — components often span multiple repos. For example, a server's CRD/operator may live in a different repo than the server itself. When a release changes config structures, API surfaces, or deployment models, check whether related repos (operators, CLIs, client libraries) have also released changes that affect the documentation. Ask the user which repos are related if unclear.
89
+
90
+
6.**Read the actual source code at the release tag** to verify every claim made in the PR description:
89
91
90
92
```bash
91
93
gh api repos/<OWNER>/<REPO>/contents/<PATH>?ref=<TAG>
92
94
```
93
95
94
96
The response is base64-encoded; decode it to read the content.
95
97
96
-
6. Note discrepancies between PR descriptions and actual code. Trust the code.
98
+
7. Note discrepancies between PR descriptions and actual code. Trust the code.
99
+
100
+
8.**Deep-verify behavioral claims** — these are the most common source of documentation inaccuracy. For each feature, verify not just struct definitions but actual runtime behavior:
101
+
-**API routes**: Check the actual route registration code (e.g., `r.Get`, `r.Post`, `r.Delete`), not just handler names. Docs often claim endpoints exist at paths where no handler is registered.
102
+
-**Required fields**: Check validation code (e.g., `if field == ""` checks), not just struct definitions. A field present in a struct is not necessarily required — only fields checked in validation logic are enforced.
103
+
-**Default values**: Check the actual defaulting code or fallback logic, not comments or struct tags. For example, "defaults to main" may actually mean "defaults to the remote's HEAD" in practice.
104
+
-**Precedence rules**: Read the actual `if/else` chain. For example, `if commit != "" { ... } else if branch != "" { ... } else if tag != "" { ... }` means commit > branch > tag, not commit > tag > branch.
105
+
-**Delete/cleanup behavior**: Check whether the code reassigns pointers, cascades deletes, or leaves orphans. Delete behavior is frequently mis-documented.
106
+
-**Query parameters**: Check whether parsed parameters are actually wired to the service layer and database queries. Parameters can be parsed from the URL but silently ignored if no service option or SQL filter exists for them.
107
+
-**Containment/authorization direction**: When documenting subset/superset checks, verify which argument is the caller and which is the resource. Getting the direction wrong produces examples that show the opposite of actual behavior.
97
108
98
-
7. Identify:
109
+
9. Identify:
99
110
-**Auto-generated content** — files generated from upstream (OpenAPI specs, CLI reference docs, JSON schemas). Do not manually edit these; flag them for automated update instead. However, auto-generated reference docs (e.g., API endpoints from a swagger spec) do **not** replace the need for conceptual explanations, guide content, or cross-references in existing pages. A new feature with auto-generated API docs still needs: (1) a conceptual explanation of what it is and why it exists, (2) mentions and cross-references in related existing pages (intro pages, feature lists, related guides), and (3) guide content if the feature has non-trivial workflows. Only skip creating a **duplicate API reference page** — never skip the surrounding documentation.
100
111
-**Hidden/experimental features** — look for indicators like `Hidden: true` in CLI command definitions, feature flags, or internal-only annotations. Do not document these unless the user explicitly asks.
101
112
@@ -167,7 +178,7 @@ Apply the approved changes:
167
178
168
179
## Phase 5: Validation
169
180
170
-
1.**Re-verify every factual claim** against source code at the tag. This is the third verification pass (after Phase 2 and Phase 4).
181
+
1.**Re-verify every factual claim** against source code at the tag. This is the third verification pass (after Phase 2 and Phase 4). For large doc sets, spawn parallel verification agents — one per file or topic area — to check all claims concurrently. Each agent should read the doc file and verify every factual claim (struct fields, API routes, defaults, behavioral logic) against the actual source code at the release tag. Collect and resolve any discrepancies before proceeding.
171
182
172
183
2.**Build the site** — run the project's build command to check for broken links, missing references, or build errors.
0 commit comments