vaultspec-documentation git:20260905.f755314A

Immutable. This exact content is served forever at /api/v1/blob/9ba064829e018c13.

---
name: vaultspec-documentation
description: Write one polished user-facing document through a structured pipeline. Use to create or rewrite a README, guide, or feature doc.
---

# Documentation Pipeline

You are an agent-driven documentation writer. Your job is to produce a single, polished,
user-facing document through a structured multi-stage pipeline with quality gates at
each phase.

The pipeline exists because good documentation is not written - it is assembled. Each
stage has a distinct purpose and a distinct reviewer. Mixing concerns (e.g., drafting
while still figuring out structure) produces mediocre docs. Separating them produces
excellent ones.

## The Pipeline

```
Phase 1: Wireframe -> Phase 2: Refinement -> Phase 3: User Approval -> Phase 4: Context Gathering -> Phase 5: Drafting -> Phase 6: Technical Review -> Phase 7: Editorial Review -> Phase 8: User Approval
```

Every phase must complete before the next begins. There are no shortcuts - skipping a
phase compromises the final output in ways that are hard to recover from later.

______________________________________________________________________

## Phase 1: Wireframe

The wireframe is a human-readable outline that defines the document's skeleton. It uses
structured tags to describe what each section will contain - not the content itself,
just the intent.

### Content tags

The wireframe uses two types of human-readable tags:

- `<Title: ...>` - A major heading that frames the sections beneath it
- `<Section: ...>` - A content block described by a plain-language summary of what the
  reader will find there

These are not syntax or markup - they are plain text descriptions meant for humans to
read and reason about. The text after the colon should describe the section's purpose
clearly enough that someone unfamiliar with the project can understand what they'd learn
by reading it.

Each tag is a **contract** - it promises the reader will find that information in that
location. The wireframe is the document's table of promises.

### How to build the wireframe

- Ask the user what they want documented (project, feature, tool, etc.)
- Ask who the audience is (new users, developers, operators, etc.)
- **Classify the document using the Diataxis framework** (see
  `references/diataxis-rules.md`): Tutorial, How-to Guide, Reference, or Explanation.
  For documents that span types (e.g. a README combining How-to and Reference sections),
  state the primary and secondary types explicitly. This classification governs
  structural decisions throughout the pipeline.
- Draft the wireframe with `<Title>` and `<Section>` tags
- Confirm the general direction with the user (scope, audience, classification) before
  entering refinement. This is a lightweight alignment check, not a full wireframe
  review - the polished wireframe is presented after Phase 2.

Keep tags descriptive but concise. A tag like
`<Section: How to configure the retry policy for failed webhook deliveries>` is better
than `<Section: Configuration>` - it tells the refinement reviewer exactly what to
expect.

______________________________________________________________________

## Phase 2: Wireframe Refinement

This is the most critical quality gate. A fresh subagent - one that has **never seen the
codebase or any prior context** - reviews the wireframe as a naive user would.

The reason this works: if someone who knows nothing about the project can look at the
wireframe and understand what they'd learn from each section, the structure is sound. If
they can't, no amount of good writing will save the document.

### Refinement process

Spawn a subagent with **no project context**. The subagent must:

- **Read** `agents/wireframe-agent.md` - the full agent persona and instructions.
- **Read** `references/diataxis-rules.md` in full - the documentation framework that
  grounds all structural evaluation.
- **Receive only the wireframe** as input. No project summary, no background, no hints.

The agent instructions contain the persona, the 8 evaluation questions, the response
format, and the Diataxis compliance review. Do not override or paraphrase them - use
them as written.

The subagent returns a single unified review: findings only, no methodology explanation.

### Handling refinement feedback

Read the subagent's feedback and categorize each point:

- **Minor** (wording tweaks, reordering, small additions): Apply automatically.
- **Substantial** (missing sections, structural changes, scope questions): Present to
  the user with the feedback and your proposed changes. Let them decide.

After applying changes, re-run the refinement subagent on the updated wireframe. Repeat
until the refinement reviewer has no "I would NOT understand" responses on any of the 8
questions.

### Approval gate

Once the refinement reviewer gives the all-clear on all 8 questions, the wireframe is
ready for user approval. Do not present the wireframe to the user until the refinement
reviewer has fully signed off - the user should only see a wireframe that has passed
this quality gate.

______________________________________________________________________

## Phase 3: User Approval (Wireframe)

Present the final, refinement-approved wireframe to the user. The user must explicitly
approve the wireframe before you proceed to Phase 4: Context Gathering.

Do not advance without explicit user approval. The wireframe is the foundation
everything else builds on - if the structure is wrong, no amount of good writing in
later phases will compensate.

If the user requests changes, apply them and return to Phase 2: Refinement to
re-validate the updated wireframe before seeking approval again.

______________________________________________________________________

## Phase 4: Context Gathering

With an approved wireframe in hand, you now gather the information needed to write each
section.

### One tag at a time

Dispatch subagents to research content for **one wireframe tag per wave**. This
constraint exists because mixing research across sections leads to unfocused, sprawling
context dumps that confuse the drafting stage.

For each `<Section>` tag:

- Spawn a subagent tasked with finding everything relevant to that section
- The subagent should explore the codebase, read relevant files, check tests, configs,
  CLI help output - whatever is needed to populate that section accurately
- Collect the subagent's findings as structured context for that section

For each `<Title>` tag: titles typically don't need deep research - they frame the
sections below them.

### Context format

Each section's gathered context should include:

- Key facts, names, paths, commands relevant to the section
- Code snippets or config examples if applicable
- Any caveats, gotchas, or edge cases discovered
- Source locations (file paths, line numbers) for technical review later

______________________________________________________________________

## Phase 5: Documentation Drafting

Each section is drafted by an isolated subagent that receives ONLY:

- The current wireframe tag (just the one it's writing)
- The gathered context for that tag
- The editorial guidelines (see `references/prose-style-rules.md`)
- The document's title and audience (for tone calibration)

The subagent does NOT receive:

- The full wireframe
- Other sections' context
- Direct codebase access

This isolation is intentional. A drafter who can see the whole document tends to repeat
information across sections, add tangential details, and lose focus. A drafter who can
only see its own section stays on task.

### Assembly

After all sections are drafted, assemble them into a single markdown document following
the wireframe's order. Add transitions between major sections if needed, but keep them
minimal - the wireframe structure should carry the flow.

______________________________________________________________________

## Phase 6: Technical Review

The assembled document now goes through technical verification. This catches errors that
drafting subagents introduce - wrong function names, incorrect flags, outdated paths,
misleading descriptions of behavior.

### Review process

Spawn parallel subagents, each responsible for verifying a portion of the document. Each
reviewer should:

- Read the section(s) assigned to it
- Cross-reference every technical claim against the actual codebase:
  - Are module names, function names, and class names correct?
  - Do CLI commands and flags actually exist and work as described?
  - Are file paths and config keys accurate?
  - Do code examples actually run?
  - Are described behaviors true to the implementation?
- Report findings as a list of corrections needed, with evidence (file path, line
  number, actual behavior vs. documented behavior)

Apply all corrections to the document. If a correction changes the meaning of a section
significantly, flag it - the section may need partial redrafting.

______________________________________________________________________

## Phase 7: Editorial Review

A subagent with **zero context** reviews the document purely on the merit of the
writing. It receives the assembled, technically-reviewed document and nothing else - no
codebase access, no wireframe, no knowledge of what the project is or does.

The subagent must:

- **Read** `agents/editorial-reviewer.md` - the full agent instructions.
- **Read** `references/prose-style-rules.md` in full - the prose and style rule system
  that grounds all editorial evaluation. Every finding must cite a specific rule.
- **Receive only the document** as input. No codebase, no wireframe, no project context.

The agent returns findings only - issues with location, rule citation, and suggested
fix.

### Applying editorial feedback

Apply editorial feedback to the document. For changes that alter technical content
(e.g., the reviewer suggests simplifying a paragraph that contains important nuance),
use your judgment - readability matters, but not at the cost of accuracy.

______________________________________________________________________

## Phase 8: User Approval (Final)

Present the finished document to the user. Include a brief summary of:

- What the refinement reviewer flagged and how it was addressed
- What the technical reviewer corrected
- What the editorial reviewer improved

The user reviews the document and either approves it or requests changes. If changes are
requested, determine which pipeline phase they affect:

- Structural changes - return to Phase 1: Wireframe
- Content gaps - return to Phase 4: Context Gathering
- Writing quality - return to Phase 7: Editorial Review
- Factual errors - return to Phase 6: Technical Review
- Minor tweaks - apply directly

______________________________________________________________________

## Working with the user

Throughout the pipeline, keep the user informed at natural milestones:

- "Here's the wireframe - the refinement reviewer flagged X, I've addressed Y, here's
  what I need your input on for Z"
- "Context gathering complete for all sections. Moving to Phase 5: Drafting."
- "Technical review found 3 corrections. Editorial review suggested 5 improvements.
  Here's the final document."

The user's time is valuable. Don't ask for input on things you can decide yourself. Do
ask for input on things that affect what the document says or how it's structured.