Skip to main content

Knowledge > Runbooks > Agent Ops > How to Update the Decision Log

How to Update the Decision Log

Document significant decisions, course changes, and key learnings in the shared decision journal so future agents and the founder have institutional memory.

Why This Matters​

ChurchWiseAI is a solo-founder operation with multiple concurrent Claude agents. Without a decision log, the same mistakes get made repeatedly and the same decisions get relitigated. The log is how context survives across sessions.

The File​

C:\dev\DECISION_LOG.md — append-only. Never edit previous entries.

When to Update​

Append an entry when you:

TriggerExample
Architecture changeSwitched from Railway to LiveKit Cloud for voice
Technology choiceChose isomorphic-dompurify over jsdom for sanitization (then found it fails — documented that too)
Feature added or removedAdded trial_will_end webhook handler to all 3 codebases
Problem encountered + course changeDiscovered chatbot was using 261K church count; fixed filter
Surprising system behaviorCartesia SDK 0.2.4 has a known crash with the wrapper
Founder expressed a clear preferenceJohn said never to suggest stopping a session
Security or data incidentRotated service role key after suspected exposure
Pricing or policy decisionDecided voice plans will not have annual billing due to per-minute cost variability

Do NOT add entries for:

  • Routine bug fixes with no architectural significance
  • Minor UI changes
  • Updating a knowledge doc (that's tracked by git)

Format​

- YYYY-MM-DD: What happened and WHY. Keep to 1-2 lines max.

Rules:

  • Use absolute dates — never "today", "yesterday", "last Thursday"
  • Write what happened AND the reasoning — "WHY" is the part that decays without documentation
  • Keep it brief — 1-2 lines max per entry
  • Use past tense: "Switched", "Found", "Decided", "Rotated"

How to Append​

Read the file first to understand the current format and find the end, then append:

# Check the current end of the file
tail -20 /c/dev/DECISION_LOG.md

# Then append (using the Edit tool is preferred — never overwrite the file)

Use the Edit tool to append to the bottom of the file. Never use a write tool that overwrites the whole file — you would destroy previous entries.

Example entry:

- 2026-03-25: Switched chatbot primary LLM from gpt-4o-mini to Claude Haiku 4.5 — better theological reasoning and consistent with the brand narrative of being Anthropic-native.

Entries Written By Agents​

Agents should sign their entries when the context is useful:

- 2026-03-25: [Agent: knowledge-expansion] Added 29 runbook files to knowledge/runbooks/ — covers technical-ops, agent-ops, and business-ops.

This is optional but helpful when the log shows a burst of related entries from a multi-file task.

Do Not Edit Previous Entries​

The decision log is append-only. If a previous decision turned out to be wrong, add a new entry explaining the course correction:

# DO THIS:
- 2026-03-25: Reverted the jsdom sanitizer added on 2026-03-10 — discovered it crashes in Vercel serverless (see feedback_dompurify_serverless.md). Now using blocklist sanitizer instead.

# NOT THIS: (editing the old entry)

Verification​

  • The entry appears at the bottom of DECISION_LOG.md
  • The date is correct (today's date: 2026-03-25)
  • The entry explains WHAT happened AND WHY
  • Previous entries are unchanged

See Also​