<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run gen:skill-docs -->

Step 0: Detect platform and base branch

First, detect the git hosting platform from the remote URL:

git remote get-url origin 2>/dev/null

• If the URL contains "github.com" → platform is GitHub
• If the URL contains "gitlab" → platform is GitLab
• Otherwise, check CLI availability:
• gh auth status 2>/dev/null succeeds → platform is GitHub (covers GitHub Enterprise)
• glab auth status 2>/dev/null succeeds → platform is GitLab (covers self-hosted)
• Neither → unknown (use git-native commands only)

Determine which branch this PR/MR targets, or the repo's default branch if no PR/MR exists. Use the result as "the base branch" in all subsequent steps.

If GitHub:

1. gh pr view --json baseRefName -q .baseRefName — if succeeds, use it
2. gh repo view --json defaultBranchRef -q .defaultBranchRef.name — if succeeds, use it

If GitLab:

1. glab mr view -F json 2>/dev/null and extract the target_branch field — if succeeds, use it
2. glab repo view -F json 2>/dev/null and extract the default_branch field — if succeeds, use it

Git-native fallback (if unknown platform, or CLI commands fail):

1. git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'
2. If that fails: git rev-parse --verify origin/main 2>/dev/null → use main
3. If that fails: git rev-parse --verify origin/master 2>/dev/null → use master

If all fail, fall back to main.

Print the detected base branch name. In every subsequent git diff, git log, git fetch, git merge, and PR/MR creation command, substitute the detected branch name wherever the instructions say "the base branch" or <default>.

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:
2. If invoked with a specific target (feature, module, file, skill): scope is that target
3. If invoked for an entire project: scope is the full project
4. If called from /document-release with gaps: scope is the specific entities from the coverage map

1. 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.

1. Determine the output format:
2. If the project already has a docs/ directory, follow its conventions
3. If the project uses a doc framework (Nextra, Docusaurus, MkDocs, VitePress), follow its format
4. Otherwise, use plain Markdown files in docs/

Step 1: Codebase Archaeology (Research Phase)

The quality of the documentation depends on how well you understand the code, so this step carries the most weight.

1. Map the project structure:

find . -type f -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.gstack/*" -not -path "./dist/*" -not -path "./build/*" -not -path "./.next/*" | head -200

1. Read the entry points. Identify and read:
2. README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md / AGENTS.md
3. package.json / Cargo.toml / pyproject.toml / go.mod (understand the project type)
4. Main entry files (index.ts, main.rs, app.py, cmd/main.go)
5. Configuration files and examples

1. Read the source code for each target entity. For each feature/module you're documenting:
2. Read the implementation files end-to-end (not just signatures)
3. Read the tests — they reveal intended behavior, edge cases, and usage patterns
4. Read related modules that the target depends on or is depended upon by
5. Read any existing inline comments, especially // NOTE:, // DESIGN:, // WHY:

1. 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]

1. 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:

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:

# [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:

# [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:

# 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:

# [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.]

[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.

1. Update entry-point files. Add references to new docs in:
2. README.md — add to documentation section or table of contents
3. CLAUDE.md / AGENTS.md — add to project structure if relevant
4. Any existing docs index or sidebar config

1. 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.

1. 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 .).

Redaction scan before commit. Generated docs frequently contain example credentials; scan the staged doc content and block on a HIGH credential (a live-format secret in committed docs is a leak). The per-span placeholder filter passes obvious docs examples (e.g. AKIAIOSFODNN7EXAMPLE); a live-format secret blocks wherever it appears, fenced or not:

REDACT_VIS=$(~/.claude/skills/gstack/bin/gstack-config get redact_repo_visibility 2>/dev/null)
[ -z "$REDACT_VIS" ] && REDACT_VIS=$(gh repo view --json visibility -q .visibility 2>/dev/null | tr 'A-Z' 'a-z')
git diff --cached --no-color | grep '^+' | sed 's/^+//' | \
  ~/.claude/skills/gstack/bin/gstack-redact --repo-visibility "${REDACT_VIS:-unknown}" --json
# exit 3 (HIGH) → unstage the offending doc, remove the secret, re-stage. Do NOT commit.

1. Create a commit:

git commit -m "$(cat <<'EOF'
docs: generate [scope] documentation (Diataxis)

[One-line summary of what was documented]

Quadrants: [list which quadrants were produced]

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

1. Push to the current branch:

git push

1. 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 |

1. 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 ocean.