My Decision Log

Decision Log

Track session decisions, rationale, and consequences.

⚡ Quick Start

Making a decision with trade-offs? → Log it. Future you (or another agent) will thank you.

User asks "why did we do X?" → Check the decision log. If missing, reconstruct and log it.

What to Log

Log decisions that meet any of these criteria:

Skip trivial decisions:

• Variable naming
• Formatting choices
• Standard library usage
• Obvious fixes

Decision Convention

Establish a lightweight convention for logging decisions. Use the Session Decision Card format for most in-session decisions, and the Full ADR format only for hard-to-reverse architectural choices.

Session Decision Card (default)

For in-session decisions that are important but not architectural:

**Decision:** <One-line choice>
**Context:** <2-3 sentence problem statement>
**Rationale:** <Why this choice over alternatives>
**Consequences:** <What this enables or constrains>

Where to store:

• Inline in session chat (first) — for immediate context
• memex_retro card (second) — for cross-session recall
• Skill update if it affects agent behavior

Full Decision Log (for hard-to-reverse choices)

Each decision entry:

## <Decision Title>

**Date:** YYYY-MM-DD
**Context:** <What problem we were solving>
**Decision:** <What we chose>
**Alternatives considered:** <What we rejected and why>
**Rationale:** <Why this choice wins>
**Consequences:** <What this enables or constrains>
**Reversibility:** <Easy / Medium / Hard>
**Related:** <Links to ADRs, skills, memex cards>

Where to store:

• docs/adr/ for architectural decisions
• CONTEXT.md for domain terminology changes
• Relevant SKILL.md for behavioral decisions

When to Use Which Format

Logging Discipline

Log immediately. Don't wait until the end of the session. The moment a decision with trade-offs is made, log it:

1. First: State it in the chat — "Decision: using X instead of Y because Z."
2. Second: If cross-session value, call memex_retro with a Decision card
3. Third: If architectural, create/update the ADR file

Never batch decision logging. Log as decisions happen, or they get lost in context compaction.

Where to Store

Decision Lifecycle

Decision made
├── Log immediately → session memory
├── If cross-session → memex_retro
├── If architectural → ADR
├── If domain term → CONTEXT.md
└── If behavioral → update relevant SKILL.md

Retrospective Decision Recovery

When a decision wasn't logged and the user asks about it later:

1. Reconstruct from git history — git log, commits, PRs
2. Reconstruct from session memory — ctx_search for related terms
3. Ask user for confirmation — "My reconstruction: we chose X because Y. Is that right?"
4. Log the recovered decision — prevent future ambiguity

Common Decision Triggers

Agents should proactively log decisions when these situations arise:

Rule of thumb: If you pause to think "which option is better?" — log the decision.

Examples

Good: Tool choice decision

## Use yaml package for config parsing

**Date:** 2026-05-20
**Context:** Need to parse event-horizon instances.yaml in pi-event-horizon-provider
**Decision:** Use `yaml` npm package
**Alternatives considered:**
- js-yaml — popular but no anchor/comment support needed
- Native JSON.parse — instances.yaml uses YAML features
**Rationale:** yaml package handles full YAML spec including quoted strings, anchors, comments. Matches user's existing yaml files.
**Consequences:** Adds one dependency. Future configs can use advanced YAML features.
**Reversibility:** Easy — swap parser if needed

Good: Architecture decision

## Split my-workflow into 3 composable skills

**Date:** 2026-05-26
**Context:** my-workflow v1.6 was 490 lines, approaching 500-line limit. Adding 6 new sections would bloat it.
**Decision:** Extract VCS content to my-vcs-hygiene and lifecycle content to my-project-lifecycle
**Alternatives considered:**
- Keep monolithic — simpler but 620+ lines hurts triggering
- Split into 5+ skills — too granular, hard to discover
**Rationale:** Three skills with distinct triggers (orchestration, VCS, lifecycle) matches skill-separation-of-concerns principle. Each < 360 lines.
**Consequences:** All AGENTS.md files need reference updates. Users must learn 3 skill names.
**Reversibility:** Medium — can merge back but loses trigger precision
**Related:** ADR in agents repo, memex card skill-composability-workflow-split

Bad: Unlogged decision

Agent chose setWidget over notify for UI without logging why. Future agent tries notify, wastes time debugging. ❌ Always log non-obvious choices.

Common Mistakes

❌ Wrong: Logging every tiny choice — noise drowns signal ✅ Right: Log only decisions with trade-offs, reversibility concerns, or future impact

❌ Wrong: Logging only in session chat — lost after compaction ✅ Right: Persistent storage: memex for cross-session, ADR for architecture

❌ Wrong: Reconstructing decisions from memory without verification ✅ Right: Reconstruct, then confirm with user or git history

Related Skills

• @skills/my-project-lifecycle — Document phase produces ADRs and CONTEXT.md
• @skills/my-session-retrospective — Assesses whether key decisions were logged
• @skills/grill-with-docs — Produces ADRs for hard-to-reverse decisions

Versioning

• Last updated: 2026-05-26
• Version: 1.1
• Update notes: Added Decision Convention with Session Decision Card and Full Decision Log formats, plus Common Decision Triggers section based on retrospective finding that decision logging was the weakest skill (5–15% adherence).