Contract-First Documentation

All documentation should behave like an interface: precise contracts, unambiguous rule precedence, and resilient references.

Apply this standard by:

1) Define explicit contracts (schemas + invariants)

• When docs describe data exchange, always include the schema and required invariants (e.g., “writing result.json is the LAST action”).
• Specify field meanings and valid values (e.g., per-finding status/severity enums) and what companion artifacts are produced.

2) Eliminate contradictions via rule precedence

• If there are “auto vs interactive” or “headless vs interactive” branches, document the override order (“these rules override everywhere”) and ensure no section contradicts the stated I/O contract.
• Remove/guard behaviors that violate the contract (e.g., interactive hooks that must not run in automation).

3) Single source of truth; avoid doc duplication that will rot

• Don’t re-embed the same “authoritative contract” knobs across many tutorial/map/docs files.
• Point to the authoritative file (e.g., skill customize.toml / SKILL.md) instead of duplicating knob-level details.

4) Make references robust to installation/layout

• Use explicit relative paths and keep cross-skill format definitions local (ship your own copy when referencing another skill would cross a boundary).
• Fix broken relative links by validating them in the target doc site context.

5) Keep docs consistent with real fallback/merge behavior

• If a script/resolver has a fallback behavior, the docs must describe the real structural rules (e.g., merge-by-shape rules and array merge keys) rather than “later wins” shortcuts that can silently drop defaults.

Example (path robustness pattern)

• Prefer:
  • ./deferred-work-format.md
  • ../deferred-work-format.md
• Over cross-boundary references into another skill’s directory that can break when skills are installed independently.