Tracking What Went Wrong
The most valuable part of a decision graph isn't what succeeded—it's what failed and why.
As Claude reads through snowflex's git history, it doesn't just trace the happy path. It discovers the problems that forced the project to change direction. These problems are captured as observation nodes, and the direction changes are captured as revisit nodes.
Observations: Capturing Problems
Observations are facts that emerge from the codebase. They don't carry confidence scores because they aren't judgments—they're things that happened. In snowflex's case, Claude found a series of ODBC-related problems scattered across the commit history:
Each observation is a data point. Individually, they're annoyances. Together, they tell a story: the ODBC approach was slowly breaking down under the weight of accumulated issues. Session expiry, encoding bugs, platform incompatibilities, memory problems—each one required a workaround, and the workarounds were getting more fragile.
Observations get linked to the nodes they relate to. Node 15 (session expiry) connects back to the outcome of the ODBC implementation. Node 33 (accumulating limitations) connects to the earlier observations that built up the case for change.
The Pivot: ODBC to HTTP
This is the climax of the snowflex story. After two years of ODBC workarounds, the team decided to throw out the entire transport layer and rewrite it from scratch using HTTP REST APIs. In the decision graph, this is captured with a revisit node—deciduous's way of marking the moment when an old approach gets reconsidered.
The archaeology pivot command captures this entire pivot atomically:
Linked: 32 → 33 → 34 → 36
Marked node 32 as superseded
The Revisit Node
Revisit nodes are deciduous's way of capturing pivot points. They sit at the junction between an old approach that stopped working and a new approach that replaced it. The pattern is always the same:
[Old Outcome] → [Observation: why it failed] → [REVISIT] → [New Decision]
In snowflex's case:
- Old Outcome (node 32): The ODBC-based approach was working, but with increasing friction
- Observation (node 33): "ODBC limitations accumulating — auth expiry, encoding, Apple Silicon, memory"
- Revisit (node 34): "Reconsider ODBC as transport — switch to HTTP REST API"
- New Decision (node 36): "How to replace ODBC transport for v1.0?"
This chain is what makes the graph useful for understanding evolution, not just current state. Anyone querying the graph in the future can trace exactly why ODBC was abandoned and what drove the decision to switch to HTTP.
archaeology pivot is the most powerful command for retroactive history. It creates an observation, a revisit, and a new decision, links them all together, and marks the old approach as superseded—all in one atomic operation. Without it, you'd need to run deciduous add three times, deciduous link three times, and deciduous status once.
Statuses
Every node in the graph has a status that reflects where it stands. As Claude builds the snowflex graph, it marks nodes appropriately:
The full set of statuses:
| Status | Meaning | Example from Snowflex |
|---|---|---|
pending |
Not yet resolved | A goal that's still being worked toward |
active |
Current truth — this is how things work now | The HTTP transport approach (node 37) |
completed |
Done and working | The v1.0 rewrite action (node 39) |
superseded |
Replaced by a newer approach | The ODBC-based outcome (node 32) after the pivot |
abandoned |
Tried and given up on | An approach that was started but never finished |
rejected |
Considered but not chosen | "Direct HTTP client without transport abstraction" (node 38) |
Statuses make the graph queryable by intent. You can ask "show me only active nodes" to see the current design, or "show me superseded nodes" to find every pivot point in the project's history.