mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-17 17:51:27 +08:00
v1.35.0.0 feat: add /document-generate skill + enhance /document-release with Diataxis coverage map (#1477)
* feat(document-release): add Diataxis coverage map, diagram drift detection, and docs debt tracking Inspired by @doodlestein's documentation-website skill. Three key ideas incorporated: 1. Step 1.5: Coverage Map (Blast-Radius Analysis) — before editing any docs, scan the diff for new public surface and assess documentation coverage across Diataxis quadrants (reference/how-to/tutorial/explanation). Flags gaps without auto-generating content. 2. Architecture diagram drift detection — extracts entity names from ASCII/Mermaid diagrams and cross-references against the diff to catch stale diagrams. 3. Enhanced CHANGELOG sell test — Diataxis rubric scoring (0-3) replaces the subjective 'would a user want this?' check. 4. Documentation Debt section in PR body — surfaces coverage gaps and diagram drift as actionable items for future work. All changes are audit-only: the skill flags what's missing, never auto-generates missing documentation pages. Stays in its lane as a post-ship updater. Co-Authored-By: Hermes Agent <agent@nousresearch.com> * feat(document-generate): add Diataxis documentation generation skill New /document-generate skill, the companion to /document-release. While /document-release audits and fixes existing docs post-ship, /document-generate writes missing documentation from scratch using the Diataxis framework. Inspired by doodlestein documentation-website-for-software-project skill. Co-Authored-By: Hermes Agent <agent@nousresearch.com> * chore(docs): regenerate gstack/llms.txt with /document-generate entry CI's check-freshness step ran gen:skill-docs and found llms.txt stale — the index wasn't regenerated when /document-generate was added in the preceding commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(docs): regen document-generate/SKILL.md after merging main Main brought in the Non-ASCII characters directive in the AskUserQuestion Format resolver (scripts/resolvers/preamble/generate-ask-user-format.ts). Regenerating document-generate/SKILL.md propagates the new section into the generated output. check-freshness should now pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(CLAUDE.md): add workflow for fork PRs from garrytan-agents Fork PRs from non-collaborators don't get base-repo secrets passed to their CI workflows, so eval/E2E jobs fail with empty-env auth. New section: when checking out a PR from garrytan-agents, push the branch to garrytan/gstack and re-target the PR from there. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: sync project docs for v1.35.0.0 + bump VERSION - README.md: add /document-generate to skills table (Technical Writer category) + install-command skill lists - CLAUDE.md: add document-generate/ to project structure tree - SKILL.md.tmpl + regenerated SKILL.md: add /document-generate routing line ("write docs from scratch") - VERSION: 1.34.0.0 → 1.35.0.0 (MINOR: new skill + enhancement) CHANGELOG entry deferred to /ship. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v1.35.0.0) CHANGELOG entry for the document-generate skill + document-release Diataxis enhancements. package.json synced to VERSION (drift repair after merging main which had bumped pkg to 1.34.2.0). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: generate /document-generate Diataxis docs (tutorial + how-to + explanation) Fills the documentation debt items flagged by /document-release in PR #1477: critical-gap tutorial coverage and common-gap explanation coverage for the new /document-generate skill. Quadrants: tutorial, how-to, explanation (reference already covered by document-generate/SKILL.md). - docs/tutorial-document-generate.md (1009 words): newcomer 90-second flow - docs/howto-document-a-shipped-feature.md (770 words): post-ship audit + fill workflow - docs/explanation-diataxis-in-gstack.md (1106 words): why Diataxis, trade-offs, alternatives - README.md: links the three docs from the /document-generate skills-table row All cross-links verified — every Related section points at an existing file. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Hermes Agent <agent@nousresearch.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -4,10 +4,12 @@ preamble-tier: 2
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Post-ship documentation update. Reads all project docs, cross-references the
|
||||
diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
|
||||
polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when
|
||||
asked to "update the docs", "sync documentation", or "post-ship docs".
|
||||
Proactively suggest after a PR is merged or code is shipped. (gstack)
|
||||
diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation),
|
||||
updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
|
||||
detects architecture diagram drift, polishes CHANGELOG voice with a sell-test
|
||||
rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation
|
||||
debt in the PR body. Use when asked to "update the docs", "sync documentation",
|
||||
or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. (gstack)
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
@@ -850,6 +852,48 @@ find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules
|
||||
|
||||
---
|
||||
|
||||
## Step 1.5: Coverage Map (Blast-Radius Analysis)
|
||||
|
||||
Before touching any documentation file, build a **coverage map** of what shipped vs what's
|
||||
documented. This is inspired by the Diataxis framework (tutorial / how-to / reference / explanation)
|
||||
— but applied as an audit lens, not a generation tool.
|
||||
|
||||
1. **Extract public surface changes from the diff.** Scan `git diff <base>...HEAD` for:
|
||||
- New exported functions, classes, commands, CLI flags, config options, API endpoints
|
||||
- New skills, workflows, or user-facing capabilities
|
||||
- Renamed or removed public surface (modules, commands, features)
|
||||
- New environment variables, feature flags, or configuration knobs
|
||||
|
||||
2. **For each new/changed public surface item, assess documentation coverage:**
|
||||
|
||||
```
|
||||
Coverage map:
|
||||
[entity] [reference?] [how-to?] [tutorial?] [explanation?]
|
||||
/new-skill ✅ AGENTS.md ❌ ❌ ❌
|
||||
--new-flag ✅ README ✅ README ❌ ❌
|
||||
FooProcessor ❌ ❌ ❌ ❌
|
||||
```
|
||||
|
||||
Use these definitions:
|
||||
- **Reference** — factual description of what it is, its API, its options (README tables, AGENTS.md skill lists, API docs)
|
||||
- **How-to** — task-oriented: "how to do X with this" (README examples, CONTRIBUTING workflows)
|
||||
- **Tutorial** — learning-oriented: step-by-step walkthrough for newcomers (getting started guides)
|
||||
- **Explanation** — understanding-oriented: "why this works this way" (ARCHITECTURE decisions, design rationale)
|
||||
|
||||
3. **Output the coverage map.** Items with zero coverage are **critical gaps** — flag them for
|
||||
Step 3. Items with reference-only coverage are **common gaps** — note them for the PR body.
|
||||
|
||||
4. **Architecture diagram drift detection.** If ARCHITECTURE.md (or any doc) contains ASCII
|
||||
diagrams or Mermaid blocks, extract entity names (modules, services, data flows) from the
|
||||
diagrams. Cross-reference against the diff. Flag any diagram entities that were renamed,
|
||||
split, removed, or moved in the code.
|
||||
|
||||
The coverage map feeds into Steps 2-3 (what to audit and fix) and Step 9 (documentation debt
|
||||
summary in the PR body). Do NOT auto-generate missing documentation pages — flag gaps only.
|
||||
When significant gaps are found, suggest running `/document-generate` to fill them.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Per-File Documentation Audit
|
||||
|
||||
Read each documentation file and cross-reference it against the diff. Use these generic heuristics
|
||||
@@ -942,8 +986,11 @@ preserved them. This skill must NEVER do that.
|
||||
|
||||
**If CHANGELOG was modified in this branch**, review the entry for voice:
|
||||
|
||||
- **Sell test:** Would a user reading each bullet think "oh nice, I want to try that"? If not,
|
||||
rewrite the wording (not the content).
|
||||
- **Sell test (Diataxis rubric):** Score each CHANGELOG entry 0-3:
|
||||
- **1 point** — answers "What changed?" (reference: names the feature/fix)
|
||||
- **1 point** — answers "Why should I care?" (explanation: user impact, pain removed)
|
||||
- **1 point** — answers "How do I use it?" (how-to: command, flag, or link to docs)
|
||||
- Entries scoring <2 need a rewrite. Entries scoring 3 are gold.
|
||||
- Lead with what the user can now **do** — not implementation details.
|
||||
- "You can now..." not "Refactored the..."
|
||||
- Flag and rewrite any entry that reads like a commit message.
|
||||
@@ -1071,9 +1118,21 @@ glab mr view -F json 2>/dev/null | python3 -c "import sys,json; print(json.load(
|
||||
2. If the tempfile already contains a `## Documentation` section, replace that section with the
|
||||
updated content. If it does not contain one, append a `## Documentation` section at the end.
|
||||
|
||||
3. The Documentation section should include a **doc diff preview** — for each file modified,
|
||||
describe what specifically changed (e.g., "README.md: added /document-release to skills
|
||||
table, updated skill count from 9 to 10").
|
||||
3. The Documentation section should include:
|
||||
|
||||
a. **Doc diff preview** — for each file modified, describe what specifically changed (e.g.,
|
||||
"README.md: added /document-release to skills table, updated skill count from 9 to 10").
|
||||
|
||||
b. **Documentation debt** — if the coverage map from Step 1.5 found gaps, append a
|
||||
`### Documentation Debt` subsection listing:
|
||||
- Critical gaps: new public surface with zero documentation coverage
|
||||
- Common gaps: features with reference-only coverage (no how-to or tutorial)
|
||||
- Stale diagrams: architecture diagrams with entity names that drifted from the code
|
||||
- Each item should include a one-line description of what's missing and which Diataxis
|
||||
quadrant would fill it (e.g., "⚠️ `/new-skill` — has reference in AGENTS.md but no
|
||||
how-to example in README")
|
||||
|
||||
If there are any documentation debt items, suggest adding a `docs-debt` label to the PR.
|
||||
|
||||
4. Write the updated body back:
|
||||
|
||||
@@ -1171,6 +1230,20 @@ Where status is one of:
|
||||
- Already bumped — version was set by /ship
|
||||
- Skipped — file does not exist
|
||||
|
||||
If the coverage map from Step 1.5 identified any gaps, append:
|
||||
|
||||
```
|
||||
Documentation coverage:
|
||||
[entity] [reference] [how-to] [tutorial] [explanation]
|
||||
/new-skill ✅ ❌ ❌ ❌
|
||||
--new-flag ✅ ✅ ❌ ❌
|
||||
|
||||
Diagram drift:
|
||||
ARCHITECTURE.md: "FooProcessor" renamed to "BarProcessor" in code — diagram may be stale
|
||||
```
|
||||
|
||||
If all coverage is complete and no diagrams drifted, output: "Coverage: all shipped features have adequate documentation."
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
@@ -1181,5 +1254,10 @@ Where status is one of:
|
||||
- **Be explicit about what changed.** Every edit gets a one-line summary.
|
||||
- **Generic heuristics, not project-specific.** The audit checks work on any repo.
|
||||
- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md.
|
||||
- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body
|
||||
and future work. It does NOT auto-generate missing documentation pages or sections. When gaps
|
||||
are found, suggest `/document-generate` as the follow-up skill.
|
||||
- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not
|
||||
auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly.
|
||||
- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person
|
||||
who hasn't seen the code.
|
||||
|
||||
@@ -4,10 +4,12 @@ preamble-tier: 2
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Post-ship documentation update. Reads all project docs, cross-references the
|
||||
diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
|
||||
polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when
|
||||
asked to "update the docs", "sync documentation", or "post-ship docs".
|
||||
Proactively suggest after a PR is merged or code is shipped. (gstack)
|
||||
diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation),
|
||||
updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
|
||||
detects architecture diagram drift, polishes CHANGELOG voice with a sell-test
|
||||
rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation
|
||||
debt in the PR body. Use when asked to "update the docs", "sync documentation",
|
||||
or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. (gstack)
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
@@ -91,6 +93,48 @@ find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules
|
||||
|
||||
---
|
||||
|
||||
## Step 1.5: Coverage Map (Blast-Radius Analysis)
|
||||
|
||||
Before touching any documentation file, build a **coverage map** of what shipped vs what's
|
||||
documented. This is inspired by the Diataxis framework (tutorial / how-to / reference / explanation)
|
||||
— but applied as an audit lens, not a generation tool.
|
||||
|
||||
1. **Extract public surface changes from the diff.** Scan `git diff <base>...HEAD` for:
|
||||
- New exported functions, classes, commands, CLI flags, config options, API endpoints
|
||||
- New skills, workflows, or user-facing capabilities
|
||||
- Renamed or removed public surface (modules, commands, features)
|
||||
- New environment variables, feature flags, or configuration knobs
|
||||
|
||||
2. **For each new/changed public surface item, assess documentation coverage:**
|
||||
|
||||
```
|
||||
Coverage map:
|
||||
[entity] [reference?] [how-to?] [tutorial?] [explanation?]
|
||||
/new-skill ✅ AGENTS.md ❌ ❌ ❌
|
||||
--new-flag ✅ README ✅ README ❌ ❌
|
||||
FooProcessor ❌ ❌ ❌ ❌
|
||||
```
|
||||
|
||||
Use these definitions:
|
||||
- **Reference** — factual description of what it is, its API, its options (README tables, AGENTS.md skill lists, API docs)
|
||||
- **How-to** — task-oriented: "how to do X with this" (README examples, CONTRIBUTING workflows)
|
||||
- **Tutorial** — learning-oriented: step-by-step walkthrough for newcomers (getting started guides)
|
||||
- **Explanation** — understanding-oriented: "why this works this way" (ARCHITECTURE decisions, design rationale)
|
||||
|
||||
3. **Output the coverage map.** Items with zero coverage are **critical gaps** — flag them for
|
||||
Step 3. Items with reference-only coverage are **common gaps** — note them for the PR body.
|
||||
|
||||
4. **Architecture diagram drift detection.** If ARCHITECTURE.md (or any doc) contains ASCII
|
||||
diagrams or Mermaid blocks, extract entity names (modules, services, data flows) from the
|
||||
diagrams. Cross-reference against the diff. Flag any diagram entities that were renamed,
|
||||
split, removed, or moved in the code.
|
||||
|
||||
The coverage map feeds into Steps 2-3 (what to audit and fix) and Step 9 (documentation debt
|
||||
summary in the PR body). Do NOT auto-generate missing documentation pages — flag gaps only.
|
||||
When significant gaps are found, suggest running `/document-generate` to fill them.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Per-File Documentation Audit
|
||||
|
||||
Read each documentation file and cross-reference it against the diff. Use these generic heuristics
|
||||
@@ -183,8 +227,11 @@ preserved them. This skill must NEVER do that.
|
||||
|
||||
**If CHANGELOG was modified in this branch**, review the entry for voice:
|
||||
|
||||
- **Sell test:** Would a user reading each bullet think "oh nice, I want to try that"? If not,
|
||||
rewrite the wording (not the content).
|
||||
- **Sell test (Diataxis rubric):** Score each CHANGELOG entry 0-3:
|
||||
- **1 point** — answers "What changed?" (reference: names the feature/fix)
|
||||
- **1 point** — answers "Why should I care?" (explanation: user impact, pain removed)
|
||||
- **1 point** — answers "How do I use it?" (how-to: command, flag, or link to docs)
|
||||
- Entries scoring <2 need a rewrite. Entries scoring 3 are gold.
|
||||
- Lead with what the user can now **do** — not implementation details.
|
||||
- "You can now..." not "Refactored the..."
|
||||
- Flag and rewrite any entry that reads like a commit message.
|
||||
@@ -312,9 +359,21 @@ glab mr view -F json 2>/dev/null | python3 -c "import sys,json; print(json.load(
|
||||
2. If the tempfile already contains a `## Documentation` section, replace that section with the
|
||||
updated content. If it does not contain one, append a `## Documentation` section at the end.
|
||||
|
||||
3. The Documentation section should include a **doc diff preview** — for each file modified,
|
||||
describe what specifically changed (e.g., "README.md: added /document-release to skills
|
||||
table, updated skill count from 9 to 10").
|
||||
3. The Documentation section should include:
|
||||
|
||||
a. **Doc diff preview** — for each file modified, describe what specifically changed (e.g.,
|
||||
"README.md: added /document-release to skills table, updated skill count from 9 to 10").
|
||||
|
||||
b. **Documentation debt** — if the coverage map from Step 1.5 found gaps, append a
|
||||
`### Documentation Debt` subsection listing:
|
||||
- Critical gaps: new public surface with zero documentation coverage
|
||||
- Common gaps: features with reference-only coverage (no how-to or tutorial)
|
||||
- Stale diagrams: architecture diagrams with entity names that drifted from the code
|
||||
- Each item should include a one-line description of what's missing and which Diataxis
|
||||
quadrant would fill it (e.g., "⚠️ `/new-skill` — has reference in AGENTS.md but no
|
||||
how-to example in README")
|
||||
|
||||
If there are any documentation debt items, suggest adding a `docs-debt` label to the PR.
|
||||
|
||||
4. Write the updated body back:
|
||||
|
||||
@@ -412,6 +471,20 @@ Where status is one of:
|
||||
- Already bumped — version was set by /ship
|
||||
- Skipped — file does not exist
|
||||
|
||||
If the coverage map from Step 1.5 identified any gaps, append:
|
||||
|
||||
```
|
||||
Documentation coverage:
|
||||
[entity] [reference] [how-to] [tutorial] [explanation]
|
||||
/new-skill ✅ ❌ ❌ ❌
|
||||
--new-flag ✅ ✅ ❌ ❌
|
||||
|
||||
Diagram drift:
|
||||
ARCHITECTURE.md: "FooProcessor" renamed to "BarProcessor" in code — diagram may be stale
|
||||
```
|
||||
|
||||
If all coverage is complete and no diagrams drifted, output: "Coverage: all shipped features have adequate documentation."
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
@@ -422,5 +495,10 @@ Where status is one of:
|
||||
- **Be explicit about what changed.** Every edit gets a one-line summary.
|
||||
- **Generic heuristics, not project-specific.** The audit checks work on any repo.
|
||||
- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md.
|
||||
- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body
|
||||
and future work. It does NOT auto-generate missing documentation pages or sections. When gaps
|
||||
are found, suggest `/document-generate` as the follow-up skill.
|
||||
- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not
|
||||
auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly.
|
||||
- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person
|
||||
who hasn't seen the code.
|
||||
|
||||
Reference in New Issue
Block a user