Practical workflows
Documentation Backfill Workflow
Reconstruct missing documentation from code, tests, configuration, history, and observed behavior while marking uncertainty and keeping volatile claims sourced.
- Format
- Playbook
- Level
- Intermediate
- Audience
- Practitioner, Developer, Operator
- Owner
- Project42 Editorial
- Review cadence
- Every 90 days
- Prerequisites
- Read access to the implementation and existing evidence; An identified audience and documentation purpose; A reviewer who can validate behavior or ownership
Inventory evidence and authority
List the missing decisions, setup, interfaces, operations, troubleshooting, and recovery information by audience. Gather source code, public contracts, schemas, tests, configuration templates, release notes, issue and decision history, runtime output, and current first-party dependency documentation.
Label facts, inferred behavior, recommendations, unknowns, and volatile external claims separately. Code can reveal current behavior but not always intent, support policy, safety, or the reason for a decision.
Draft a reproducible path and test it cold
Ask AI to map every material claim to evidence and to flag conflicts instead of resolving them silently. Write prerequisites, supported scope, steps, expected results, failure meanings, verification, recovery, owner, and review date.
Have a reviewer who did not write the draft follow it in a safe environment. Convert every ambiguity, missing prerequisite, wrong assumption, and stale link into a correction or tracked gap.
Task: [MISSING DOCUMENT AND USER OUTCOME]
Scope: [COMPONENT, VERSION, AUDIENCE, SUPPORTED ENVIRONMENTS, AND EXCLUSIONS]
Permissions: [SOURCE/HISTORY/LOG READ, SAFE EXECUTION, WRITABLE DOC PATHS]
Evidence inventory: [CODE, CONTRACTS, TESTS, CONFIG, HISTORY, RUNTIME, AND SOURCES]
Claim map: [CLAIM -> FACT | INFERENCE | RECOMMENDATION | UNKNOWN -> EVIDENCE]
Document contract: [PREREQUISITES, STEPS, EXPECTED RESULT, FAILURES, OWNER, REVIEW DATE]
Stop conditions: [SECRET, UNSAFE REPRODUCTION, CONFLICTING EVIDENCE, OR MISSING OWNER]
Verification: [COLD READER TEST, COMMAND/LINK CHECK, CLAIM REVIEW, AND USER OUTCOME]
Recovery: [REVERT DOC CHANGE, MARK UNSUPPORTED CLAIM, PRESERVE GAP AS TRACKED WORK]Expected evidence and verification
Expected evidence includes the gap inventory, audience, source map, claim classifications, conflicts and unknowns, reviewed draft, cold-reader results, checked commands and links, supported-version statement, owner, and review cadence.
Stop when documentation would expose a secret, require an unsafe production experiment, or present an inference as supported fact. Remove or label the unsupported claim, restore the prior published version if necessary, and retain the unresolved gap as explicit tracked work.