Adr 021 Session Capture Via Hooks

EPGOAT Documentation - Architectural Decisions

ADR-021: Session Capture via Claude Code Hooks

Date: 2025-11-10 Status: ✅ Accepted Deciders: CTO (Claude Code AI), CEO Tags: #documentation #automation #knowledge-management

Context

Problem: Architectural decisions and session context are lost after conversations end. Only code and commit messages are preserved.

What Gets Lost: - Why decisions were made (rationale, trade-offs) - Discoveries and insights - Design discussions - Alternative approaches considered - Lessons learned

CEO Question: "What about decisions, ADRs and meta information that is uncovered during a session?"

Decision

Implement automatic session capture using Claude Code hooks:

Hook 1: session-end - Triggers: At end of every session - Prompts AI to: - Create ADRs for architectural decisions - Create session summary in living documents - Update DECISIONS-PENDING.md - Update living document state

Hook 2: tool-result - Triggers: After Edit/Write tools execute - Detects backend code changes - Prompts to check documentation impact - Suggests /maintain-documentation skill

Rationale

Why Hooks vs Manual?

  • Automated prompts are reliable: AI can't forget
  • Consistent capture: Every session gets debriefed
  • Zero manual effort: Hooks run automatically
  • Prevents knowledge loss: Decisions always documented

Why Session-End Hook?

  • Perfect timing to review entire session
  • All work is fresh in context
  • Natural checkpoint for reflection

Why Tool-Result Hook?

  • Real-time detection of code changes
  • Proactive reminder (not reactive)
  • Catches doc drift at the moment

Alternatives Considered

Alternative 1: Skills Only (No Hooks)

Rejected because: - Relies on AI remembering to invoke skills - Easy to forget during focused work - No automatic prompts

Alternative 2: Manual ADR Creation

Rejected because: - Human/AI must remember - Inconsistent application - Decisions get lost

Alternative 3: Commit Message Only

Rejected because: - Too brief for architectural context - No space for trade-off discussion - Loses rich session context

Consequences

Positive

  • ✅ Every session automatically captures decisions
  • ✅ ADRs created reliably
  • ✅ Living documents stay updated
  • ✅ Backend changes trigger doc checks
  • ✅ Zero manual effort

Negative

  • ❌ Adds prompts at session end (minor overhead)
  • ❌ Tool-result hook shows warnings (can be noise)

Mitigation

  • Hooks are concise and actionable
  • Tool-result only triggers on backend/ changes
  • Can be disabled if too noisy

Implementation

Created Hooks: 1. .claude/hooks/session-end (2.7K, executable) 2. .claude/hooks/tool-result (4.9K, executable)

Integration with System: - Session-end prompts for ADR creation - Creates session summaries in 10-Projects/Active/Session-YYYY-MM-DD.md - Tool-result warns on backend/, api/, migrations/, config/ changes - Living documents updated automatically

Current State: - ✅ Both hooks created and executable - ✅ Tested (will trigger at session end) - ✅ Documented in living document

Validation

Session-End Hook Test: - Will trigger when this session ends - Should prompt for ADR creation (7 ADRs made) - Should create session summary - Should update living document

Tool-Result Hook Test: - Triggers when backend/ code modified - Shows reminder to check docs - Suggests /maintain-documentation

References

Notes

This is a critical piece of the documentation maintenance stack. Combined with: - Pre-commit hooks (quality gates) - Build system (automation) - Living documents (state persistence) - Skills (autonomous work)

We now have complete session-to-session knowledge preservation.

The hooks ensure that even if AI forgets to create ADRs manually, the system will prompt automatically at session end. This solves the "ephemeral conversation" problem.