Record a decision whenever any of these are true:

• Structural choice — the call affects boundaries, assumptions other code depends on, or the composition model.
• Non-obvious behavior — the code does something that would surprise a future reader; the decision log is the explanation.
• Why-not-the-alternative — the obvious alternative will be suggested in review; write the rationale now so the discussion doesn't recur.

Do NOT record mechanical changes (renaming, formatting, dependency bumps) or decisions self-evident from the diff.

1. Locate the governing design under wiki/designs/ (e.g. crickets-development-lifecycle.md, crickets-developer-safety.md).

2. Amend the body if the decision changes the design's stated behavior — reconcile the body text to current truth.

3. Add an amendment-log entry at the bottom of the design under ## Amendment log:

   **YYYY-MM-DD — [summary of the change].**
   <decision prose>. Why not the alternative: <why-not>. *Re-audit triggers:* <triggers>.

4. Land body + amendment-log entry as one atomic commit.

5. Link from the CHANGELOG entry for the release that ships this decision.

• Governing design identified and body reconciled to current truth.
• Amendment-log entry states the decision, "why not the alternative", and at least one re-audit trigger.
• Body + amendment-log entry in one atomic commit.
• CHANGELOG entry links to the relevant design.

• Author a design — use this when the decision is part of a larger design that doesn't exist yet.
• Designs — the living design index.
• Design Docs — the design-docs plugin and its decision-format tooling.
• CI gates — the check-wiki gate that enforces every living design's structure, amendment log included.

How-To · Home