Documentation Update Loop

Overview

The documentation update loop discovers and fixes problems in existing documentation for a specific topic or area. Unlike the Documentation Bootstrap loop (which generates docs from scratch), this loop targets scoped updates with source verification, structural validation, and accuracy checks.

The current tracked artifacts are .agents/tasks/prd-doc-update.json, .agents/tasks/templates/prd-doc-update.template.json, and the convenience copy .agents/tasks/prd-active.json. Treat any additional prompt/engine paths below as local setup that must be verified before execution.

Template: prd-doc-update.template.json Prompt: PROMPT_docs-update.md Stories: 9 (DU00-DU08)

Story Breakdown

Phase	ID	Title	Depends On	Output
Scope	DU00	Lock effective scope	--	.ralph/docs-update-scope.md
Discovery	DU01	Code drift, accuracy audit, gap analysis	DU00	.ralph/docs-update-discovery.md
Discovery	DU02	Link validation and nav sync	DU00	.ralph/docs-update-links.md
Planning	DU03	Merge findings into prioritized plan	DU01, DU02	.ralph/docs-update-plan.md
Extraction	DU04	Create extraction artifacts	DU03	.ralph/docs-update-extractions.md
Writing	DU05	Apply documentation updates	DU04	Updated .mdx files
Verification	DU06	Structural lint and link check	DU05	.ralph/docs-update-verification.md
Verification	DU07	Technical accuracy spot-check	DU05	.ralph/docs-update-accuracy.md
Final	DU08	Build validation and report	DU06, DU07	.ralph/docs-update-report.md

Dependency Graph

DU01 and DU02 are independent -- link validation doesn't need source drift analysis and vice versa. Similarly, DU06 and DU07 are independent verification tracks that can run in any order.

Phases Explained

Phase 1: Scope (DU00)

Converts the user's intent (e.g., "update k12 workflow docs") into concrete include/exclude paths for both source code and documentation files. Maps source directories to their corresponding doc directories.

Phase 2: Discovery (DU01, DU02)

Two independent analyses:

• DU01 discovers content problems: stale claims, inaccurate values, missing sections, placeholder content, and gaps where source code has no corresponding documentation.
• DU02 discovers structural problems: broken internal links, orphaned pages not in sidebars.js, dead navigation entries, and missing cross-references between related docs.

Phase 3: Planning and Extraction (DU03, DU04)

DU03 merges all findings into a prioritized remediation plan with batches grouped by doc file. DU04 reads source code to create lean extraction artifacts for changes that need new content (not just corrections).

Phase 4: Writing and Verification (DU05, DU06, DU07)

DU05 applies all updates from the plan using a surgical edit approach. Then two independent verification tracks run:

• DU06 checks structural quality: frontmatter, heading structure, Mermaid rendering, link integrity, sidebar sync.
• DU07 performs a technical accuracy spot-check on the top 5 highest-impact changes by re-reading the source code and verifying every concrete claim.

Phase 5: Final Validation (DU08)

Runs the Docusaurus build validation and compiles a comprehensive report with metrics, change summary, and recommendations for future iterations.

Quality Gates

1. Read .ralph/intake/current-guidelines.json at the start of every story
2. Never modify files outside scope.include except tracking artifacts
3. Every factual claim must be source-verified before writing
4. Preserve existing doc structure and style unless the finding requires change
5. Keep sidebars.js in sync when adding/removing/renaming docs
6. Use extract-then-write pattern for new content
7. Never fabricate content -- defer if source cannot be found
8. After any doc edit, verify no broken internal links were introduced
9. Require Docusaurus build validation before final story

Finding Categories

Type	Description
STALE	Content no longer matches source code
INACCURATE	Factual error (wrong path, enum, config key)
MISSING	Required section or page entirely absent
INCOMPLETE	Section exists but lacks depth
PLACEHOLDER	TODO, TBD, "coming soon"
RENDERING_BUG	Mermaid \n, broken frontmatter
BROKEN_LINK	Internal link target does not exist
ORPHANED_PAGE	Doc file not in sidebars.js
DEAD_NAV_ENTRY	sidebars.js entry with no file
MISSING_XREF	Related docs not cross-referencing each other

Findings are prioritized by severity:

Severity	Criteria
Critical	Actively misleading, broken rendering, placeholder text
High	Inaccurate claims, missing required sections, broken links
Medium	Incomplete coverage, missing cross-references
Low	Style issues, minor structural improvements

Scope Configuration

The loop scope is set via intake. Examples:

# Target a specific domain
/docs-update-loop-bootstrap k12 workflows

# Target a source directory
/docs-update-loop-bootstrap src/auth/**

# Target a doc section
/docs-update-loop-bootstrap loops

# Target Bruno testing docs
/docs-update-loop-bootstrap bruno-testing

When no scope is provided, defaults to repository-wide docs update.

Artifacts

Artifact	Written By	Purpose
.ralph/docs-update-scope.md	DU00	Source-to-doc mappings, scope guards
.ralph/docs-update-discovery.md	DU01	Findings by severity and type
.ralph/docs-update-links.md	DU02	Broken links, orphaned pages, nav issues
.ralph/docs-update-plan.md	DU03	Prioritized remediation batches
.ralph/docs-update-extractions.md	DU04	Extraction artifact inventory
.ralph/docs-update-verification.md	DU06	Lint and link check results
.ralph/docs-update-accuracy.md	DU07	Accuracy spot-check results
.ralph/docs-update-report.md	DU08	Final report with metrics and recommendations