> ## Documentation Index
> Fetch the complete documentation index at: https://sdlc-rstack.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Stage 03 — Documentation

> Documentation Agent. Turns requirement_spec.json into client-facing BRD, FRD, and draft SOW, plus the run's shared spec-anchor.

<Info>
  **File:** `agents/sdlc/03-documentation.md` · **Model:** Sonnet · **Tools:** Bash, Read, Write
</Info>

## Purpose

The documentation agent produces the professional, enterprise-grade documents that get sent to the client for sign-off: a Business Requirements Document, a Functional Requirements Document, and a draft Statement of Work. It writes for two audiences at once — "the engineer who picks this up at midnight with no context, and the executive who needs the key decision in 30 seconds" — and treats vague language as a real risk, since a sentence like "the system will support user roles" is exactly the kind of gap that turns into a disputed change request three months later.

It is also the first stage to write `spec-anchor.md`, a short orientation document that every later stage (04–14) reads first when its own context is full.

## How it works

**Input:** `$RSTACK_RUN_DIR/artifacts/requirements/requirement_spec.json` (stage 02's output). The agent stops and reports which upstream agent needs to run if this file is missing, and reports the parse error if it's malformed.

**Context budget:** stage 3 of 15, capped at 5 files read before writing begins; if `requirement_spec.json` is large (>200 lines) it reads only `functional_requirements`, `non_functional_requirements`, and `out_of_scope`.

**Spec anchor first.** Before any client document, it writes `${RUN_BASE}artifacts/spec-anchor.md` — run id, one-sentence goal, primary stack, top 5 core requirements, out-of-scope summary, key constraints, and a stage-status line (`00=PASS 01=PASS 02=PASS 03=IN_PROGRESS 04=PENDING ...`). This is the "steering document" pattern: it survives context compaction and gives any downstream agent orientation in under 200 tokens.

**Adopted runs (brownfield).** If the run was created by `rstack-agents adopt`, the agent checks `manifest.json` for `"mode": "adopt"` and looks for a harvested `documentation.json` tagged `"source": "brownfield-adoption"`. If found, that baseline's `docs` array indexes the project's real existing documents — the agent reads those first as the authoritative record, and only writes BRD/FRD/SOW content for the change being made or for gaps the baseline exposes. It never regenerates documentation for functionality that already ships.

Once oriented, it runs four tasks against `$RSTACK_RUN_DIR/artifacts/documents/`:

| Task | File                        | Structure highlights                                                                                                                                                            |
| ---- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | `BRD.md`                    | Executive summary, business objectives/KPIs, current vs. future state, scope, business requirements, stakeholders, success metrics, assumptions/constraints, risks              |
| 2    | `FRD.md`                    | System overview, user roles/permissions matrix, FRs by module (ID, actors, priority, acceptance criteria), NFRs, data/integration/UI/security requirements, traceability matrix |
| 3    | `SOW.md`                    | Scope of work, deliverables table, timeline, team structure, assumptions, acceptance criteria, change management, sign-off placeholder                                          |
| 4    | `documentation_output.json` | Machine-readable summary contract (see below)                                                                                                                                   |

Every requirement ID in the FRD must trace back to an ID in `requirement_spec.json` — that's a pinned quality rule, not just a convention.

## Output contract

`documentation_output.json` is what the next stage reads:

```json theme={null}
{
  "contract_version": "1.0",
  "produced_by": "documentation_agent",
  "timestamp": "<ISO 8601 timestamp>",
  "documents_created": [
    "$RSTACK_RUN_DIR/artifacts/documents/BRD.md",
    "$RSTACK_RUN_DIR/artifacts/documents/FRD.md",
    "$RSTACK_RUN_DIR/artifacts/documents/SOW.md"
  ],
  "requirement_spec_path": "$RSTACK_RUN_DIR/artifacts/requirements/requirement_spec.json",
  "total_functional_requirements": 0,
  "total_non_functional_requirements": 0,
  "total_modules": 0,
  "estimated_complexity": "LOW|MEDIUM|HIGH|VERY_HIGH",
  "domain": "<from requirement spec>",
  "next_agent": "planning_agent",
  "next_input_file": "$RSTACK_RUN_DIR/artifacts/documents/documentation_output.json"
}
```

<Note>
  The agent file itself mixes two path conventions: the newer `.rstack/runs/<run_id>/artifacts/` layout used by the Spec Anchor and Context Recovery sections, and the legacy `$RSTACK_RUN_DIR/artifacts/documents/` layout used by the Task 1–4 instructions (with a documented legacy fallback lookup at `$RSTACK_RUN_DIR/artifacts/documents/`). Both are honored by the agent's own recovery logic — this page describes both rather than picking one.
</Note>

## Optional publishing step

After generating the local files, the agent offers an interactive publishing menu — local-only (default), Confluence, Notion, SharePoint/OneDrive, PDF export (via the `pdf` skill), or a combination. Each remote option is gated on the relevant credentials being present (`CONFLUENCE_URL`/`CONFLUENCE_TOKEN`/`CONFLUENCE_SPACE_KEY`, `NOTION_API_KEY`/`NOTION_DATABASE_ID`, or an MS Graph token); the choice is recorded in `user_preferences.documentation_platform`.

## Gate and handoff

There is no dedicated validator profile named in this stage's agent file — its own **Quality Self-Check** is the mechanism: before reporting done, it verifies the BRD covers every business goal from the transcript, the FRD traces every functional requirement to a source ID, and a non-technical reader would follow the executive summary. Any "no" answer means fix it before reporting status ("a fast DONE\_WITH\_CONCERNS is better than a wrong DONE").

Completion is reported as `STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`, following the shared Task Contract shape in `agents/OPERATING-STANDARD.md`. `BLOCKED` covers a missing or malformed `requirement_spec.json`; `NEEDS_CONTEXT` is used to ask one question about a critical document gap. On success, the agent hands off directly to the Planning Agent (stage 04), passing `documentation_output.json` and `requirement_spec.json` as inputs and instructing it not to stop until the next agent is triggered in turn.

## Where it sits in the pipeline

Stage 03 sits between **02 — Requirements** (its input) and **04 — Planning** (its handoff target), in the documentation/requirements branch of the pipeline alongside 10-summary — see the [pipeline overview](/sdlc-pipeline/overview)'s routing map.

## Related

* [Pipeline Overview](/sdlc-pipeline/overview)
* [Agent 02 — Requirements](/sdlc-pipeline/requirements)
* [Agent 06 — Architecture](/sdlc-pipeline/architecture)