mirror of
https://github.com/garrytan/gstack.git
synced 2026-10-02 01:20:19 +02:00
Garry Tan
dcaea52800
* feat: add surface-aware exploratory QA and ship documentation gates * test: preserve delegated QA setup authority after main integration * fix(qa): clarify exploration order and preserve report artifacts * test(qa): follow the shared setup reference directly * refactor(ship): make verification and recovery routes explicit * test(ship): align evidence and review guards with explicit routes * fix(workflows): clarify ship recovery and functional QA evidence * fix(workflows): clarify approval recovery and full QA coverage * refactor(workflows): order review transactions and clarify ship state * fix(ship): clarify final verification and fail closed at publication * fix(evals): attribute native atomic documentation writes * fix(ship): clarify recovery and documentation lifecycle guidance * fix(test): preserve observed native placeholder styling in CI * fix(codex): report watchdog timeouts without a process-exit race * Checkpoint functional QA implementation and workflow validation repairs * Fix documentation and shared-review fixture contracts * docs: clarify judge reuse and evaluation supervision * test: align review evidence and selected case contracts * test: verify append-only documentation checkpoints and recovery * fix: qualify QA workflows and CI validation repairs * fix: launch shared-libs fixture scripts on Windows * fix: qualify QA deadlines, fixture isolation, and shard cleanup * fix: preserve qualified QA and cancellation repairs * fix: enforce functional fixture authority and share strict event decoding * fix: retain free-test evidence and explain recovery * fix: reject malformed native evidence after decoder consolidation * test: use reliable capture for telemetry privacy filters * test: refresh measured quick coverage and document validation costs * Fix native fixture receipts and preserve VM validation evidence * Align negative judge controls with upstream clarity policy * Fix report-only QA preparation and public evidence handling * Clarify QA-only preparation and current-report preservation * Stream Ship quality judgments with an explicit 64k response contract * Validate compact judge reasoning locally with supported wire schema * Align functional QA fixture instructions with evidence acceptance * Bind native browser diagnostics to execution evidence and align review verdicts * Preserve native diagnostic line boundaries * Serialize functional QA evidence from native captures * Keep large QA evidence fixture payload out of Windows argv
143 lines
6.7 KiB
Markdown
143 lines
6.7 KiB
Markdown
# 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 feature before shipping** (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).
|