40e34deb7a
* 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>
5.1 KiB
How to document a feature you just shipped
This is the post-ship workflow: you merged a PR, the docs are stale, and you want a coverage map plus filled gaps in one pass. You'll run /document-release to audit, then /document-generate to fill the gaps it finds.
Prerequisites
- gstack installed (
./setupcomplete; verify withwhich gstackor by typing/in Claude Code and seeing skills listed) - The branch with your shipped feature is checked out
- A PR exists on GitHub or GitLab (recommended — the workflow updates the PR body with a coverage map)
If no PR exists yet, run /ship first to create one; that's what /document-release is designed to run against.
Steps
1. Audit current coverage
Run:
/document-release
The skill walks your diff against the base branch, extracts new public surface (skills, CLI flags, config options, API endpoints, new modules), and scores each entity across the four Diataxis quadrants. You'll see a coverage map like:
Coverage map:
[entity] [reference?] [how-to?] [tutorial?] [explanation?]
/new-skill ✅ AGENTS.md ❌ ❌ ❌
--new-flag ✅ README ✅ README ❌ ❌
FooProcessor ❌ ❌ ❌ ❌
Items with zero coverage are critical gaps. Items with only reference coverage are common gaps. Both land in the PR body as a ### Documentation Debt subsection so reviewers see them.
If /document-release reports everything is covered, you're done. Skip the rest of this how-to.
2. Read the documentation debt section in the PR body
Open your PR (the skill prints the URL). Scroll to ## Documentation → ### Documentation Debt. Each item is tagged with the Diataxis quadrant that would fill it:
### Documentation Debt
- ⚠️ /new-skill — has reference in AGENTS.md but no how-to example in README. Diataxis quadrant: how-to.
- ⚠️ FooProcessor — zero coverage. Diataxis quadrants: reference, explanation.
This is the input to the next step. Each line tells you what's missing and which quadrant fills it.
3. Fill the gaps with /document-generate
Run:
/document-generate
When the skill asks about scope, tell it the specific entities flagged in the debt section. The skill reads the codebase (its Step 1 archaeology phase is mandatory), partitions by Diataxis quadrant, and writes the missing docs.
You can also let the skill auto-discover: if /document-release passed you the gaps explicitly (it does this when chained), /document-generate already knows what to write.
4. Verify the gaps closed
Re-run /document-release:
/document-release
The coverage map should now show the previously-flagged entities with green checkmarks in the previously-empty quadrants. The PR body's Documentation Debt section should be empty or reduced to items you intentionally deferred.
Verification
Open your PR and confirm:
- The PR body has a
## Documentationsection with a doc-diff preview. - The
### Documentation Debtsubsection lists zero critical gaps (or only items you knowingly deferred). - Each generated doc file in
docs/opens cleanly and cross-links to siblings (reference → how-to → tutorial → explanation). - Run
grep -rE '\]\([^)]*\.md\)' docs/and verify no link points to a missing file.
If all four check, your PR is ready to land with complete documentation.
Troubleshooting
/document-release reports "No public surface changes detected."
The diff is internal-only (refactors, tests, infra). No docs are needed. Skip to landing.
The Diataxis quadrant tag on a gap doesn't match what you'd expect. The skill uses an entity taxonomy to decide which quadrants matter (CLI flags want reference + how-to; internal modules want reference + explanation; user-facing features want all four). If you disagree, you can override by hand-editing the docs after generation. The audit is a guide, not a constraint.
/document-generate writes a tutorial that takes 8 steps to reach a working result.
Tutorials should hit a working result in 3 steps or fewer. Re-run the skill and ask it to compress, or hand-edit. The Step 8 Quality Self-Review catches some of these but not all.
You want to document a feature but no PR exists yet.
Run /ship first to create the PR, then this workflow. Without a PR, /document-release can still audit but skips the PR-body update.
A generated reference doc has hallucinated API signatures. File a bug. The skill's Step 1 archaeology is supposed to read implementation files end-to-end, not just signatures, specifically to prevent this. Include the generated text and the actual code so we can trace why the archaeology missed it.
Related
- Tutorial: first time using
/document-generate: tutorial-document-generate.md - Why gstack uses the Diataxis framework: explanation-diataxis-in-gstack.md
- Reference for the audit skill:
document-release/SKILL.md - Reference for the generation skill:
document-generate/SKILL.md