Doc revalidate

doc_revalidate is a pipeline-layer request type that keeps a project's whole documentation landscape — markdown prose, HTML doc sites, and prompt/schema/config/example files that act as documentation or contracts — in sync with its real code. It discovers every doc surface, validates code↔docs agreement, fixes drift, and drafts first-pass docs for gaps, all through the native staged lifecycle rather than a standalone action flow.

All request types

Its mechanics live once in the shared recipe _processes/_shared/recipes/doc_revalidate.md, which the plan, execute, and validate stages read through a thin type-conditional pointer. The preset _processes/_shared/presets/doc_revalidate.md seeds the JOB.md defaults.

The flow

As a pipeline type, doc_revalidate runs the orchestrator's staged lifecycle, but with a lean default stage set. Per the preset, three stages are enabled out of the box — plan → execute → validate — and the rest (clarify, brainstorm, test, document, review) are optional and disabled by default. plan owns documentation-landscape discovery, the coverage matrix, the segmentation map, and the write allow-list; execute runs the recipe's read-only survey then a confined write pass; validate adversarially re-checks the result.

Inside execute, the shared recipe drives an internal validate→fix→draft loop over the discovered segments. The recipe discovers the landscape, validates each segment's docs against the code it documents, triages every mismatch (fix the doc, or capture the code issue for hand-off), then in a confined write pass fixes drifted docs and drafts first-pass docs for gaps.

What it is for

Use doc_revalidate when you want the entire documentation landscape re-synced with the code in one repeatable run. Unlike a single-folder doc job, it discovers all documentation surfaces across all relevant formats, segments them, fans out code↔doc validation, fixes drifted docs, and drafts source-backed first-pass docs for gaps — with every write confined to a discovered/approved multi-root allow-list. Because revalidating docs means reading almost the whole codebase, the run also captures out-of-scope code/app issues it spots as hand-off-ready cards in 04_execution/found-issues.md (it never fixes them — docs only).

Close calls — which doc job do I want? Three capabilities touch documentation; pick by scope and write posture.

doc_revalidate (this type, pipeline): the whole doc landscape, all formats, multiple roots — discover → validate → fix drift → draft gaps, via the staged pipeline.
doc_upkeep (action): validate and update one existing HTML docs folder against the code and the UI kit, confined to a single mandatory target folder. Narrower and write-capable. See doc_upkeep.
audit with Kind: doc_drift (action, read-only): a whole-app doc↔code drift sweep that only reports — it writes no docs. doc_revalidate's survey pass reuses this framing but then fixes. See audit.

doc_revalidate reuses — and never modifies or duplicates — audit Kind: doc_drift, doc_upkeep, and doc_create.

The logic

After pickup, the orchestrator reads JOB.md → Type and looks up doc_revalidate in the registry: layer pipeline, shape pipeline. It therefore runs the normal staged lifecycle — it does not hand off to an action prompt. The stages enrich their work by reading the shared recipe through a type-conditional pointer.

Select-and-go (D-50). Because the work is fully defined by the recipe, the intake form hides the identity and mandate sections for this type. The slug is auto-generated as YY-MM-DD-doc-revalidate and a fixed whole-project mandate is auto-filled by interface/intake-generator.js (its AUTO_FILL entry). You only set stage-config, approval-gates, and git. The orchestrator's creation/bootstrap step still receives a complete, contract-valid intake (mandate + slug present), so the pipeline runs normally — there is nothing per-job to clarify, which is why clarify is off by default.

The fields

The intake form shows only stage-config, approval-gates, and git for this type — identity and mandate are auto-filled and hidden (D-50). The table below records the defaults the preset seeds into JOB.md.

doc_revalidate field defaults (source: `_processes/_shared/presets/doc_revalidate.md`)
Block	Field	Default	Notes
`## Identity`	Slug	auto `YY-MM-DD-doc-revalidate`	Hidden in form; auto-generated.
`# Mandate`	Mandate body	auto whole-project	Hidden in form; auto-filled via `AUTO_FILL`.
`## Stages`	clarify	disabled	Mandate is fixed/recipe-defined; enable (+ `after_clarify`) to confirm discovered doc roots.
	brainstorm	disabled	Approach is settled by the recipe.
	plan	enabled	Owns discovery, coverage matrix, segmentation, allow-list.
	execute	enabled	Survey pass → confined apply pass; writes `found-issues.md`.
	test	disabled	Edits documentation, not application code.
	document	disabled	Edits documentation, not application code.
	review	disabled	No source-code change to review.
	validate	enabled	Adversarial re-check; finalizes found-issues summary.
`## Approval gates`	after_creation	no	All non-git gates default off; turn on `before_execution` to review the discovered landscape + segmentation before the fan-out.
	after_clarify	no
	after_brainstorm	no
	before_plan	no
	before_execution	no
	before_commit	no	Renders inside the Git section.
	before_pr	no	Renders inside the Git section.
`## Git`	Create branch	no	Off by default — doc edits sit in the working tree for review. Turn on for branch/commit/PR.
	Validate against main	no
	Commit	no
	Push	no
	PR	no
	PR target branch	(blank)
`## Per-stage config`	Plan → Multi-phase	yes	Segments become phases.
	Execute → Delegate research to sub-agents	yes	Discovery + survey are fan-out heavy.
	Validate → Cross-check against mandate / Agent	yes / `claude`	Override `Agent` to `codex` per-job for Codex validation.

How to run it

In the intake form, pick doc_revalidate, set stage-config / approval-gates / git as desired, and submit — the slug and whole-project mandate are filled in automatically. Then start the orchestrator by sending it the prompt path:

Copy this path

_processes/02_orchestrator/orchestrator.prompt.md

The orchestrator picks up the job, routes it as a pipeline job, and runs the enabled stages. The stage mechanics — discovery, segmentation, the survey/apply loop, and the validate re-checks — come from the shared recipe at _processes/_shared/recipes/doc_revalidate.md, which plan, execute, and validate read via a type-conditional pointer. The run's documentation edits land in the discovered allow-list, and any out-of-scope code/app issues it spotted are recorded in 04_execution/found-issues.md with a ## Found issues for follow-up summary in 08_validate/validate-report.md.