[FEATURE] Decision History Tracking with DECISIONS.md

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Add a decision tracking system that preserves the reasoning behind code decisions, including paths not taken and backtracked approaches. This captures the "why" of development that git history alone cannot preserve.

Problem Statement

When using Claude Code for AI-assisted development, valuable context is systematically lost:

1. Decision rationale disappears — Git tracks what changed, but not why this approach instead of that one. When Claude presents options A, B, and C, and we choose B, the reasoning for rejecting A and C evaporates.

1. Backtrack patterns are invisible — When we try approach X, hit a wall, and pivot to Y, that hard-won knowledge isn't captured anywhere. Future sessions (or future developers) may repeat the same dead-end exploration.

1. Solo developer context gap — Teams naturally create decision artifacts through Slack threads, PR discussions, and meeting notes. Solo developers using Claude Code don't have that—the conversation is the design meeting, and it evaporates when context clears.

1. Cross-session continuity — Each new Claude session starts fresh. Without explicit documentation, previous explorations and their outcomes are lost.

Proposed Solution

Core Mechanism

Introduce a DECISIONS.md file that Claude proactively maintains during development sessions. This file:

• Tracks decisions made, alternatives considered, and paths rejected
• Documents backtracked approaches and the reasons they failed
• Persists across Claude sessions within a commit cycle
• Gets committed alongside code changes, then resets for the next commit

Suggested Format

A hybrid structure optimized for both LLM parsing and human readability:

================================================================================
[DECISION] AUTH-001 | ACTIVE | 2024-01-15 14:30
Token Storage Strategy
================================================================================

### Context
Building auth for the mobile + web app. Need stateless approach for API 
compatibility. User wants to avoid server-side session management.

### Decided
Secure device storage (Keychain on iOS, EncryptedSharedPrefs on Android), 
with in-memory only for web client.

### Alternatives Explored

~~[REJECTED] httpOnly cookies~~
Initially seemed ideal for web security. Hit CORS issues when testing 
mobile webview context. Would require different auth flows per platform.

~~[REJECTED] localStorage~~
Security concerns raised—XSS vulnerable. Ruled out quickly.

### Open Questions
- Need to revisit web storage if we add PWA support later


================================================================================
[DECISION] AUTH-002 | BACKTRACKED | 2024-01-15 16:45
Refresh Token Rotation
================================================================================

### Context
Implementing token refresh logic. Security best practice suggests rotating 
refresh tokens on each use.

### Original Approach
Rotate refresh token on every use, invalidate old token immediately.

### What Went Wrong
Race condition: concurrent API calls could both try to refresh simultaneously.
First one succeeds, second gets invalid token error, logs user out.
Discovered this during testing with poor network conditions.

### Revised Approach
Rotate only on expiry, with a grace window for concurrent requests.

### Lessons Learned
Aggressive rotation sounds good on paper but breaks in real-world concurrency.


================================================================================
[DECISION] DB-001 | EXPLORING | 2024-01-15 17:30  
Message Queue Architecture
================================================================================

### Context
Need to handle async notifications. Discussing options.

### Options Under Consideration

**Option A: Supabase Realtime + Edge Functions**
Pros: Already in our stack, simple
Cons: Uncertain scaling characteristics, vendor lock-in

**Option B: Dedicated queue (BullMQ + Redis)**
Pros: Battle-tested, flexible
Cons: Another service to manage, overkill for current scale?

### Current Thinking
Leaning toward Option A for MVP, with abstraction layer to swap later.

---
Waiting on: User decision after pricing review
---

================================================================================

Key Format Features

| Element | Pattern | Purpose |
|---------|---------|---------|
| Decision boundary | ====...==== | Easy document splitting |
| Header line | [DECISION] ID \| STATUS \| TIMESTAMP | Regex-friendly metadata |
| Status values | ACTIVE, REJECTED, BACKTRACKED, EXPLORING | Finite set for filtering |
| Rejected alternatives | ~~[REJECTED] name~~ | Visual + parseable |
| Blockers | ---\nWaiting on:...\n--- | Quick extraction |

Lifecycle

1. During development: Claude proactively maintains DECISIONS.md, updating it as decisions are made, alternatives explored, or approaches backtracked
2. At commit time:

• Full DECISIONS.md is committed with the code
• Commit message includes a summary of key decisions

1. After commit: DECISIONS.md resets for the next unit of work
2. Historical review: Walk git history to see decision evolution across commits

Implementation Considerations

Historian Agent Pattern

To avoid cluttering the main coding context, consider spawning a specialized "historian" sub-agent that:

• Receives "decision events" from the main coding agent
• Detects when the main agent is backtracking and prompts for reasoning
• Periodically surfaces summaries for user review/correction
• Generates commit message summaries at commit time

This keeps the primary context focused on coding while ensuring decision capture happens reliably.

User Interaction Points

Claude should occasionally check in with the user:

• When alternatives are being considered: "I'm tracking these options—anything to add?"
• When backtracking: "Logging that X didn't work because of Y—accurate?"
• Before commit: "Here's the decision summary for the commit message—look right?"

Benefits

1. Reduced repeated mistakes — "We tried that in commit abc123, it failed because..."
2. Better onboarding — New developers (or future Claude sessions) understand why the code is structured this way
3. Improved commit messages — Structured decision data enables richer, more informative commits
4. Solo developer parity — Solo devs get the decision documentation that teams get naturally
5. LLM context optimization — Structured format makes it easy for Claude to quickly parse and apply historical decisions

Alternative Solutions

Rolling project-level DECISIONS.md

• Pro: Single source of truth
• Con: Unbounded growth, harder to scope to relevant context
• Rejected in favor of per-commit snapshots with git history providing the long view

Unstructured narrative logs

• Pro: More natural to write
• Con: Harder for LLMs to parse reliably, difficult to extract status at a glance
• Rejected in favor of hybrid structured + narrative format

Priority

Medium - Would be very helpful

Feature Category

Other

Use Case Example

1. I'm a solo developer building an iOS app with a Supabase backend. I ask Claude to help me implement user authentication.

1. Claude presents three options: (A) Supabase Auth with magic links, (B) Supabase Auth with OAuth providers, (C) custom JWT implementation. We discuss trade-offs and I choose Option B.

1. During implementation, we hit a wall—OAuth redirect URLs don't work cleanly with iOS deep links. Claude and I backtrack and pivot to Option A (magic links) instead.

1. I commit the working auth implementation. Two weeks later, a new team member asks "why didn't we use OAuth?" or I myself forget why we made that choice.

1. Without this feature: The reasoning is lost. I might waste hours re-exploring OAuth only to hit the same wall, or I can't explain the decision to my teammate.

1. With this feature: The committed DECISIONS.md shows:

• AUTH-001 | BACKTRACKED | OAuth approach rejected due to iOS deep link complications
• AUTH-002 | ACTIVE | Magic links chosen as simpler alternative

The full context is preserved in git history. Future Claude sessions can read this and avoid suggesting OAuth again for this project.

1. This saves me time by preventing repeated exploration of dead ends, and helps maintain project knowledge even as a solo developer without a team to document decisions naturally.

Additional Context

This feature aligns with Claude Code's existing strengths in git workflow management and would complement the current /commit and PR creation capabilities. The decision log could integrate naturally with these existing workflows.

Related Issues

This proposal is related to but distinct from several existing feature requests:

| Issue | Focus | How This Proposal Differs |
|-------|-------|---------------------------|
| #1813 - Background Worker for Memory and Docs | Auto-updating READMEs, general project memory | This proposal specifically tracks decision rationale, alternatives rejected, and backtracked paths—not general documentation |
| #10654 - Explicit Memory via "Remember" Directives | User-commanded persistence ("remember we can't use X") | This proposal is proactive/automatic and captures the full decision context, not just user-flagged items |
| #11455 - Session Handoff/Continuity | Pending tasks between sessions | This proposal captures why decisions were made, not just what's left to do |
| #209 - Markdown Conversation History | Raw conversation logging (like Aider) | This proposal is structured, decision-focused, and git-integrated rather than raw transcript |
| #14227 - Persistent Memory Between Sessions | General memory/preferences | This proposal is commit-scoped with a specific format optimized for decision tracking |
| #9306 - Project-Local Conversation History | Storing conversation history in project directory | This proposal extracts and structures decisions rather than storing raw conversations |

Key differentiators of this proposal:

1. Structured format optimized for LLM parsing with explicit delimiters
2. Decision lifecycle states (ACTIVE, REJECTED, BACKTRACKED, EXPLORING)
3. Per-commit scope that resets after each commit, with git history providing the long view
4. Explicit tracking of paths not taken—the alternatives considered and why they were rejected
5. Backtrack documentation—capturing what went wrong when an approach failed

The existing feature-dev plugin demonstrates Claude presenting multiple architecture approaches within a session, but that context doesn't persist to git history. This proposal bridges that gap.