/reasoning-graph

Reasoning Graph Generation

> Reference for: Common Ground > Load when: Using --graph flag, generating mermaid diagrams

---

Purpose

The reasoning graph makes Claude's decision-making structure visible—not just the assumptions (premises), but the decision tree that led to the current approach.

**Two complementary artifacts:**

• `COMMON-GROUND.md` = the premises (what we're assuming)
• Reasoning graph = the structure (how decisions connect)

---

Mermaid Diagram Structure

Basic Template

flowchart TD
    %% Root node: the task/goal
    ROOT[Task: {task_description}]

    %% Decision points: diamond shape
    ROOT --> D1{Decision Question?}

    %% Branches with weights and source tags
    D1 -->|"weight: 0.8 [inferred]"| P1[Chosen Path]
    D1 -->|"weight: 0.2 [alternative]"| P2[Alternative Path]

    %% Downstream decisions
    P1 --> D2{Next Decision?}

    %% Leaf nodes: concrete implementations
    D2 --> I1[Implementation Detail]

    %% Styling
    style D1 fill:#ffcc00,stroke:#333
    style P1 fill:#90EE90,stroke:#333
    style P2 fill:#cccccc,stroke:#333

---

Node Types

| Node Type | Shape | Color | Mermaid Syntax | Meaning | |-----------|-------|-------|----------------|---------| | Task/Goal | Rectangle | Default | `ROOT[Task: ...]` | Root of reasoning tree | | Decision Point | Diamond | Yellow `#ffcc00` | `D1{Question?}` | Fork requiring choice | | Chosen Path | Rectangle | Green `#90EE90` | `P1[Path Name]` | High confidence, taken | | Alternative | Rectangle | Gray `#cccccc` | `P2[Alternative]` | Considered but not taken | | Uncertain | Rectangle | Orange `#FFB366` | `U1[Uncertain]` | Low confidence, needs clarification | | Implementation | Rectangle | Blue `#87CEEB` | `I1[Detail]` | Concrete decision/action |

---

Styling Rules

Apply styles after all node definitions:

%% Decision points: yellow
style D1 fill:#ffcc00,stroke:#333
style D2 fill:#ffcc00,stroke:#333

%% Chosen paths: green
style P1 fill:#90EE90,stroke:#333

%% Alternatives: gray
style P2 fill:#cccccc,stroke:#333

%% Uncertain: orange
style U1 fill:#FFB366,stroke:#333

%% Implementations: blue
style I1 fill:#87CEEB,stroke:#333
style I2 fill:#87CEEB,stroke:#333

---

Edge Labels

Include weight and source tag on edges where relevant:

D1 -->|"weight: 0.8 [stated]"| P1
D1 -->|"weight: 0.5 [inferred]"| P2
D1 -->|"[uncertain]"| U1
D1 -->|"[alternative]"| A1

Source Tags

| Tag | Meaning | Typical Weight | |-----|---------|----------------| | `[stated]` | User explicitly said this | 0.8 - 1.0 | | `[inferred]` | Derived from code/config | 0.6 - 0.8 | | `[assumed]` | Best practice default | 0.5 - 0.7 | | `[uncertain]` | Needs clarification | 0.2 - 0.5 | | `[alternative]` | Considered but not taken | 0.1 - 0.3 |

---

Node Naming Conventions

IDs

Use consistent prefixes:

| Prefix | Meaning | Example | |--------|---------|---------| | `ROOT` | Root task | `ROOT[Task: Build auth]` | | `D{n}` | Decision point | `D1{MVP or Production?}` | | `P{n}` | Chosen path | `P1[Production-grade]` | | `A{n}` | Alternative | `A1[MVP approach]` | | `U{n}` | Uncertain node | `U1[Redis sessions?]` | | `I{n}` | Implementation | `I1[15min token expiry]` |

Labels

• Keep labels concise (< 30 chars)
• Use sentence case
• Decision points end with `?`
• Implementations are specific

---

Graph Generation Process

Step 1: Identify Root Task

Extract the main task/goal from conversation context:

ROOT[Task: Build authentication system]

Step 2: Map Major Decisions

For each ESTABLISHED or WORKING assumption, trace back:

• What decision led to this assumption?
• What alternatives existed?

Step 3: Build Decision Tree

Connect decisions hierarchically:

ROOT --> D1{Scope?}
D1 --> P1[Production] --> D2{Architecture?}
D1 --> A1[MVP]
D2 --> P2[Stateless] --> D3{Token Strategy?}
D2 --> A2[Stateful]

Step 4: Add Leaf Implementations

For concrete decisions (ESTABLISHED assumptions):

D3 --> I1[JWT access tokens]
D3 --> I2[Refresh token rotation]
I1 --> I3[15min expiry]
I2 --> I4[7-day refresh window]

Step 5: Mark Uncertainty

Flag OPEN assumptions and uncertain branches:

D2 -->|"[uncertain]"| U1[Redis sessions?]
style U1 fill:#FFB366,stroke:#333

Step 6: Apply Styling

Add style rules for all nodes based on their type.

---

Complete Example

Context

User wants to build an authentication system. Through conversation:

• Production-grade confirmed (inferred from requirements)
• Stateless preferred (assumed, not confirmed)
• JWT chosen over sessions (working assumption)

Generated Graph

flowchart TD
    ROOT[Task: Build auth system] --> D1{MVP or Production?}
    D1 -->|"0.8 [inferred]"| P1[Production-grade]
    D1 -->|"0.2 [alternative]"| A1[MVP/Prototype]

    P1 --> D2{Stateless required?}
    D2 -->|"0.7 [assumed]"| P2[JWT + refresh tokens]
    D2 -->|"0.3 [uncertain]"| U1[Redis sessions]

    P2 --> I1[Access token: 15min]
    P2 --> I2[Refresh token: 7 days]
    P2 --> I3[Token rotation on refresh]

    U1 --> I4[Session in Redis]
    U1 --> I5[Cookie-based ID]
    U1 --> D3{Scaling concern?}
    D3 -->|"[uncertain]"| U2[Redis cluster needed]
    D3 -->|"[alternative]"| A2[Single instance OK]

    style D1 fill:#ffcc00,stroke:#333
    style D2 fill:#ffcc00,stroke:#333
    style D3 fill:#ffcc00,stroke:#333
    style P1 fill:#90EE90,stroke:#333
    style P2 fill:#90EE90,stroke:#333
    style A1 fill:#cccccc,stroke:#333
    style U1 fill:#FFB366,stroke:#333
    style U2 fill:#FFB366,stroke:#333
    style A2 fill:#cccccc,stroke:#333
    style I1 fill:#87CEEB,stroke:#333
    style I2 fill:#87CEEB,stroke:#333
    style I3 fill:#87CEEB,stroke:#333
    style I4 fill:#87CEEB,stroke:#333
    style I5 fill:#87CEEB,stroke:#333

---

Embedding in COMMON-GROUND.md

Add the graph as a section in the ground file:

---

## Reasoning Graph

Last gener