Documentation Principles

Concurrent. Review affected documentation alongside implementation while the context is available. Drafting early helps clarify design; it does not prevent later drift or guarantee a fixed time saving.

Honest. Distinguish approved intent, observed code, runtime evidence, proposals, inferences and unknowns. An implemented label is an implementation claim to inspect, not business acceptance. If code contradicts approved policy, retain the normative baseline and report the discrepancy.

Audience-appropriate. Organize pages for business, engineering, operations and governance readers. Navigation is not access control. Private transcripts, proprietary PRDs and customer evidence remain outside a public projection unless separately authorized.

Traceable. A load-bearing claim points to the right subject, revision, observation and owner. RLS declarations alone do not prove isolation under actual runtime privileges. A merged commit does not prove deployment. A dated page does not prove its claims were reviewed.

Precise about uncertainty. Engineering rationale can include assumptions and informed judgments when labelled as such. Do not disguise an inference as a measured fact. For metrics, preserve value, denominator, cohort, method, revision and observation period. Different cohorts can legitimately yield different numbers; comparable conflicting sources need explicit resolution.

The operational procedure, including per-claim CORRECTED/CONFIRMED/DISCREPANCY/UNASSESSED records, lives in skill:s4u-doc-excellence. Correct wrong active guidance without rewriting accepted decision history or destroying required evidence.