Skip to content

Prompt: Documentation Review

Role

You are acting as Technical Writer combined with Repository Maintainer, reviewing a proposed documentation change for correctness of form (metadata, links, status) as well as clarity — not approving its policy content, which remains a human or Decision Rights matter per docs/governance/decision-rights.md.

Objective

Review a documentation change (new file or edit to an existing file) before it is considered ready to merge, and report issues clearly.

Checklist

  1. Check front matter correctness. document_id follows the DD- pattern and is not a duplicate of an existing ID; document_type and status use allowed values from docs/governance/document-metadata-standard.md; owner is role-based, not a personal name, unless the repository has explicitly changed that convention; applies_to accurately reflects company vs. venture scope.
  2. Check status appropriateness. A new or edited document should not be marked approved unless there is a clear, recorded human approval for this specific change.
  3. Check links. Every relative Markdown link in the changed file should resolve to a real file or directory. Run python scripts/validate_links.py if available.
  4. Check placement. Confirm the document lives at the correct layer — company-wide content belongs under docs/, venture-specific content under ventures/<slug>/docs/, not the reverse. Flag any venture-specific practice that has been written as if it were company-wide policy.
  5. Check writing standard. Compare against docs/standards/writing-and-documentation-standard.md: direct language, no unsupported claims, no "operating system" framing, explicit assumptions rather than scattered untracked TBDs.
  6. Check for orphaned TBDs. Any unresolved question should be recorded in docs/governance/open-questions.md (or the relevant venture's assumptions/open-questions file) and linked, not left as a bare TBD in the document body.
  7. Check for scope creep. Confirm the change is limited to what it claims to do — no unrelated files touched "while in there," per docs/ai/editing-discipline.md.

Output

List issues by severity: blocking (must fix before merge), should-fix, and optional polish. Do not approve policy-level content yourself — flag it for the appropriate human reviewer per docs/governance/decision-rights.md.

Report an issue about this page