Technical Writer

Document

Generate from diffs, not from scratch.

ReadSearchExecuteWrite

Why this phase exists

Documentation is the most-skipped step in development. By making it an autonomous workflow phase, it happens on every change. No exceptions. No "I'll document it later."

It comes after Review because it documents the final, approved state. Documenting before review wastes effort if reviewers request changes.

The agent generates documentation from diffs, not from a blank slate. The docs describe what actually changed, not what someone thinks changed.

Methodology

Receive artifacts

Code diff, build report, review verdict, and plan artifact. These are your source of truth.

Analyze the diff

Understand what changed, what was added, what was removed. The diff is the single source of truth for documentation.

Identify documentation targets

Which existing docs need updating? Which new docs need creating? Read existing documentation to find what must change.

Route documentation type

Architecture change: create an ADR. New feature: update feature docs. Bug fix: changelog entry. API change: update API reference.

Generate documentation

Produce structured docs with file:line references back to the implementation. Every claim traces to a code change.

Write documentation files

Update existing docs or create new ones. Follow existing documentation style and structure in the project.

Inputs and outputs

Inputs

• Code diff
• Build report ($build_report)
• Review verdict ($review_verdict)
• Plan artifact ($plan_artifact)

Outputs

• Updated documentation files
• New ADRs (if architectural changes)
• Changelog entries

Consumed by: Deploy phase for commit packaging

Documentation output structure

## Documentation Generated

### Architecture Decisions
- Added Redis caching as a read-through layer for user queries
  (src/cache/redis-client.ts:1-45)

### Implementation Details
- Cache strategy: read-through with TTL-based expiration
  1. Check Redis for cached result on GET requests
  2. On miss, query database and store result with 5-minute TTL
  3. Invalidate cache on any write to the same resource

### Files Updated
- docs/architecture/caching.md -- Updated caching strategy documentation
- CHANGELOG.md -- Added entry for Redis caching layer

### Files Created
- docs/decisions/008-redis-caching.md -- ADR for caching strategy

Example: documenting an infrastructure change (Redis caching layer). The Document phase generates from the actual diff, referencing specific files and architectural decisions.

Agent pattern

Single Agent / Multi-Agent for Large Diffs

Small diffs: a single agent handles all documentation. Large diffs (20+ files): spawn domain-specific subagents (backend docs, frontend docs, test coverage notes). Main Writer synthesizes into coherent documentation.

Conditional routing: subagents only read docs relevant to their domain. The backend analyst does not read frontend docs and vice versa. This keeps context windows focused.

Tool permissions

ReadSearchExecuteWrite

Document needs Write to create and update documentation files. Execute is denied because this phase does not need to run tests or scripts. It only reads code and writes text.

Prompt template

# Document Phase -- Technical Writer

## Role
You are a Technical Writer. Your job is to generate
documentation from the code changes, not from scratch.

You document what actually changed. You reference specific
files and lines. You write for two audiences: developers
who will maintain this code, and the team's decision log.

## Context
Plan Artifact:
${plan_artifact}

Build Report:
${build_report}

Review Verdict:
${review_verdict}

Code Diff:
${code_diff}

Existing Docs Directory: ${docs_directory}
Changelog Path: ${changelog_path}

## Documentation Routing

### If architecture change detected:
- Create an Architecture Decision Record (ADR)
- Format: docs/decisions/NNN-title.md
- Include: Context, Decision, Consequences

### If new feature:
- Update relevant feature documentation
- Add usage examples if applicable
- Update API documentation if endpoints changed

### If bug fix:
- Add CHANGELOG entry
- Update any docs that described the incorrect behavior

### If API change:
- Update API reference docs
- Note breaking changes prominently
- Include migration notes if applicable

## Methodology
1. Read the code diff to understand what changed
2. Read existing documentation to find what needs updating
3. Generate new documentation from the diff
4. Reference specific file:line locations in your docs
5. Write documentation files

## Constraints
- Generate from the diff, not from imagination.
- Every claim in the docs must trace to a code change.
- Reference specific file:line for implementation details.
- Follow existing documentation style and structure.
- Do not document code that didn't change.
- Keep it concise. Engineers read docs when stuck, not for fun.

## Output Format
1. Architecture Decisions -- Key decisions with rationale
2. Implementation Details -- What changed and why
3. Files Updated -- Existing docs modified
4. Files Created -- New documentation files
5. Changelog Entry -- Formatted for the project's changelog

Role AssignmentTemplate VariablesDocumentation RoutingDiff-Based GenerationADR Pattern

Best practices

Do

Generate from diffs, not from memory
Reference specific file:line locations
Follow existing documentation style
Create ADRs for architectural decisions
Keep it concise and scannable

Don't

Document code that did not change
Write aspirational documentation
Duplicate information from code comments
Skip the changelog entry
Describe intent instead of actual changes

Nuances

"Generate from diffs, not from scratch" is the core principle

Traditional documentation asks agents to describe code from memory. This phase works from the actual diff. If it is not in the diff, it does not get documented.

Architecture decision records (ADRs)

When the plan or review identified an architectural choice, the Document phase captures it as a formal ADR. This builds an audit trail automatically, and each ADR follows the Context-Decision-Consequences structure.

Documentation as a non-blocking phase

If Document fails, the workflow should still proceed to Deploy. Documentation matters but it is not on the critical path. A failed documentation phase should log a warning, not halt the workflow.

Conditional documentation routing

In a large monorepo, the Document agent should not read all documentation. Route it: backend changes get backend docs, frontend changes get frontend docs. This keeps context windows focused and output relevant.

Review Phase Deploy Phase