audit-first-commentary

Documenting code invariants and design tradeoffs involves adding concise file-level blocks that summarize purpose, failure modes, and alternatives considered. This practice improves readability, maintenance, and auditability for non-trivial modules.

To document failure modes during complex logic refactoring, add a concise summary of potential failure scenarios directly within the file-level documentation block at the top of the non-trivial file.

You need to document design tradeoffs when writing new modules, refactoring complex logic, updating CI/scripts, or modifying configuration to ensure consistent documentation and capture decisions for future contributors.

You can enforce consistent inline comments and file headers by applying a standard file header structure alongside a lightweight review process, ensuring all non-trivial files document invariants and tradeoffs consistently.

Yes, this documentation approach explicitly applies to updating CI/scripts and modifying configuration, requiring file- and function-level comments to capture invariants, failure modes, and design tradeoffs in these non-trivial files.