AI-assisted Writing Process

Source scan, draft, deterministic validation, agent smoke test, owner review, and freshness monitoring.

Key takeaways

AI writing works only when the workflow separates fast drafting from forced evidence, deterministic checks, and ownership.
The lifecycle runs source scan, design, draft, deterministic validation, agent smoke test, owner review, publish, and freshness monitoring as a loop.
Constrain the draft prompt to use only provided sources, forbid inventing commands, APIs, versions, or owners, and require a final "unknowns" section.
Run deterministic checks (links, types/build, OpenAPI lint/diff, code blocks, frontmatter, command-vs-package.json) before human review.
Smoke-test the document by asking an agent to use it without editing files, which catches drafting failures like hallucination, over-explanation, and date errors.

Writing documentation with AI is effective only when the workflow separates drafting from validation. The agent can draft quickly, but the team must force evidence, checks, and ownership.

Lifecycle

Step	Actor	Activity	Output
Source scan	AI + human	Read code, specs, docs, official references	Evidence list
Design	Human	Choose surface, owner, validation, freshness	Design sheet
Draft	AI	Generate from template and sources	MD/MDX draft
Validation	Automation	Link, schema, code block, build checks	CI result
Smoke test	AI + human	Verify agents can use the document	Failures
Owner review	Human	Check facts, security, tone, ownership	Approval
Monitor	CI + owner	Detect drift and stale docs	Issues

Source Scan

## Source Scan

Read:
- code: `src/api/**`, `app/api/**`
- specs: `openapi/**`, `schema/**`
- project rules: `AGENTS.md`, `CLAUDE.md`, `.claude/rules/**`
- skills: `.agents/skills/**/SKILL.md`
- official docs: [links]

Rules:
- Do not invent commands.
- Do not infer current versions without source documents.
- Mark unknowns explicitly.

Document Design Sheet

## Document Design

- Purpose:
- Primary reader: human / coding agent / RAG / MCP client
- Surface:
- Owner:
- Source of truth:
- Project-specific facts to include:
- Generic background to omit:
- Validation commands:
- Smoke test prompt:
- Freshness policy:

Draft Prompt

Write a documentation draft using only the sources below.
Do not invent commands, APIs, versions, owners, or policies.

Sources:
- [files and links]

Output:
- frontmatter
- tables and code blocks where useful
- completion criteria
- validation commands
- a final "unknowns" section

Deterministic Validation

Check	Example
Links	`pnpm docs:links`
Types/build	`pnpm typecheck`, `pnpm build`
OpenAPI	`pnpm openapi:lint`, `pnpm openapi:diff`
Code blocks	shellcheck, doctest
Frontmatter	custom lint
File paths	path existence check
Commands	compare docs against `package.json` scripts

Agent Smoke Tests

Project rules

Assume you need to edit an API route in this repository.
Which files should you inspect and which validation commands should you run?
Do not modify files.

API docs

Using only this API document, explain how to call `POST /orders`,
including auth, request body, error handling, and any uncertainty.

Skills

Assume you are using the `release-check` Skill for the current diff.
List the commands, output format, and approval boundaries without editing files.

Common AI Drafting Failures

Failure	Symptom	Fix
Hallucination	Nonexistent API or command	Source scan first
Over-explanation	Generic tutorials	State "omit generic background"
Date errors	Old facts labeled current	Include current date and source date
Security gaps	Sensitive examples or broad tools	Security checklist
Drift	Docs conflict with code	CI checks and owner review

Checklist

Item	Check
Evidence sources are listed	[ ]
Unknowns are separated from facts	[ ]
Deterministic checks are included	[ ]
Agent smoke test exists	[ ]
Owner and freshness policy are clear	[ ]

Key takeaways

AI writing works only when the workflow separates fast drafting from forced evidence, deterministic checks, and ownership.
The lifecycle runs source scan, design, draft, deterministic validation, agent smoke test, owner review, publish, and freshness monitoring as a loop.
Constrain the draft prompt to use only provided sources, forbid inventing commands, APIs, versions, or owners, and require a final "unknowns" section.
Run deterministic checks (links, types/build, OpenAPI lint/diff, code blocks, frontmatter, command-vs-package.json) before human review.
Smoke-test the document by asking an agent to use it without editing files, which catches drafting failures like hallucination, over-explanation, and date errors.

Writing documentation with AI is effective only when the workflow separates drafting from validation. The agent can draft quickly, but the team must force evidence, checks, and ownership.

Lifecycle

Step	Actor	Activity	Output
Source scan	AI + human	Read code, specs, docs, official references	Evidence list
Design	Human	Choose surface, owner, validation, freshness	Design sheet
Draft	AI	Generate from template and sources	MD/MDX draft
Validation	Automation	Link, schema, code block, build checks	CI result
Smoke test	AI + human	Verify agents can use the document	Failures
Owner review	Human	Check facts, security, tone, ownership	Approval
Monitor	CI + owner	Detect drift and stale docs	Issues

Source Scan

## Source Scan

Read:
- code: `src/api/**`, `app/api/**`
- specs: `openapi/**`, `schema/**`
- project rules: `AGENTS.md`, `CLAUDE.md`, `.claude/rules/**`
- skills: `.agents/skills/**/SKILL.md`
- official docs: [links]

Rules:
- Do not invent commands.
- Do not infer current versions without source documents.
- Mark unknowns explicitly.

Document Design Sheet

## Document Design

- Purpose:
- Primary reader: human / coding agent / RAG / MCP client
- Surface:
- Owner:
- Source of truth:
- Project-specific facts to include:
- Generic background to omit:
- Validation commands:
- Smoke test prompt:
- Freshness policy:

Draft Prompt

Write a documentation draft using only the sources below.
Do not invent commands, APIs, versions, owners, or policies.

Sources:
- [files and links]

Output:
- frontmatter
- tables and code blocks where useful
- completion criteria
- validation commands
- a final "unknowns" section

Deterministic Validation

Check	Example
Links	`pnpm docs:links`
Types/build	`pnpm typecheck`, `pnpm build`
OpenAPI	`pnpm openapi:lint`, `pnpm openapi:diff`
Code blocks	shellcheck, doctest
Frontmatter	custom lint
File paths	path existence check
Commands	compare docs against `package.json` scripts

Agent Smoke Tests

Project rules

Assume you need to edit an API route in this repository.
Which files should you inspect and which validation commands should you run?
Do not modify files.

API docs

Using only this API document, explain how to call `POST /orders`,
including auth, request body, error handling, and any uncertainty.

Skills

Assume you are using the `release-check` Skill for the current diff.
List the commands, output format, and approval boundaries without editing files.

Common AI Drafting Failures

Failure	Symptom	Fix
Hallucination	Nonexistent API or command	Source scan first
Over-explanation	Generic tutorials	State "omit generic background"
Date errors	Old facts labeled current	Include current date and source date
Security gaps	Sensitive examples or broad tools	Security checklist
Drift	Docs conflict with code	CI checks and owner review

Checklist

Item	Check
Evidence sources are listed	[ ]
Unknowns are separated from facts	[ ]
Deterministic checks are included	[ ]
Agent smoke test exists	[ ]
Owner and freshness policy are clear	[ ]

Lifecycle

Source Scan

Document Design Sheet

Draft Prompt

Deterministic Validation

Agent Smoke Tests

Project rules

API docs

Skills

Common AI Drafting Failures

Checklist

On This Page

AI-assisted Writing Process

Lifecycle

Source Scan

Document Design Sheet

Draft Prompt

Deterministic Validation

Agent Smoke Tests

Project rules

API docs

Skills

Common AI Drafting Failures

Checklist

On This Page