v1.35.0.0 feat: add /document-generate skill + enhance /document-release with Diataxis coverage map

[garrytan]

Moved from #1427 (garrytan-agents fork) so eval CI can access base-repo secrets.

What

Inspired by @doodlestein's documentation-website skill and the FrankenTUI docs site it produced. Two changes:

1. New /document-generate skill — writes missing documentation from scratch using the Diataxis framework
2. Enhanced /document-release — now audits documentation coverage gaps and suggests /document-generate as follow-up

These two skills compose like Unix pipes: /document-release finds what's missing, /document-generate fills the gaps.

---

New: /document-generate

Writes high-quality documentation from scratch for a feature, module, or entire project. Uses the Diataxis framework (tutorial / how-to / reference / explanation).

9-step workflow:
0. Scope and Intent — confirm target, output format, where docs go

1. Codebase Archaeology — deep research phase, reads code + tests + comments before writing anything
2. Diataxis Partitioning — decide which quadrants each entity needs (decision matrix included)
3. Write Reference — factual, complete, code-derived (foundation layer, written first)
4. Write Explanation — design rationale, trade-offs, "why" docs with ASCII diagrams
5. Write How-Tos — task-oriented guides with prerequisites, steps, verification, troubleshooting
6. Write Tutorials — learning-oriented, hard rule: working result within 3 steps
7. Cross-Document Linking — ensure discoverability from README within 2 clicks
8. Quality Self-Review — accuracy, completeness, and voice gates
9. Commit and Output — structured summary with quadrant breakdown

Key design principles stolen from @doodlestein:

• Research-first, write-second (the "Partition" phase maps everything before drafting)
• Reference docs written first (establish vocabulary for other quadrants)
• Composable with other skills (can be called standalone or from /document-release)
• Ambitious scope as a feature ("boil the lake" — write complete docs, not minimal)

---

Enhanced: /document-release

Step 1.5: Coverage Map (Blast-Radius Analysis)

New step between Pre-flight and Per-File Audit. Scans the diff for new public surface and assesses documentation coverage across Diataxis quadrants. Flags gaps but never auto-generates — suggests /document-generate when significant gaps are found.

Architecture Diagram Drift Detection

Parses entity names from ASCII/Mermaid diagrams, cross-references against the diff. Flags stale diagrams.

Enhanced CHANGELOG Sell Test

0-3 Diataxis rubric: +1 for "what changed" (reference), +1 for "why care" (explanation), +1 for "how to use it" (how-to). Entries scoring less than 2 get rewritten.

Documentation Debt in PR Body

Step 9 now appends a ### Documentation Debt section with critical gaps, common gaps, and stale diagrams.

---

Files Changed

• document-generate/SKILL.md.tmpl — NEW template for /document-generate
• document-generate/SKILL.md — generated output
• document-release/SKILL.md.tmpl — enhanced template
• document-release/SKILL.md — regenerated output

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

Documentation

• README.md — added /document-generate row to skills table (Technical Writer category); updated install-command skill lists in both Claude Code and Codex/AGENTS sections
• SKILL.md.tmpl + SKILL.md — added routing line: "User asks to write docs from scratch, generate documentation, document this feature/module → invoke /document-generate"
• CLAUDE.md — added document-generate/ to project structure tree; added new "Checking out PRs from garrytan-agents" section documenting the fork-PR secret-access workflow
• gstack/llms.txt — auto-regenerated to include /document-generate entry
• VERSION — 1.34.0.0 → 1.35.0.0 (MINOR: new skill + substantial enhancement)

Documentation Debt

The following are flagged for follow-up (not blocking this PR):

• Tutorial coverage for /document-generate — no getting-started walkthrough in README beyond the skills-table row. Diataxis quadrant: tutorial. Would help first-time users learn-by-doing rather than reading the skill template cold. Consider: a short "First doc generation in 90 seconds" section in README.
• Explanation coverage for Diataxis adoption — no ARCHITECTURE.md entry on why gstack uses Diataxis as its doc-quadrant lens (Procida origin, why this vs. just-write-markdown). Diataxis quadrant: explanation. Low priority; explanation is in the skill prose itself.
• CHANGELOG entry — this branch has no CHANGELOG entry yet. Will be added by /ship when the PR is ready to land (one entry under ## [1.35.0.0] covering both the new skill and the doc-release enhancements).

docs-debt label recommended on this PR.

[github-actions]

E2E Evals: ✅ PASS

3/3 tests passed | $.33 total cost | 12 parallel runners

Suite	Result	Status	Cost
e2e-workflow	1/1	✅	$0.29
llm-judge	1/1	✅	$0.02
llm-judge	1/1	✅	$0.02

---

12x ubicloud-standard-2 (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite