decision-trace

Decision Trace

Every non-trivial edit should be recorded in ~/.fd-plan/<slug>/.codebase/DECISIONS.jsonl. This creates an append-only audit trail that makes code review and debugging faster.

When to Record a Decision

Record when:

• Editing a file that affects behavior (not just formatting/comments)
• Choosing between two or more implementation approaches
• Making an assumption about a requirement
• Fixing a bug or regression
• Changing an API contract or schema

How to Record

Use the decision-trace tool:

{
  "action": "record",
  "entry": {
    "id": "auth-refactor-2024-05-01",
    "file_path": "src/services/auth.ts",
    "change_type": "edit",
    "rationale": "Refactored token validation to use constant-time comparison to prevent timing attacks",
    "evidence": [
      "OWASP: timing attacks on string comparison",
      "Prior failure: auth-timing-2024-03 in FAILURES.json"
    ],
    "assumptions": [
      "Token format remains base64-encoded JWT",
      "Redis cache is available for token blacklist"
    ],
    "alternatives_considered": [
      "Keep string comparison (rejected: timing attack risk)",
      "Move validation to edge (rejected: adds latency)"
    ],
    "risk_level": "medium",
    "agent": "backend-coder"
  }
}

Automatic Recording

The decision-trace-hook auto-records a minimal entry for every write/edit. The full entry (with rationale, evidence, assumptions) should be added by the agent explicitly using the tool above.

Querying Decisions

// Get all decisions for a file
{ "action": "get_for_file", "file_path": "src/services/auth.ts" }

// Get all high-risk decisions
{ "action": "query", "query": { "risk_level": "high", "limit": 10 } }

Decision Evolution

Decisions are not static. They change as requirements shift, new evidence appears, or better alternatives emerge. Track the full lifecycle:

alternatives_considered

List every option evaluated and why it was rejected or accepted. This prevents re-litigating old choices.