Decision nodes lack visible alternatives — diamond shape claims branching the edges don't back up

[bobthearsonist]

Observation

The extraction prompt's heuristic 5 defines decision as "A choice resolved, discovery, design point, tradeoff." The shape (diamond) visually signals a branch point. But the prompt never asks Claude to represent the considered alternatives — so decision nodes in real extracted graphs typically look like single-path sinks or pass-throughs, just with a different shape.

A diamond surrounded by one incoming + one outgoing edge tells the reader "a decision happened here" but not "here are the paths that were weighed." That's a visual claim the edges don't back up.

Concrete example — today's overview (2026-05-18)

From 0 Daily ADHD Brain Logs/20260518-overview.json, decision nodes and their actual edges:

Decision node	Incoming edges	Outgoing edges
mcpx-permissions-gate	(none)	motivates → gateway-readmes, weak parallel to → agentgateway-dns-cascade
agentgateway-dns-cascade	weak parallel to ← mcpx-permissions-gate	surfaces → rfc-1035-underscores, motivates → gateway-readmes
cost-bug-fix	discovers ← claude-statusline-overhaul	(none)
rfc-1035-underscores	surfaces ← agentgateway-dns-cascade	(none)
ccstatusline-evaluation	evaluates ← claude-statusline-overhaul	(none)

None of these have alternative paths. cost-bug-fix is a discovery, rfc-1035-underscores is a surfaced gotcha, ccstatusline-evaluation is parked — all single-arrow recordings of "what happened," not branched representations of "what was considered vs. chosen."

Visually compare against the proposed-style preview from #21's design (docs/superpowers/specs/samples/2026-05-18-issue-21-proposed-style.html) — even with improved styling and layout, the diamonds remain semantically thin.

This pattern is not new with the plugin path — the legacy hook output has the same shape. From 20260515-overview.json: lock-toctou (decision, "chosen") and atomic-filter (decision, "stashed") are the two halves of a real branching decision, but they appear as separate decision nodes joined by a rolled back from edge, not as one branch point with two outcomes. So this is prompt-shaped, not plugin-shaped.

Hypotheses for root cause

1. Heuristic 5's definition is too broad. Lumping "choice resolved", "discovery", and "tradeoff" under one type makes most nodes Claude tags as decision fall into the discovery/tradeoff buckets, which are naturally single-path.
2. No explicit ask for alternatives. The prompt asks for "EXACTLY ONE shape per node" but never says "if you tag something as decision, emit edges to the alternatives that were considered as well as the path chosen."
3. Schema has no slot for considered-but-rejected alternatives. Even if Claude wanted to emit them, there's no convention for "this alternative was weighed but not taken" — they'd just look like equal-weight outgoing edges, indistinguishable from the chosen path.

Candidate fixes (not exhaustive)

Option A: Tighten the type definition

Restrict decision to branching choices (two or more alternatives considered, one chosen). Move "discovery", "surfaced gotcha", and "tradeoff observation" to a new type or fold into context with a decision status.

Option B: Require alternative-path edges on decisions

Add a heuristic: "If a node is a decision, emit at least one edge to each alternative considered, using a weak-edge or new rejected-edge class for the path not taken." Forces decisions to look branched.

Option C: Schema addition for alternatives

Add an optional data.alternatives: string[] array to decision nodes. Renderer draws each alternative as a small ghost branch off the diamond — visually present but de-emphasized vs. the taken path.

Option D: Split decision into two types

• branch (true choice point with alternatives) → diamond shape, requires multiple paths
• discovery (single-arrow finding/realization) → maybe a different shape (octagon? note-shape?)

Option A is least invasive (prompt + worked examples updated). B adds a new edge class. C touches schema. D touches schema and renderer styling.

Out of scope (for this issue and any specific fix)

• This is not blocking Improve plugin visual generation to match legacy hook-rendered boards #21 (visual fidelity pass). Touches prompts/extract-graph.md and possibly shared/schema.json, not layout.ts / renderer.ts.
• This is not a regression — pattern has existed since the legacy hook path. Filing as observation for future prompt engineering.

References

• Extraction prompt heuristic 5: plugins/obsidian-plugin/prompts/extract-graph.md lines 88-107
• Today's overview as example: 0 Daily ADHD Brain Logs/20260518-overview.json
• Issue Improve plugin visual generation to match legacy hook-rendered boards #21 design + proposed-style preview: docs/superpowers/specs/2026-05-18-issue-21-visual-fidelity-design.md