Document Generate

When to invoke

Use when asked to "write docs", "generate documentation", "document this feature", "create a tutorial", or "explain this module".

Preamble

eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)" 2>/dev/null || SLUG="unknown"
_LEARN_FILE="${VIBESTACK_HOME:-$HOME/.vibestack}/projects/${SLUG:-unknown}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
  _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
  echo "LEARNINGS: $_LEARN_COUNT entries loaded"
  if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
    ~/.vibestack/bin/vibe-learnings-search --limit 5 2>/dev/null || true
  fi
else
  echo "LEARNINGS: none yet"
fi

{{include lib/snippets/session-host.md}}

{{include lib/snippets/decision-brief.md}}

{{include lib/snippets/working-protocols.md}}

{{include lib/snippets/state-protocols.md}}

Step 0: Detect base branch

Determine which branch this work targets, or the repo's default branch. Probes GitHub (gh) and GitLab (glab) before the git-native fallback, so the base is correct on either host:

BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null)
[ -z "$BASE" ] && BASE=$(glab mr view -F json 2>/dev/null \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('target_branch',''))" 2>/dev/null)
[ -z "$BASE" ] && BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
[ -z "$BASE" ] && git rev-parse --verify origin/main >/dev/null 2>&1 && BASE=main
[ -z "$BASE" ] && git rev-parse --verify origin/master >/dev/null 2>&1 && BASE=master
[ -z "$BASE" ] && BASE=main
echo "Base branch: $BASE"

Use $BASE in subsequent git diff / git log commands.

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 0a: 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:

find . -type f -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.vibestack/*" -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:

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

```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

**Secret scan before commit.** Doc generators routinely emit example credentials that look real. Before staging, scan every generated/updated documentation file for high-confidence secrets. On a match, **stop**: name the file and matched pattern, and tell the user to redact (and rotate if the secret is real) before re-running. Do not commit.

{{include lib/snippets/secret-scan-patterns.md}}

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-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
EOF
)"

3. Push to the current branch:

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]

Claimed Limitations Need Evidence

A claimed limitation is a material claim, not a caveat — "the CLI can't do that", "that needs a credential", "the platform makes this impossible". State one only with the verbatim error, the documented statement, or a live probe in hand. Where a cheap probe would settle it — run the command, read the file, grep the flag — run it before the claim goes in. This cuts both ways here: a fabricated limit written into a how-to or a troubleshooting section is published as fact and readers build workarounds around it, and a fabricated limit about your own tooling stops the workflow early. When you genuinely cannot verify, say what you don't know and what would settle it instead of asserting the limit.

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.

Capture Learnings

Before finishing, review the session for durable learnings and log each one. This step always runs — it is not conditional on something having felt noteworthy, because a run that waits to be impressed logs nothing. What belongs here: a non-obvious documentation pattern, a Diataxis pitfall, a source-of-truth quirk (which file the project actually treats as authoritative for a fact).

~/.vibestack/bin/vibe-learnings-log '{"skill":"document-generate","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'

Types: pattern (reusable approach), pitfall (what NOT to do), preference (user stated), architecture (structural decision).

Only log genuine discoveries. A good test: would this insight save time in a future session?

If the review surfaces none, say "No durable learnings this session" in your completion summary. An empty result is a result; a silently skipped step is indistinguishable from a run that found nothing.