RomanNum3ral
/
gstack
mirror of https://github.com/garrytan/gstack.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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>
This commit is contained in:
Hermes Agent 2026-05-11 12:07:15 +00:00
parent 49cc4ff9c9
commit 1730a06135
2 changed files with 172 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
document-release/SKILL.md
View File

@ -4,10 +4,12 @@ preamble-tier: 2
version: 1.0.0 version: 1.0.0
description: | description: |
Post-ship documentation update. Reads all project docs, cross-references the Post-ship documentation update. Reads all project docs, cross-references the
diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation),
polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
asked to "update the docs", "sync documentation", or "post-ship docs". detects architecture diagram drift, polishes CHANGELOG voice with a sell-test
Proactively suggest after a PR is merged or code is shipped. (gstack) 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: allowed-tools:
- Bash - Bash
- Read - Read
@ -829,6 +831,47 @@ 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.
---
## Step 2: Per-File Documentation Audit ## Step 2: Per-File Documentation Audit
Read each documentation file and cross-reference it against the diff. Use these generic heuristics Read each documentation file and cross-reference it against the diff. Use these generic heuristics
@ -921,8 +964,11 @@ preserved them. This skill must NEVER do that.
**If CHANGELOG was modified in this branch**, review the entry for voice: **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, - **Sell test (Diataxis rubric):** Score each CHANGELOG entry 0-3:
rewrite the wording (not the content). - **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. - Lead with what the user can now **do** — not implementation details.
- "You can now..." not "Refactored the..." - "You can now..." not "Refactored the..."
- Flag and rewrite any entry that reads like a commit message. - Flag and rewrite any entry that reads like a commit message.
@ -1050,9 +1096,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 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. 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, 3. The Documentation section should include:
describe what specifically changed (e.g., "README.md: added /document-release to skills
table, updated skill count from 9 to 10"). 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: 4. Write the updated body back:
@ -1150,6 +1208,20 @@ Where status is one of:
- Already bumped — version was set by /ship - Already bumped — version was set by /ship
- Skipped — file does not exist - 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 ## Important Rules
@ -1160,5 +1232,10 @@ Where status is one of:
- **Be explicit about what changed.** Every edit gets a one-line summary. - **Be explicit about what changed.** Every edit gets a one-line summary.
- **Generic heuristics, not project-specific.** The audit checks work on any repo. - **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. - **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. The coverage
map is an audit tool, not a content generator.
- **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 - **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person
who hasn't seen the code. who hasn't seen the code.

95
document-release/SKILL.md.tmpl
View File

@ -4,10 +4,12 @@ preamble-tier: 2
version: 1.0.0 version: 1.0.0
description: | description: |
Post-ship documentation update. Reads all project docs, cross-references the Post-ship documentation update. Reads all project docs, cross-references the
diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation),
polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
asked to "update the docs", "sync documentation", or "post-ship docs". detects architecture diagram drift, polishes CHANGELOG voice with a sell-test
Proactively suggest after a PR is merged or code is shipped. (gstack) 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: allowed-tools:
- Bash - Bash
- Read - Read
@ -91,6 +93,47 @@ 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.
---
## Step 2: Per-File Documentation Audit ## Step 2: Per-File Documentation Audit
Read each documentation file and cross-reference it against the diff. Use these generic heuristics Read each documentation file and cross-reference it against the diff. Use these generic heuristics
@ -183,8 +226,11 @@ preserved them. This skill must NEVER do that.
**If CHANGELOG was modified in this branch**, review the entry for voice: **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, - **Sell test (Diataxis rubric):** Score each CHANGELOG entry 0-3:
rewrite the wording (not the content). - **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. - Lead with what the user can now **do** — not implementation details.
- "You can now..." not "Refactored the..." - "You can now..." not "Refactored the..."
- Flag and rewrite any entry that reads like a commit message. - Flag and rewrite any entry that reads like a commit message.
@ -312,9 +358,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 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. 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, 3. The Documentation section should include:
describe what specifically changed (e.g., "README.md: added /document-release to skills
table, updated skill count from 9 to 10"). 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: 4. Write the updated body back:
@ -412,6 +470,20 @@ Where status is one of:
- Already bumped — version was set by /ship - Already bumped — version was set by /ship
- Skipped — file does not exist - 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 ## Important Rules
@ -422,5 +494,10 @@ Where status is one of:
- **Be explicit about what changed.** Every edit gets a one-line summary. - **Be explicit about what changed.** Every edit gets a one-line summary.
- **Generic heuristics, not project-specific.** The audit checks work on any repo. - **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. - **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. The coverage
map is an audit tool, not a content generator.
- **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 - **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person
who hasn't seen the code. who hasn't seen the code.