mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-16 01:02:13 +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
49
CHANGELOG.md
49
CHANGELOG.md
@@ -1,5 +1,54 @@
|
||||
# Changelog
|
||||
|
||||
## [1.35.0.0] - 2026-05-13
|
||||
|
||||
## **Docs become a tracked surface, not an afterthought. `/document-generate` writes them from scratch, `/document-release` audits coverage in four Diataxis quadrants.**
|
||||
## **Every PR now ships a coverage map of what got documented vs what shipped. New skill generates tutorials, how-tos, references, and explanations from code. Both speak the same vocabulary, so gaps become visible in the PR body instead of accumulating silently.**
|
||||
|
||||
You can now run `/document-generate` to write missing documentation from scratch. The skill reads your code first (the codebase archaeology step is non-skippable), maps the public surface, then writes docs in the four Diataxis quadrants: tutorial (newcomer walkthrough), how-to (task-oriented), reference (factual API description), explanation (design rationale). It runs standalone or chains automatically from `/document-release` when the coverage map finds gaps. `/document-release` got a Step 1.5 coverage map that scores every new entity across the four quadrants. Items with zero coverage show up as critical gaps in the PR body. Items with reference-only coverage show up as common gaps. Architecture diagrams get scanned for entity-name drift against the diff. The CHANGELOG voice check now uses a 0-3 sell-test rubric: 1 point each for "what changed?", "why care?", and "how to use it?". Entries below 2 get rewritten.
|
||||
|
||||
A new section in CLAUDE.md documents the fork-PR workflow for `garrytan-agents` PRs: push the branch to `garrytan/gstack` and re-target so eval CI can access secrets. The pattern keeps secret distribution scoped to one branch instead of broadening it to all forks.
|
||||
|
||||
### The numbers that matter
|
||||
|
||||
Source: this PR's diff against `origin/main` and the new skill template at `document-generate/SKILL.md.tmpl`.
|
||||
|
||||
| Surface | Before | After |
|
||||
|---------|--------|-------|
|
||||
| Doc-generation skills | 1 (`/document-release`) | 2 (`/document-generate` + enhanced `/document-release`) |
|
||||
| Diataxis quadrants surfaced in PR body | 0 | 4 (tutorial / how-to / reference / explanation) |
|
||||
| `/document-release` workflow steps | 9 | 9 + new Step 1.5 (coverage map) |
|
||||
| CHANGELOG voice scoring | gut-check ("would a user think 'oh nice'?") | 0-3 rubric (3 = reference + explanation + how-to all present) |
|
||||
| Architecture diagram drift detection | none | scans ARCHITECTURE.md against diff for renamed/removed entities |
|
||||
| Doc-debt visibility in PR | none | `### Documentation Debt` subsection with critical + common gaps per Diataxis quadrant |
|
||||
|
||||
`/document-generate` is 446 lines of new template producing a 1184-line generated SKILL.md. The Diataxis vocabulary makes "did docs get updated?" a visible answer instead of an implicit one.
|
||||
|
||||
### What this means for downstream gstack users
|
||||
|
||||
You stop guessing whether your docs are complete. When you ship a new skill, `/document-release` shows you which quadrants you covered and which you skipped, and the gaps land in the PR body where reviewers see them. When you want to bootstrap docs for an existing project, `/document-generate` walks you from zero to four-quadrant coverage in one session. Diataxis becomes the shared vocabulary across `/ship`, `/document-release`, `/document-generate`, and whatever skill comes next that needs to know whether you have a tutorial.
|
||||
|
||||
To use: run `/document-release` after `/ship` (or let `/ship` auto-invoke it), see the coverage map in the PR body, then run `/document-generate` if it flags critical gaps.
|
||||
|
||||
### Itemized changes
|
||||
|
||||
#### Added
|
||||
- **`/document-generate` skill** (`document-generate/SKILL.md.tmpl`, 446 lines): Diataxis-based documentation generator with 9-step workflow — scope, codebase archaeology, partition, reference, explanation, how-to, tutorial, cross-linking, quality self-review. Reads the full codebase before writing a single line of docs.
|
||||
- **`/document-release` Step 1.5 — Coverage Map**: scans diff for new public surface (skills, CLI flags, config options, API endpoints), classifies each entity by Diataxis quadrant coverage, flags zero-coverage items as critical gaps and reference-only as common gaps. Output feeds the PR body.
|
||||
- **`/document-release` Architecture diagram drift detection**: extracts entity names from ASCII/Mermaid blocks in ARCHITECTURE.md, cross-references against the diff, flags renamed/removed entities.
|
||||
- **`/document-release` `### Documentation Debt` section in PR body**: surfaces critical gaps, common gaps, and stale diagrams with a one-line description + Diataxis quadrant per item. Suggests adding a `docs-debt` label.
|
||||
- **`/document-release` CHANGELOG sell-test rubric**: 0-3 scoring per entry (1 point each for reference / explanation / how-to coverage). Entries below 2 get rewritten.
|
||||
- **Skill routing entry**: `/document-generate` added to `SKILL.md` routing rules and `README.md` skills table (Technical Writer category).
|
||||
- **CLAUDE.md fork-PR workflow section**: documents how to handle "check out <PR link>" when the PR is from a non-collaborator fork. Push the branch to `garrytan/gstack`, close the fork PR, open a new PR from the base-repo branch. Keeps secret distribution scoped.
|
||||
|
||||
#### Changed
|
||||
- `/document-release` description and triggers updated to reference the coverage map and `/document-generate` chaining.
|
||||
- README.md skills table grouping: `/document-release` and `/document-generate` now appear under the Technical Writer category.
|
||||
|
||||
#### For contributors
|
||||
- `document-generate/SKILL.md` is generated from `document-generate/SKILL.md.tmpl`. Do not edit the `.md` directly. Run `bun run gen:skill-docs` after template edits.
|
||||
- `gstack/llms.txt` now lists `/document-generate` (auto-regenerated from the skill template).
|
||||
|
||||
## [1.34.2.0] - 2026-05-13
|
||||
|
||||
## **Three filed bugs land in one PR. `/codex review`, `/investigate` learnings, and `/sync-gbrain` engine detection all work again.**
|
||||
|
||||
33
CLAUDE.md
33
CLAUDE.md
@@ -122,7 +122,8 @@ gstack/
|
||||
├── investigate/ # /investigate skill (systematic root-cause debugging)
|
||||
├── retro/ # Retrospective skill (includes /retro global cross-project mode)
|
||||
├── bin/ # CLI utilities (gstack-repo-mode, gstack-slug, gstack-config, etc.)
|
||||
├── document-release/ # /document-release skill (post-ship doc updates)
|
||||
├── document-release/ # /document-release skill (post-ship doc updates + Diataxis coverage map)
|
||||
├── document-generate/ # /document-generate skill (Diataxis doc generator: tutorial/how-to/reference/explanation)
|
||||
├── cso/ # /cso skill (OWASP Top 10 + STRIDE security audit)
|
||||
├── design-consultation/ # /design-consultation skill (design system from scratch)
|
||||
├── design-shotgun/ # /design-shotgun skill (visual design exploration)
|
||||
@@ -452,6 +453,36 @@ Even if the agent strongly believes a change improves the project, these three
|
||||
categories require explicit user approval via AskUserQuestion. No exceptions.
|
||||
No auto-merging. No "I'll just clean this up."
|
||||
|
||||
## Checking out PRs from garrytan-agents
|
||||
|
||||
When the user says "check out <PR link>" and the PR is from `garrytan-agents/gstack`
|
||||
(or any other fork that is NOT a collaborator on `garrytan/gstack`), do NOT just
|
||||
`gh pr checkout`. Fork PRs don't receive base-repo secrets (`ANTHROPIC_API_KEY`,
|
||||
`OPENAI_API_KEY`, etc.), so the eval/E2E CI jobs fail with empty-env auth errors
|
||||
regardless of what's set on the base repo.
|
||||
|
||||
**Workflow:** push the branch to `garrytan/gstack` (the base repo) and re-target
|
||||
the PR from there.
|
||||
|
||||
Concretely, after `gh pr checkout <N>`:
|
||||
|
||||
1. Note the original PR number and head branch name.
|
||||
2. Push the same branch to the base repo: `git push origin HEAD:<branch-name>`
|
||||
(origin = `garrytan/gstack`, since the worktree is set up with that remote).
|
||||
3. Close the fork PR (`gh pr close <N> --comment "moving to base-repo branch for secret access"`).
|
||||
4. Open a new PR from the base-repo branch: `gh pr create --base main --head <branch-name>`.
|
||||
5. New PR's workflows will get secrets automatically.
|
||||
|
||||
Why not fix it on the fork side? `garrytan-agents` isn't a collaborator on
|
||||
`garrytan/gstack`. Adding it as a collaborator (option A) or flipping the
|
||||
repo-wide "send secrets to fork PRs" toggle (option B) would let secrets reach
|
||||
fork PRs from anyone — broader blast radius than just moving this one branch.
|
||||
Option C (this section) keeps secret-distribution scope tight.
|
||||
|
||||
If the user asks you to skip the move (e.g., "just leave it as a fork PR"),
|
||||
respect that — eval CI will fail with empty-env auth, but check-freshness,
|
||||
workflow-lint, and windows-tests will still pass on the fork PR.
|
||||
|
||||
## CHANGELOG + VERSION style
|
||||
|
||||
**Versioning invariant (workspace-aware ship).** VERSION is a monotonic ordered
|
||||
|
||||
10
README.md
10
README.md
@@ -48,7 +48,7 @@ Fork it. Improve it. Make it yours. And if you want to hate on free open source
|
||||
|
||||
Open Claude Code and paste this. Claude does the rest.
|
||||
|
||||
> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it.
|
||||
> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /document-generate, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it.
|
||||
|
||||
### Step 2: Team mode — auto-update for shared repos (recommended)
|
||||
|
||||
@@ -198,7 +198,8 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
|
||||
| `/land-and-deploy` | **Release Engineer** | Merge the PR, wait for CI and deploy, verify production health. One command from "approved" to "verified in production." |
|
||||
| `/canary` | **SRE** | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures. |
|
||||
| `/benchmark` | **Performance Engineer** | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. |
|
||||
| `/document-release` | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. |
|
||||
| `/document-release` | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. Builds a Diataxis coverage map (reference / how-to / tutorial / explanation) so gaps are visible in the PR body. |
|
||||
| `/document-generate` | **Documentation Author** | Generate missing docs from scratch using the Diataxis framework. Researches the codebase first, then writes reference / how-to / tutorial / explanation docs that actually match the code. Invokable standalone or chained from `/document-release` when the coverage map finds gaps. Learn more: [tutorial](docs/tutorial-document-generate.md) • [how-to](docs/howto-document-a-shipped-feature.md) • [why Diataxis](docs/explanation-diataxis-in-gstack.md). |
|
||||
| `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. `/retro global` runs across all your projects and AI tools (Claude Code, Codex, Gemini). |
|
||||
| `/browse` | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. `/open-gstack-browser` launches GStack Browser with sidebar, anti-bot stealth, and auto model routing. |
|
||||
| `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
|
||||
@@ -466,8 +467,9 @@ Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__*
|
||||
Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review,
|
||||
/design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy,
|
||||
/canary, /benchmark, /browse, /open-gstack-browser, /qa, /qa-only, /design-review,
|
||||
/setup-browser-cookies, /setup-deploy, /setup-gbrain, /sync-gbrain, /retro, /investigate, /document-release,
|
||||
/codex, /cso, /autoplan, /pair-agent, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn.
|
||||
/setup-browser-cookies, /setup-deploy, /setup-gbrain, /sync-gbrain, /retro, /investigate,
|
||||
/document-release, /document-generate, /codex, /cso, /autoplan, /pair-agent, /careful, /freeze,
|
||||
/guard, /unfreeze, /gstack-upgrade, /learn.
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
1
SKILL.md
1
SKILL.md
@@ -505,6 +505,7 @@ quality gates that produce better results than answering inline.
|
||||
- User asks to configure deployment for the project → invoke `/setup-deploy`
|
||||
- User asks to monitor prod after shipping, post-deploy checks → invoke `/canary`
|
||||
- User asks to update docs after shipping → invoke `/document-release`
|
||||
- User asks to write docs from scratch, generate documentation, "document this feature/module" → invoke `/document-generate`
|
||||
- User asks for a weekly retro, what did we ship, "how'd we do" → invoke `/retro`
|
||||
- User asks for a second opinion, codex review → invoke `/codex`
|
||||
- User asks for safety mode, careful mode → invoke `/careful` or `/guard`
|
||||
|
||||
@@ -49,6 +49,7 @@ quality gates that produce better results than answering inline.
|
||||
- User asks to configure deployment for the project → invoke `/setup-deploy`
|
||||
- User asks to monitor prod after shipping, post-deploy checks → invoke `/canary`
|
||||
- User asks to update docs after shipping → invoke `/document-release`
|
||||
- User asks to write docs from scratch, generate documentation, "document this feature/module" → invoke `/document-generate`
|
||||
- User asks for a weekly retro, what did we ship, "how'd we do" → invoke `/retro`
|
||||
- User asks for a second opinion, codex review → invoke `/codex`
|
||||
- User asks for safety mode, careful mode → invoke `/careful` or `/guard`
|
||||
|
||||
79
docs/explanation-diataxis-in-gstack.md
Normal file
79
docs/explanation-diataxis-in-gstack.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# Why gstack uses Diataxis for documentation
|
||||
|
||||
The two doc skills in gstack — `/document-release` and `/document-generate` — both speak Diataxis. New entities get scored across four quadrants. Coverage gaps surface in PR bodies tagged by quadrant. This doc explains why that vocabulary is load-bearing, and why a simpler "just write markdown" approach falls down at the scale gstack operates at.
|
||||
|
||||
## The problem
|
||||
|
||||
Documentation rot is the easiest kind of rot to ignore. Code stops compiling and you notice immediately. A test fails and CI screams. Docs go stale silently — the README still parses, the install command still copy-pastes — and the only signal is a confused user weeks later filing an issue or quietly walking away.
|
||||
|
||||
gstack has more than 45 skills. Every one is a SKILL.md plus a `.tmpl` template plus, ideally, a getting-started tutorial somewhere and an explanation of why it works the way it does. Multiply that by however many gstack users have similar surface-area in their own projects and the maintenance load is real.
|
||||
|
||||
The naive failure mode is "every team writes docs in their own format." One project has a Wiki. Another has nested README files. A third has reference-only API docs and no tutorials. A fourth has tutorials that no longer compile. You can't write tooling that audits across all of those because there's no shared vocabulary for what good coverage means.
|
||||
|
||||
The second failure mode is more subtle: even when a team is disciplined, they tend to write the kind of doc that matches their current state of mind. Engineers in build mode write reference. Engineers in launch mode write tutorials. Engineers in maintenance mode write troubleshooting how-tos. No one wakes up and says "today I'll write the explanation doc for why we chose this architecture" — so explanation rot accumulates fastest.
|
||||
|
||||
## The approach
|
||||
|
||||
Diataxis (Daniele Procida, originally at Divio, now adopted across CPython, Django, NumPy, FastAPI, GitHub docs, and many others) splits documentation into four quadrants based on **reader intent**:
|
||||
|
||||
```
|
||||
THEORETICAL PRACTICAL
|
||||
(understanding) (doing)
|
||||
|
||||
STUDY +-----------------------------+----------------------------+
|
||||
(learning) | | |
|
||||
| EXPLANATION | TUTORIAL |
|
||||
| "Why does X exist?" | "Walk me through X |
|
||||
| | for the first time" |
|
||||
| discusses code | teaches code |
|
||||
| | |
|
||||
+-----------------------------+----------------------------+
|
||||
|
||||
WORK +-----------------------------+----------------------------+
|
||||
(using) | | |
|
||||
| REFERENCE | HOW-TO |
|
||||
| "What is the exact | "How do I accomplish Y |
|
||||
| signature of Y?" | using X?" |
|
||||
| | |
|
||||
| describes code | uses code |
|
||||
| | |
|
||||
+-----------------------------+----------------------------+
|
||||
```
|
||||
|
||||
A reader in tutorial mode is learning by doing. They want a guided path with guaranteed success. A reader in how-to mode already knows the basics and wants the recipe for a specific task. A reader in reference mode wants accurate, complete, fact-table coverage of the API. A reader in explanation mode wants to understand a design decision.
|
||||
|
||||
The same person reads a project from each of these modes at different times. The same paragraph cannot serve all four — tutorials need handholding that would slow down a reference reader; reference needs completeness that would overwhelm a tutorial reader.
|
||||
|
||||
## Why this matters as a coverage lens
|
||||
|
||||
A coverage map written in Diataxis terms gives you a deterministic answer to "did docs get updated?" — not "is there a README" but "is there a tutorial for this new skill, a how-to for the common task, a reference for the API, and an explanation for the non-obvious design choice?"
|
||||
|
||||
`/document-release` Step 1.5 walks the diff, extracts new public surface (skills, CLI flags, config options, API endpoints), and scores each entity across the four quadrants. Items with zero coverage become **critical gaps**. Items with only reference coverage (the most common failure mode in gstack's own history) become **common gaps**. Both land in the PR body where reviewers see them.
|
||||
|
||||
`/document-generate` writes docs in the four quadrants intentionally. It refuses to mix them: a tutorial does not get a "Configuration" section, a reference doc does not get a "What you'll build" paragraph. The skill's 9 steps go reference → explanation → how-to → tutorial because that ordering matches the dependency: reference fixes the vocabulary, explanation justifies the design, how-tos build on both, tutorials are the last and hardest.
|
||||
|
||||
## Trade-offs
|
||||
|
||||
**Diataxis adds vocabulary that readers must learn.** A user who's never heard of "reference vs explanation" might find the labels strange at first. The mitigation is that Diataxis labels are self-explanatory once you've seen them once, and the labels never appear in the docs themselves — they appear in the coverage map and PR body, where reviewers see them, not end users.
|
||||
|
||||
**Four files instead of one.** A small skill might have one `docs/SKILL.md` file that mixes all four modes. Diataxis splits that into four. The mitigation: AI generation makes the four-file structure cheap, the cross-linking between quadrants is mechanical (every reference doc links to its how-to, every how-to links to its reference, etc.), and the gains in audit-ability are substantial — `/document-release` can score coverage automatically.
|
||||
|
||||
**Diataxis is not the only good framework.** "Every page is page one" (Mark Baker), the four kinds of docs in the *Write the Docs* community, the Google developer documentation style guide — all have different cuts. gstack picked Diataxis because it has the strongest external adoption (CPython, Django, NumPy, FastAPI, etc.), which means downstream users have the highest chance of having seen the vocabulary before, and the quadrant labels translate cleanly to coverage-map signals.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**"Just write README sections."** Tried implicitly across gstack's history. Failure mode: tutorials accumulated in README until READMEs were 800+ lines and nobody read them past line 50. Diataxis splits them into dedicated files, each discoverable from README's table of contents.
|
||||
|
||||
**Custom in-house taxonomy.** Tempting because it could be tailored. Rejected because every team would invent their own vocabulary and `/document-release` would lose its cross-project audit power. Diataxis is the lingua franca.
|
||||
|
||||
**Auto-generated reference only.** Tried via tools like JSDoc / TypeDoc / Sphinx for many projects. Reference docs without explanation become impenetrable for newcomers; without tutorials, the API is hard to onboard onto. Reference is necessary but not sufficient.
|
||||
|
||||
**No documentation framework at all, just gut-check.** The status quo for most projects. Fails silently — users walk away rather than file issues, so the feedback loop is broken. Diataxis gives a structured signal even before users complain.
|
||||
|
||||
## Related
|
||||
|
||||
- **Reference for the skill that implements this:** [`document-generate/SKILL.md`](../document-generate/SKILL.md)
|
||||
- **Reference for the audit that uses this taxonomy:** [`document-release/SKILL.md`](../document-release/SKILL.md)
|
||||
- **Tutorial for using `/document-generate`:** [`tutorial-document-generate.md`](./tutorial-document-generate.md)
|
||||
- **How-to: document a shipped feature:** [`howto-document-a-shipped-feature.md`](./howto-document-a-shipped-feature.md)
|
||||
- **Diataxis homepage:** https://diataxis.fr/ — Procida's canonical reference for the framework
|
||||
105
docs/howto-document-a-shipped-feature.md
Normal file
105
docs/howto-document-a-shipped-feature.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# 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 (`./setup` complete; verify with `which gstack` or 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:
|
||||
|
||||
1. The PR body has a `## Documentation` section with a doc-diff preview.
|
||||
2. The `### Documentation Debt` subsection lists zero critical gaps (or only items you knowingly deferred).
|
||||
3. Each generated doc file in `docs/` opens cleanly and cross-links to siblings (reference → how-to → tutorial → explanation).
|
||||
4. 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](./tutorial-document-generate.md)
|
||||
- **Why gstack uses the Diataxis framework:** [explanation-diataxis-in-gstack.md](./explanation-diataxis-in-gstack.md)
|
||||
- **Reference for the audit skill:** [`document-release/SKILL.md`](../document-release/SKILL.md)
|
||||
- **Reference for the generation skill:** [`document-generate/SKILL.md`](../document-generate/SKILL.md)
|
||||
142
docs/tutorial-document-generate.md
Normal file
142
docs/tutorial-document-generate.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Tutorial: generate docs for a feature in 90 seconds
|
||||
|
||||
You'll run `/document-generate` against a project you already have, watch it write tutorial / how-to / reference / explanation docs in the right places, and end with a coverage map you can drop into a PR. By the end, you'll know the four moves: scope, archaeology, partition, write.
|
||||
|
||||
## What you'll need
|
||||
|
||||
- gstack installed (`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`)
|
||||
- Claude Code running in any project that has at least one piece of public surface (a CLI command, an exported function, a config option, a skill, an API endpoint)
|
||||
- About 90 seconds
|
||||
|
||||
You do not need a `docs/` directory in advance — the skill creates one if it's missing. You do not need to know Diataxis terminology — the skill labels the output for you.
|
||||
|
||||
## Step 1: Invoke the skill in any project
|
||||
|
||||
Open Claude Code in the project you want to document. Type:
|
||||
|
||||
```
|
||||
/document-generate
|
||||
```
|
||||
|
||||
You'll see the skill ask one question about output target:
|
||||
|
||||
```
|
||||
A) Write documentation inline in existing files (README, ARCHITECTURE, etc.)
|
||||
B) Create standalone documentation files (e.g., docs/ directory)
|
||||
C) Both — inline summaries in existing files + deep docs in standalone files
|
||||
|
||||
RECOMMENDATION: Choose C because it maximizes both discoverability and depth.
|
||||
```
|
||||
|
||||
Pick C. You'll get a README pointer plus a full set of standalone docs.
|
||||
|
||||
## Step 2: Watch the archaeology run
|
||||
|
||||
The skill goes silent for ~30 seconds while it reads the codebase. This is intentional — the Step 1 "Codebase Archaeology" phase is the most important step in the workflow. The skill is reading:
|
||||
|
||||
- The full repository structure
|
||||
- README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md (the entry points)
|
||||
- The implementation files for whatever you're documenting (full file, not just signatures)
|
||||
- The tests (which reveal edge cases and intended behavior)
|
||||
- Inline comments tagged `// NOTE:`, `// DESIGN:`, `// WHY:`
|
||||
|
||||
When it finishes, you'll see a line like:
|
||||
|
||||
```
|
||||
Researched 47 files, identified 12 public surface items, 8 concepts, and 4 design decisions.
|
||||
```
|
||||
|
||||
That number tells you the skill actually read the code rather than guessing from filenames.
|
||||
|
||||
## Step 3: See the Diataxis partition plan
|
||||
|
||||
The skill prints a partition plan showing which quadrants it'll write for which entity:
|
||||
|
||||
```
|
||||
Documentation plan:
|
||||
[entity] [tutorial] [how-to] [reference] [explanation]
|
||||
WidgetService ✅ new ✅ new ✅ new ✅ new
|
||||
--verbose flag ❌ ✅ new ✅ inline ❌
|
||||
Bayesian scheduler ❌ ❌ ✅ new ✅ new
|
||||
```
|
||||
|
||||
Not every entity needs all four quadrants. CLI flags get reference + how-to. Internal modules get reference + explanation. User-facing features get all four. The skill picks based on entity type.
|
||||
|
||||
If the plan has more than 5 documents, the skill asks you to confirm before proceeding. Otherwise it goes.
|
||||
|
||||
## Step 4: Read the first doc that lands
|
||||
|
||||
Reference docs land first because they fix the vocabulary. You'll see lines like:
|
||||
|
||||
```
|
||||
GENERATED: docs/reference-widget-service.md
|
||||
```
|
||||
|
||||
Open that file. It has a strict structure: one-paragraph intro, complete API listing with types and defaults, 2-3 runnable examples, and a Related section linking to the how-to and tutorial that will land next.
|
||||
|
||||
This is what reference docs look like in Diataxis: factual, exhaustive, no narrative. If you find yourself wanting to explain *why* an option exists, that belongs in the explanation doc the skill will write next.
|
||||
|
||||
## Step 5: See the explanation, how-to, and tutorial appear
|
||||
|
||||
In quick succession (each ~5-10 seconds), the skill writes the remaining quadrants:
|
||||
|
||||
```
|
||||
GENERATED: docs/explanation-widget-architecture.md
|
||||
GENERATED: docs/howto-create-a-custom-widget.md
|
||||
GENERATED: docs/tutorial-build-your-first-widget.md
|
||||
```
|
||||
|
||||
Open each one. Notice they don't repeat each other:
|
||||
|
||||
- **Explanation** leads with the problem, then the approach, then trade-offs and alternatives considered
|
||||
- **How-to** has prerequisites, numbered steps with exact commands, a verification section, and a troubleshooting section
|
||||
- **Tutorial** gets you to a working result in under 3 steps, ends with "What you built"
|
||||
|
||||
The skill enforces these structures. If a how-to was missing a verification section, the Step 8 Quality Self-Review caught it before commit.
|
||||
|
||||
## Step 6: Check cross-linking
|
||||
|
||||
Every doc links to the others. Reference doc Related section: links to how-to and tutorial. How-to Related section: links to reference. Tutorial "What you built" section: links to reference for deeper exploration.
|
||||
|
||||
Run a grep to verify no broken links:
|
||||
|
||||
```bash
|
||||
grep -rE '\]\([^)]*\.md\)' docs/ | head -10
|
||||
```
|
||||
|
||||
Every linked file should exist. The skill's Step 7 "Cross-Document Linking & Discoverability" checks this before commit.
|
||||
|
||||
## Step 7: See the coverage summary in the PR body
|
||||
|
||||
If you're on a feature branch with an open PR, the skill updates the PR body with a `## Documentation Generated` table:
|
||||
|
||||
```
|
||||
## Documentation Generated
|
||||
|
||||
| File | Quadrant | Description |
|
||||
|------|----------|-------------|
|
||||
| docs/tutorial-build-your-first-widget.md | Tutorial | Walk-through from install to first working widget |
|
||||
| docs/reference-widget-service.md | Reference | Complete widget API with types, defaults, examples |
|
||||
| docs/explanation-widget-architecture.md | Explanation | Why widgets are isolated services |
|
||||
| docs/howto-create-a-custom-widget.md | How-to | Creating and registering custom widgets |
|
||||
```
|
||||
|
||||
A reviewer opening the PR sees the table and knows immediately what kind of coverage shipped.
|
||||
|
||||
## What you built
|
||||
|
||||
You now have four documents that serve four different readers:
|
||||
|
||||
- A newcomer to your project can read `tutorial-*.md` and get something working
|
||||
- An experienced user can read `howto-*.md` to accomplish a specific task
|
||||
- An API caller can read `reference-*.md` for exact signatures
|
||||
- A code reviewer can read `explanation-*.md` to understand the design
|
||||
|
||||
Each one is short enough to maintain. Each one has a single job. The PR body shows which quadrants were covered. If you run `/document-release` later, the Diataxis coverage map will report this entity as fully covered (4/4 quadrants).
|
||||
|
||||
## What to do next
|
||||
|
||||
- **If you have gaps** /document-release flagged but didn't fill: run `/document-generate` again, scoped to those entities specifically.
|
||||
- **If you want to understand why the four quadrants exist:** read [explanation-diataxis-in-gstack.md](./explanation-diataxis-in-gstack.md).
|
||||
- **If you want to document one specific shipped feature** (not the whole project): read [howto-document-a-shipped-feature.md](./howto-document-a-shipped-feature.md).
|
||||
- **Reference for the skill itself:** [`document-generate/SKILL.md`](../document-generate/SKILL.md).
|
||||
1205
document-generate/SKILL.md
Normal file
1205
document-generate/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
446
document-generate/SKILL.md.tmpl
Normal file
446
document-generate/SKILL.md.tmpl
Normal file
@@ -0,0 +1,446 @@
|
||||
---
|
||||
name: document-generate
|
||||
preamble-tier: 2
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Generate missing documentation from scratch for a feature, module, or entire project.
|
||||
Uses the Diataxis framework (tutorial / how-to / reference / explanation) to produce
|
||||
complete, structured documentation. Can be invoked standalone or called by
|
||||
/document-release when it finds coverage gaps. Use when asked to "write docs",
|
||||
"generate documentation", "document this feature", "create a tutorial", or
|
||||
"explain this module". (gstack)
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- Write
|
||||
- Edit
|
||||
- Grep
|
||||
- Glob
|
||||
- AskUserQuestion
|
||||
triggers:
|
||||
- write docs for this
|
||||
- generate documentation
|
||||
- document this feature
|
||||
- create a tutorial
|
||||
- write a how-to
|
||||
- explain this module
|
||||
- docs for this project
|
||||
---
|
||||
|
||||
{{PREAMBLE}}
|
||||
|
||||
{{BASE_BRANCH_DETECT}}
|
||||
|
||||
# Document Generate: Diataxis Documentation Writer
|
||||
|
||||
You are running the `/document-generate` workflow. Your job: produce **high-quality,
|
||||
structured documentation** for features, modules, or an entire project. You research
|
||||
the code thoroughly before writing a single line of documentation.
|
||||
|
||||
This skill can be invoked two ways:
|
||||
1. **Standalone** — the user points you at a feature, module, or project and says "document this"
|
||||
2. **From /document-release** — the coverage map identified gaps; you fill them
|
||||
|
||||
You follow the **Diataxis framework** — four quadrants of documentation, each serving a
|
||||
different reader need:
|
||||
- **Tutorial** — learning-oriented, walks a newcomer through a working example step-by-step
|
||||
- **How-to** — task-oriented, shows how to accomplish a specific goal (assumes basic familiarity)
|
||||
- **Reference** — information-oriented, complete and accurate technical description
|
||||
- **Explanation** — understanding-oriented, explains why things work the way they do
|
||||
|
||||
**Philosophy: research the whole, then write the parts.** Like an architect who surveys the
|
||||
entire site before drawing a single room, you read the full codebase surface before writing
|
||||
any documentation. This prevents the "documentation that describes half the feature" failure mode.
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Scope & Intent
|
||||
|
||||
1. Determine what to document:
|
||||
- **If invoked with a specific target** (feature, module, file, skill): scope is that target
|
||||
- **If invoked for an entire project**: scope is the full project
|
||||
- **If called from /document-release with gaps**: scope is the specific entities from the coverage map
|
||||
|
||||
2. Use AskUserQuestion to confirm scope and ask about documentation target:
|
||||
|
||||
- A) Write documentation inline in existing files (README, ARCHITECTURE, etc.)
|
||||
- B) Create standalone documentation files (e.g., `docs/` directory)
|
||||
- C) Both — inline summaries in existing files + deep docs in standalone files
|
||||
|
||||
RECOMMENDATION: Choose C because it maximizes both discoverability and depth.
|
||||
|
||||
3. Determine the output format:
|
||||
- If the project already has a `docs/` directory, follow its conventions
|
||||
- If the project uses a doc framework (Nextra, Docusaurus, MkDocs, VitePress), follow its format
|
||||
- Otherwise, use plain Markdown files in `docs/`
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Codebase Archaeology (Research Phase)
|
||||
|
||||
**This is the most important step.** Do not skip or rush it. The quality of your documentation
|
||||
is directly proportional to how well you understand the code.
|
||||
|
||||
1. **Map the project structure:**
|
||||
|
||||
```bash
|
||||
find . -type f -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.gstack/*" -not -path "./dist/*" -not -path "./build/*" -not -path "./.next/*" | head -200
|
||||
```
|
||||
|
||||
2. **Read the entry points.** Identify and read:
|
||||
- README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md / AGENTS.md
|
||||
- package.json / Cargo.toml / pyproject.toml / go.mod (understand the project type)
|
||||
- Main entry files (index.ts, main.rs, app.py, cmd/main.go)
|
||||
- Configuration files and examples
|
||||
|
||||
3. **Read the source code for each target entity.** For each feature/module you're documenting:
|
||||
- Read the implementation files end-to-end (not just signatures)
|
||||
- Read the tests — they reveal intended behavior, edge cases, and usage patterns
|
||||
- Read related modules that the target depends on or is depended upon by
|
||||
- Read any existing inline comments, especially `// NOTE:`, `// DESIGN:`, `// WHY:`
|
||||
|
||||
4. **Build a concept map.** Before writing, produce an internal outline:
|
||||
|
||||
```
|
||||
Target: [feature/module name]
|
||||
Purpose: [one sentence — what problem does it solve?]
|
||||
Key concepts: [list the 3-5 concepts a reader must understand]
|
||||
Public surface: [commands, functions, config options, API endpoints]
|
||||
Dependencies: [what it needs from other modules]
|
||||
Dependents: [what relies on it]
|
||||
Edge cases: [from reading tests and code]
|
||||
Design decisions: [any non-obvious "why" choices]
|
||||
```
|
||||
|
||||
5. Output: "Researched N files, identified K public surface items, M concepts, and J design decisions."
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Diataxis Partitioning
|
||||
|
||||
For each target entity, decide which Diataxis quadrants to produce. Not every entity needs all four.
|
||||
|
||||
**Decision matrix:**
|
||||
|
||||
| Entity type | Tutorial? | How-to? | Reference? | Explanation? |
|
||||
|---|---|---|---|---|
|
||||
| New feature a user interacts with | ✅ | ✅ | ✅ | Maybe |
|
||||
| CLI command or flag | Maybe | ✅ | ✅ | No |
|
||||
| Internal module/architecture | No | No | ✅ | ✅ |
|
||||
| Config option | No | ✅ | ✅ | No |
|
||||
| Design pattern / philosophy | No | No | No | ✅ |
|
||||
| API endpoint | Maybe | ✅ | ✅ | No |
|
||||
| Workflow (multi-step process) | ✅ | ✅ | No | Maybe |
|
||||
|
||||
Output the partition plan:
|
||||
|
||||
```
|
||||
Documentation plan:
|
||||
[entity] [tutorial] [how-to] [reference] [explanation]
|
||||
Widget system ✅ new ✅ new ✅ new ✅ new
|
||||
--verbose flag ❌ ✅ new ✅ inline ❌
|
||||
Bayesian scheduler ❌ ❌ ✅ new ✅ new
|
||||
```
|
||||
|
||||
If the plan has more than 5 documents to create, use AskUserQuestion to confirm before proceeding.
|
||||
For smaller scopes, proceed directly.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Write Reference Documentation First
|
||||
|
||||
Reference docs are the foundation. They are factual, complete, and derived directly from code.
|
||||
Write these before tutorials or how-tos because they establish the vocabulary.
|
||||
|
||||
**Reference doc template:**
|
||||
|
||||
```markdown
|
||||
# [Entity Name]
|
||||
|
||||
[One paragraph: what it is, what it does, when you'd use it.]
|
||||
|
||||
## API / Interface
|
||||
|
||||
[Complete listing of public surface: functions, commands, config options, parameters.
|
||||
Include types, defaults, and constraints. Pull directly from code — do not paraphrase
|
||||
loosely.]
|
||||
|
||||
## Options / Configuration
|
||||
|
||||
[If applicable: every option with its type, default, and effect.]
|
||||
|
||||
## Examples
|
||||
|
||||
[2-3 concrete examples showing actual usage. Prefer real command output or code that
|
||||
would actually compile/run.]
|
||||
|
||||
## Related
|
||||
|
||||
[Links to other reference docs, how-tos, or explanations that provide context.]
|
||||
```
|
||||
|
||||
**Rules for reference docs:**
|
||||
- Accuracy over elegance. Every claim must be traceable to code.
|
||||
- Include types, defaults, and constraints. "Accepts a string" is insufficient — "Accepts a
|
||||
string (max 256 chars, must match `^[a-z-]+$`)" is reference-grade.
|
||||
- Show real examples that would actually work if copy-pasted.
|
||||
- Do not explain *why* — that belongs in explanation docs.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Write Explanation Documentation
|
||||
|
||||
Explanation docs answer "why does this work this way?" They are the design rationale.
|
||||
|
||||
**Explanation doc template:**
|
||||
|
||||
```markdown
|
||||
# [Concept / Design Decision]
|
||||
|
||||
[Opening paragraph: the problem this design solves, stated in terms a smart reader
|
||||
who hasn't seen the code would understand.]
|
||||
|
||||
## The problem
|
||||
|
||||
[Concrete description of what goes wrong without this design. Real failure modes,
|
||||
not abstract risks.]
|
||||
|
||||
## The approach
|
||||
|
||||
[How the design solves the problem. Include diagrams (ASCII or Mermaid) for
|
||||
architectural concepts.]
|
||||
|
||||
## Trade-offs
|
||||
|
||||
[What was given up. Every design decision trades something — name it explicitly.]
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
[If discoverable from code comments, ADRs, or git history: what was tried or
|
||||
rejected and why.]
|
||||
```
|
||||
|
||||
**Rules for explanation docs:**
|
||||
- Lead with the problem, not the solution.
|
||||
- Use ASCII diagrams for architecture. They're grep-able, diff-friendly, and render everywhere.
|
||||
- Name trade-offs explicitly. "We chose X over Y because Z" is the gold standard.
|
||||
- Do not repeat reference material — link to it.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Write How-To Guides
|
||||
|
||||
How-tos are task-oriented. They assume the reader knows the basics and wants to accomplish
|
||||
something specific.
|
||||
|
||||
**How-to doc template:**
|
||||
|
||||
```markdown
|
||||
# How to [accomplish specific task]
|
||||
|
||||
[One sentence: what you'll accomplish and the end result.]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
[What the reader needs before starting. Be specific — versions, installed tools,
|
||||
config state.]
|
||||
|
||||
## Steps
|
||||
|
||||
1. [Action verb] [specific instruction]
|
||||
|
||||
```bash
|
||||
[exact command]
|
||||
```
|
||||
|
||||
[Expected output or result, if non-obvious.]
|
||||
|
||||
2. [Next step...]
|
||||
|
||||
## Verification
|
||||
|
||||
[How to confirm it worked. A command, a URL to visit, a test to run.]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
[Common failure modes and their fixes. Pull from tests and error handling code.]
|
||||
```
|
||||
|
||||
**Rules for how-to docs:**
|
||||
- Title starts with "How to" — no exceptions. This is the reader's entry point.
|
||||
- Every step must be actionable. No "consider whether..." — instead "Run X" or "Add Y to Z".
|
||||
- Include verification. The reader should never wonder "did it work?"
|
||||
- Troubleshooting section is mandatory if the task can fail.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Write Tutorials
|
||||
|
||||
Tutorials are learning-oriented. They take a newcomer from zero to a working example.
|
||||
These are the hardest to write well and the most valuable.
|
||||
|
||||
**Tutorial doc template:**
|
||||
|
||||
```markdown
|
||||
# [Tutorial title — describes what you'll build/learn]
|
||||
|
||||
[Opening paragraph: what you'll build, why it's useful, and what you'll understand
|
||||
by the end. Keep it concrete — "You'll build a working X that does Y" not
|
||||
"This tutorial covers X".]
|
||||
|
||||
## What you'll need
|
||||
|
||||
[Prerequisites: tools, versions, prior knowledge. Link to installation guides.]
|
||||
|
||||
## Step 1: [Set up the foundation]
|
||||
|
||||
[Start from a clean state. Show every command. Explain what each does on first
|
||||
encounter — but briefly, not a lecture.]
|
||||
|
||||
```bash
|
||||
[exact command]
|
||||
```
|
||||
|
||||
[Brief explanation of what just happened.]
|
||||
|
||||
## Step 2: [Build the first working piece]
|
||||
|
||||
[Get to a working, visible result as fast as possible. The reader should see
|
||||
something happen within the first 3 steps.]
|
||||
|
||||
...
|
||||
|
||||
## Step N: [Final step]
|
||||
|
||||
## What you built
|
||||
|
||||
[Recap: what the reader now has and what it can do. Link to reference docs
|
||||
for deeper exploration. Suggest next steps.]
|
||||
```
|
||||
|
||||
**Rules for tutorials:**
|
||||
- **Time to first result < 3 steps.** If the reader hasn't seen something work by step 3,
|
||||
the tutorial is too slow.
|
||||
- Every step must produce a visible change or output. No "now configure X" without showing
|
||||
what changes.
|
||||
- Use the exact commands the reader will type. No "run the appropriate command" abstractions.
|
||||
- Error paths: if a step commonly fails, show the error and the fix inline.
|
||||
- End with "What you built" — connect the tutorial back to the real use case.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Cross-Document Linking & Discoverability
|
||||
|
||||
After writing all documents:
|
||||
|
||||
1. **Add cross-links between quadrants.** Every reference doc should link to its how-to.
|
||||
Every how-to should link to its reference. Tutorials should link to both.
|
||||
|
||||
2. **Update entry-point files.** Add references to new docs in:
|
||||
- README.md — add to documentation section or table of contents
|
||||
- CLAUDE.md / AGENTS.md — add to project structure if relevant
|
||||
- Any existing docs index or sidebar config
|
||||
|
||||
3. **Verify discoverability.** Every new document must be reachable within 2 clicks from
|
||||
README.md. If a docs framework is in use, add to the sidebar/nav config.
|
||||
|
||||
4. **Check for broken links.** Grep for any `](` references that point to files that don't exist.
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Quality Self-Review
|
||||
|
||||
Before committing, review each document against these criteria:
|
||||
|
||||
**Accuracy gate:**
|
||||
- [ ] Every code example compiles / runs / passes if copy-pasted
|
||||
- [ ] Every API description matches the actual code signature
|
||||
- [ ] Every command shown produces the output described
|
||||
- [ ] No stale references to renamed/removed entities
|
||||
|
||||
**Completeness gate:**
|
||||
- [ ] Reference docs cover 100% of public surface
|
||||
- [ ] How-tos cover the top 3 tasks a user would attempt
|
||||
- [ ] Tutorials get to a working result in ≤3 steps
|
||||
- [ ] Explanation docs name trade-offs, not just choices
|
||||
|
||||
**Voice gate:**
|
||||
- [ ] Written for a smart person who hasn't seen the code
|
||||
- [ ] No jargon without brief inline gloss on first use
|
||||
- [ ] Active voice, concrete nouns, short sentences
|
||||
- [ ] "You can now..." not "The system provides..."
|
||||
|
||||
Fix any failures before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Commit & Output
|
||||
|
||||
1. Stage new documentation files by name (never `git add -A` or `git add .`).
|
||||
|
||||
2. Create a commit:
|
||||
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
docs: generate [scope] documentation (Diataxis)
|
||||
|
||||
[One-line summary of what was documented]
|
||||
|
||||
Quadrants: [list which quadrants were produced]
|
||||
|
||||
{{CO_AUTHOR_TRAILER}}
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
3. Push to the current branch:
|
||||
|
||||
```bash
|
||||
git push
|
||||
```
|
||||
|
||||
4. **If a PR exists**, update the PR body with a `## Documentation Generated` section listing
|
||||
every new file with its Diataxis quadrant and a one-line description:
|
||||
|
||||
```
|
||||
## Documentation Generated
|
||||
|
||||
| File | Quadrant | Description |
|
||||
|------|----------|-------------|
|
||||
| docs/tutorial-getting-started.md | Tutorial | Walk-through from install to first working example |
|
||||
| docs/reference-widget-api.md | Reference | Complete widget API with types, defaults, examples |
|
||||
| docs/explanation-bayesian-scheduler.md | Explanation | Why the scheduler uses Bayesian inference |
|
||||
| docs/howto-custom-widgets.md | How-to | Creating and registering custom widgets |
|
||||
```
|
||||
|
||||
5. Output a structured summary:
|
||||
|
||||
```
|
||||
Documentation generated:
|
||||
Scope: [what was documented]
|
||||
Files: [N] new, [M] updated
|
||||
Coverage:
|
||||
Tutorials: [count] ([list])
|
||||
How-tos: [count] ([list])
|
||||
Reference: [count] ([list])
|
||||
Explanation: [count] ([list])
|
||||
Quality: [pass/fail on each gate]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Research before writing.** Step 1 is not optional. Read the code, read the tests, read the
|
||||
existing docs. Insufficient research produces surface-level documentation.
|
||||
- **Accuracy is non-negotiable.** Every code example must work. Every API description must match
|
||||
the actual code. If you're unsure about a detail, read the source again — do not guess.
|
||||
- **Diataxis quadrants serve different readers.** Do not mix tutorial content into reference docs
|
||||
or reference content into how-tos. Each quadrant has a specific reader in a specific mode.
|
||||
- **Time to first result in tutorials.** If a reader can't see something working by step 3,
|
||||
restructure the tutorial.
|
||||
- **Cross-link everything.** Isolated docs are undiscoverable docs.
|
||||
- **Voice: friendly, concrete, user-forward.** Write like you're explaining to a smart person
|
||||
who hasn't seen the code. Never corporate, never academic.
|
||||
- **Completeness over minimalism.** AI makes comprehensive documentation cheap. Don't write
|
||||
"minimal viable docs" — write complete docs. Boil the lake.
|
||||
@@ -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.
|
||||
|
||||
@@ -26,6 +26,7 @@ Conventions:
|
||||
- [/design-review](design-review/SKILL.md): Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them.
|
||||
- [/design-shotgun](design-shotgun/SKILL.md): Design shotgun: generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate.
|
||||
- [/devex-review](devex-review/SKILL.md): Live developer experience audit.
|
||||
- [/document-generate](document-generate/SKILL.md): Generate missing documentation from scratch for a feature, module, or entire project.
|
||||
- [/document-release](document-release/SKILL.md): Post-ship documentation update.
|
||||
- [/freeze](freeze/SKILL.md): Restrict file edits to a specific directory for the session.
|
||||
- [/gstack](gstack/SKILL.md): Fast headless browser for QA testing and site dogfooding.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "gstack",
|
||||
"version": "1.34.2.0",
|
||||
"version": "1.35.0.0",
|
||||
"description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
|
||||
"license": "MIT",
|
||||
"type": "module",
|
||||
|
||||
Reference in New Issue
Block a user