v1.35.0.0 feat: add /document-generate skill + enhance /document-release with Diataxis coverage map#1477
Merged
Merged
Conversation
…ction, 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>
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>
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>
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>
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>
E2E Evals: ✅ PASS12/12 tests passed | $.76 total cost | 12 parallel runners
12x ubicloud-standard-2 (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite |
- 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>
garrytan
changed the title
…-diataxis # Conflicts: # VERSION
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>
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation pipeline becomes a tracked surface. Ships a new
/document-generateskill (Diataxis-based doc author) and substantially enhances/document-releasewith coverage maps, doc-debt PR sections, and architecture diagram drift detection.Headline shipping items:
/document-generate(NEW) — 446-line skill template, 9-step workflow. Reads codebase first, then writes docs in 4 Diataxis quadrants (tutorial / how-to / reference / explanation). Runnable standalone or auto-chained from/document-releasewhen coverage gaps surface./document-releaseenhancements — new Step 1.5 Coverage Map (scores every new public-surface entity across the 4 quadrants), Documentation Debt section in PR body (critical + common gaps with Diataxis tags), Architecture diagram drift detection (scans ASCII/Mermaid blocks for renamed entities), CHANGELOG sell-test rubric (0-3 scoring).garrytan-agentsPRs: push to base repo so eval CI gets secrets, instead of broadening fork secret access.Test Coverage
bun testacross browse/test, test/, make-pdf/test — all passed. Security ensemble bench: Detection 56.2% (above 55% floor), FP 22.9% (below 25% ceiling). No new code paths introduced (diff is markdown + skill templates), so no new unit/integration tests required.Pre-Landing Review
Codex review ran during plan-mode session — 17 findings on the original cathedral plan, all addressed via two-phase rollout + inline mitigations (see plan file
/Users/garrytan/.claude/plans/what-can-we-do-idempotent-flurry.md). Adversarial Claude subagent: no new issues on the final diff.Eval Results
Paid evals (
bun run test:evals) skipped for this ship — diff is documentation + skill-routing changes, not LLM-output-changing logic. Run manually if you want extra confidence:EVALS=1 bun run test:evals.Plan Completion
Two-phase plan codified in
~/.gstack/projects/garrytan-gstack/ceo-plans/2026-05-11-document-generate-and-release-platform.md. Phase 1 (this PR) ships the/document-generateskill +/document-releaseenhancements + CLAUDE.md fork-PR workflow. Phase 2 (follow-up PR after dogfooding) ships the sharedgstack-doc-coverageCLI primitive, tutorial sandbox validation, /ship doc-debt gate, and delight pack — see plan file for gate-activation criteria (≥10 PRs of observer-mode data + <10% false-positive rate).Documentation
document-generate/to project structure tree; added new "Checking out PRs from garrytan-agents" section/document-generateentryDocumentation Debt
Two follow-up items flagged for future work, not blocking:
Test plan
bun test)v1.35.0.0/document-generateon a sample project to dogfood the four-quadrant flow/document-releaseStep 1.5 coverage map renders correctly in a real PR body🤖 Generated with Claude Code
Documentation Generated
Filled the documentation debt items flagged by
/document-releaseearlier in this PR. Closes both gaps surfaced in the previous### Documentation Debtsection.docs/tutorial-document-generate.mddocs/howto-document-a-shipped-feature.md/document-releaseaudit → fill gaps with/document-generate→ verifydocs/explanation-diataxis-in-gstack.mddocument-generate/SKILL.md.tmpl)All four Diataxis quadrants for
/document-generateare now covered. Cross-linking verified — every Related section points at an existing file. README skills-table row now links the tutorial, how-to, and explanation directly.