Decision Trace

The Scenario

A decision trace produced by spec-writer@2.1.0 for the payment retry feature from Example 13.2. This is what gets recorded for every invocation, durably, available for replay and audit.

decision_trace:
  trace_id: 7f3b9c4e-1a2d-4e5f-9876-abc123def456
  input_hash: sha256:abc123def456789...
  versions: { kernel: 0.3.0, capability: spec-writer@2.1.0 }
  cell: { id: payments-core }

  butler_decision: { outcome: HITL, score: 0.16 }

  human_intervention:
    reviewer: alice@example.com
    review_duration_ms: 245470
    review_decision: accepted_with_modifications
    modifications:
      - added 2 acceptance criteria for retry budget exhaustion
      - added risk regarding idempotency keys

  tool_invocations:
    - { tool: read_codebase, duration_ms: 230, cost_usd: 0 }
    - { tool: query_existing_specs, duration_ms: 180, cost_usd: 0 }
    - { tool: read_ticket_descriptions, duration_ms: 95, cost_usd: 0 }

  output:
    value: blob://outputs/2026/05/16/abc123-output.yaml
    confidence:
      overall_confidence: 0.82
      sources: [input_familiarity: 0.91, tool_reliability: 0.95, domain_coverage: 0.55]

  resource_consumption:
    tokens_in: 8423
    tokens_out: 2145
    cost_usd: 0.087
    context_efficiency_actual: 0.67

  outcome: { succeeded: true, human_intervention: true }
  retention: { policy: standard_seven_year, earliest_deletion: 2033-05-16 }

What This Trace Enables

• Replay — given the input_hash and versions, the invocation can be replayed; deterministic agents reproduce the same output.
• Audit — every tool invocation is recorded with duration and cost; contested decisions are resolved with evidence.
• Cost Attribution — this invocation cost $0.087, attributable to the cell, the capability, and the user.
• Confidence Calibration — overall_confidence 0.82 + outcome accepted_with_modifications is one data point the Inspector analyzes for drift (see Example 13.3).
• Human Intervention Recording — the trace shows Alice reviewed for 245 seconds and made specific modifications: review evidence, not just attestation.

What This Trace Does NOT Contain

By design, the full input, output, reasoning chain, and ticket content are referenced by hash or blob URI, dereferenceable only with permission. The trace records structure and metadata; the content lives in referenced storage with access control. This is the privacy boundary that makes scaled pattern detection compatible with sensitive content.