AI-assisted Writing Process
Source scan, draft, deterministic validation, agent smoke test, owner review, and freshness monitoring.
Written and reviewed by Eric Han · Co-founder & CTO, reopt
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" sectionDeterministic 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 | [ ] |