View execution trace - see what AI did, why, and alternatives considered
Views detailed execution trace showing AI decisions, reasoning, and alternatives considered.
/plugin marketplace add ialameh/sift-coder/plugin install ialameh-siftcoder@ialameh/sift-coder--live|--session|--exportView a detailed trace of what siftcoder did, why it made certain decisions, and what alternatives it considered.
/siftcoder:trace - Show trace for current session
/siftcoder:trace --live - Enable live tracing (verbose mode)
/siftcoder:trace --session <id> - View trace from past session
/siftcoder:trace --export - Export trace to file
/siftcoder:trace --last <n> - Show last N decisions
/siftcoder:trace --filter <type> - Filter by decision type
Read from .claude/siftcoder-state/trace.jsonl and display:
╔══════════════════════════════════════════════════════════════╗
║ EXECUTION TRACE ║
║ Session: 2026-01-12 14:30 ║
╚══════════════════════════════════════════════════════════════╝
Duration: 45 minutes | Decisions: 28 | Files touched: 12
───────────────────────────────────────────────────────────────
TIMELINE
───────────────────────────────────────────────────────────────
14:30:00 ┃ SESSION START
┃ Mode: build | Spec: FEATURE_IDEAS.md
┃
14:30:15 ┃ DECISION: Feature prioritization
┃ ├─ Chose: Start with heal.md (P0, medium effort)
┃ ├─ Alternatives considered:
┃ │ - checkpoint.md (P0, medium) - similar priority
┃ │ - swarm.md (P0, high) - too complex for first
┃ └─ Reasoning: Foundation feature, enables other P0s
┃
14:32:00 ┃ DECISION: File structure
┃ ├─ Chose: Create commands/heal.md
┃ ├─ Pattern matched: Existing command structure
┃ └─ Reasoning: Follows established plugin conventions
┃
14:35:00 ┃ ACTION: Write file
┃ ├─ File: siftcoder/commands/heal.md
┃ ├─ Lines: 285
┃ └─ Content: Self-healing loop command
┃
14:40:00 ┃ DECISION: Error parsing strategy
┃ ├─ Chose: Regex-based with fallback to LLM parsing
┃ ├─ Alternatives:
┃ │ - Pure LLM parsing (slower, more accurate)
┃ │ - AST-based parsing (complex, language-specific)
┃ └─ Reasoning: Balance of speed and accuracy
┃
14:45:00 ┃ DECISION: Max retries default
┃ ├─ Chose: 3 retries
┃ ├─ Alternatives: 5 (too many), 1 (too few)
┃ └─ Reasoning: Industry standard, prevents infinite loops
┃
14:50:00 ┃ ACTION: Write file
┃ ├─ File: siftcoder/commands/checkpoint.md
┃ ├─ Lines: 312
┃ └─ Content: Save/restore checkpoint command
┃
15:00:00 ┃ DECISION: Checkpoint storage format
┃ ├─ Chose: JSON with git stash integration
┃ ├─ Alternatives:
┃ │ - Git commits (too heavy)
┃ │ - File copies (no git awareness)
┃ └─ Reasoning: Lightweight + git state preservation
┃
15:10:00 ┃ QA CHECK
┃ ├─ Status: Passed
┃ ├─ Criteria checked: 6/6
┃ └─ Issues: None
┃
15:15:00 ┃ SESSION END
┃ Completed: 4 features | Time: 45min
───────────────────────────────────────────────────────────────
SUMMARY
───────────────────────────────────────────────────────────────
Decisions by type:
Architecture: 3
Implementation: 8
Prioritization: 2
Error handling: 5
Other: 10
Files created: 4
Files modified: 2
Tests passed: 12/12
Healing attempts: 0
--liveEnable real-time trace output during execution:
LIVE TRACE ENABLED
All decisions will be logged in real-time.
This may slow down execution slightly.
Output: .claude/siftcoder-state/trace.jsonl
[14:30:15] Considering feature order...
Options: heal (P0), checkpoint (P0), swarm (P0)
Selecting: heal.md
Reason: Foundation feature
[14:32:00] Creating file: commands/heal.md
Pattern: command-template
Lines: ~280 estimated
[14:35:00] Writing heal.md...
Progress: 100%
Duration: 3m
--filter <type>Filter trace by decision type:
/siftcoder:trace --filter architecture
ARCHITECTURE DECISIONS
[14:32:00] File structure decision
├─ Chose: Create commands/heal.md
├─ Pattern: Existing command structure in siftcoder/commands/
└─ Reasoning: Maintains consistency with plugin conventions
[15:00:00] Checkpoint storage format
├─ Chose: JSON + git stash integration
├─ Alternatives rejected:
│ - Git commits: Too heavy, clutters history
│ - File copies: Loses git state awareness
└─ Reasoning: Lightweight storage with full git state
[15:20:00] State persistence layer
├─ Chose: JSONL for append-only logs
├─ Pattern: Implementation log pattern
└─ Reasoning: Efficient appends, easy to read/parse
--exportExport trace to file for post-mortem:
/siftcoder:trace --export
EXPORTING TRACE
Session: 2026-01-12 14:30
Duration: 45 minutes
Entries: 28
Exporting to:
.claude/siftcoder-state/traces/trace-2026-01-12-1430.md
.claude/siftcoder-state/traces/trace-2026-01-12-1430.json
Export complete.
View markdown:
cat .claude/siftcoder-state/traces/trace-2026-01-12-1430.md
Each trace entry in trace.jsonl:
{
"timestamp": "2026-01-12T14:35:00Z",
"type": "decision",
"category": "architecture",
"summary": "File structure for heal.md",
"chosen": {
"option": "Create commands/heal.md",
"reasoning": "Follows established plugin conventions"
},
"alternatives": [
{
"option": "Create skills/heal/SKILL.md",
"rejected_reason": "Commands are simpler for single-file features"
}
],
"context": {
"task": "feat-heal",
"subtask": 1,
"files_touched": ["commands/heal.md"]
}
}
| Category | Description | Examples |
|---|---|---|
architecture | Structural decisions | File layout, patterns, abstractions |
implementation | Code-level choices | Algorithm, library, syntax |
prioritization | Order of work | Feature order, subtask sequence |
error_handling | Failure responses | Retry strategy, fallback |
optimization | Performance choices | Caching, batching |
integration | External connections | APIs, services, tools |
Configure trace verbosity in config:
{
"trace": {
"level": "decisions", // minimal | decisions | verbose | debug
"persist": true, // Save to trace.jsonl
"maxEntries": 1000, // Rolling log size
"exportFormat": "both" // md | json | both
}
}
| Level | What's Logged |
|---|---|
minimal | Only major decisions and errors |
decisions | All decisions with reasoning (default) |
verbose | + File operations, tool calls |
debug | + Internal state, alternatives |
/siftcoder:explain/siftcoder:explain "why did you use a factory pattern in auth?"
Uses trace to find the relevant decision and explain:
DECISION FOUND IN TRACE
Timestamp: 2026-01-12 14:42:00
Context: Building auth module
Decision: Use factory pattern for session creation
Reasoning:
1. Multiple session types needed (JWT, Cookie, API Key)
2. Pattern exists in src/services/email.ts
3. Allows easy extension for new session types
Alternatives considered:
- Direct instantiation: Less flexible
- Builder pattern: Overkill for this use case
Related trace entries:
[14:40:00] Session type analysis
[14:44:00] Factory implementation
/siftcoder:healTrace records each healing attempt:
[15:30:00] HEAL ATTEMPT 1/3
├─ Error: TypeError in src/auth/login.ts:42
├─ Analysis: Missing property on Session type
├─ Fix applied: Added 'user' to Session interface
└─ Result: Still failing (new error)
[15:31:00] HEAL ATTEMPT 2/3
├─ Error: TypeError in src/auth/login.ts:58
├─ Analysis: String/number mismatch
├─ Fix applied: Added parseInt() wrapper
└─ Result: Success
USING TRACES EFFECTIVELY
For debugging:
/siftcoder:trace --last 10 - Recent decisions
/siftcoder:trace --filter error_handling
For learning:
/siftcoder:trace --live - Watch in real-time
/siftcoder:explain <question> - Ask about decisions
For post-mortems:
/siftcoder:trace --export - Full session export
Compare traces across sessions
For optimization:
Look for repeated alternatives
Identify decision bottlenecks
Find patterns that slow down
Trace storage:
Traces are kept for 7 days by default
/siftcoder:trace clean --older-than 7d