gvFlow Decision Graph: Capturing Key Choices

Details

Raw Data

{
  "id": "3b35ba30-6c43-443e-abc8-8deee314037f",
  "type": "general",
  "status": "completed",
  "title": "gvFlow Decision Graph: Capturing Key Choices",
  "description": "Design for tracking all decisions (Claude + human) in flows with lineage to docs",
  "context": {
    "output": "<div style=\"background:#1e1e1e;color:#e0e0e0;padding:20px;border-radius:8px;font-family:'Consolas','Monaco',monospace;\">\n<h2 style=\"font-family:sans-serif;color:#fff;margin:0 0 20px 0;\">gvFlow Decision Graph</h2>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;border-left:4px solid #c678dd;\">\n<p style=\"margin:0;color:#c678dd;font-weight:bold;\">This is huge.</p>\n<p style=\"margin:8px 0 0 0;color:#e0e0e0;\">Decisions are the DNA of a codebase. Currently they're buried in chat history and lost. Surfacing them creates <strong>living documentation</strong>.</p>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Two Types of Decisions</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;line-height:2;color:#e0e0e0;font-size:13px;\">\n<span style=\"color:#61afef;font-weight:bold;\">Human Decisions</span> <span style=\"color:#7f848e;\">(explicit, via UI)</span>\n  • Kontask approvals/rejections\n  • Choice selections\n  • Direction changes (\"actually, let's do X instead\")\n  • <span style=\"color:#22c55e;\">Already captured</span> - kontask responses\n\n<span style=\"color:#c678dd;font-weight:bold;\">Claude Decisions</span> <span style=\"color:#7f848e;\">(implicit, during turns)</span>\n  • Architecture choices (\"I'll use a Map instead of Object\")\n  • Library selections (\"Using date-fns for formatting\")\n  • Pattern choices (\"Implementing as singleton\")\n  • Naming decisions (\"Calling this flowContext\")\n  • <span style=\"color:#f43f5e;\">Currently invisible!</span> - buried in turn\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Decision Data Model</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;line-height:1.6;color:#e0e0e0;font-size:12px;background:#1e1e1e;padding:12px;border-radius:4px;\">\n<span style=\"color:#c678dd;\">interface</span> <span style=\"color:#e5c07b;\">gvDecision</span> {\n  id: <span style=\"color:#98c379;\">string</span>;\n  flowId: <span style=\"color:#98c379;\">string</span>;              <span style=\"color:#7f848e;\">// Parent flow</span>\n  turnId: <span style=\"color:#98c379;\">string</span>;              <span style=\"color:#7f848e;\">// Which turn made it</span>\n  \n  <span style=\"color:#7f848e;\">// Who and what</span>\n  madeBy: <span style=\"color:#98c379;\">\"claude\"</span> | <span style=\"color:#98c379;\">\"human\"</span>;\n  type: <span style=\"color:#e5c07b;\">DecisionType</span>;          <span style=\"color:#7f848e;\">// See below</span>\n  \n  <span style=\"color:#7f848e;\">// The decision itself</span>\n  title: <span style=\"color:#98c379;\">string</span>;               <span style=\"color:#7f848e;\">// \"Use JSONL for flow storage\"</span>\n  chosen: <span style=\"color:#98c379;\">string</span>;              <span style=\"color:#7f848e;\">// What was picked</span>\n  alternatives?: <span style=\"color:#98c379;\">string</span>[];     <span style=\"color:#7f848e;\">// What was considered</span>\n  rationale: <span style=\"color:#98c379;\">string</span>;           <span style=\"color:#7f848e;\">// Why this choice</span>\n  \n  <span style=\"color:#7f848e;\">// Impact tracking</span>\n  impact: <span style=\"color:#98c379;\">\"low\"</span> | <span style=\"color:#98c379;\">\"medium\"</span> | <span style=\"color:#98c379;\">\"high\"</span>;\n  reversible: <span style=\"color:#98c379;\">boolean</span>;         <span style=\"color:#7f848e;\">// Can we change later?</span>\n  affectedFiles?: <span style=\"color:#98c379;\">string</span>[];    <span style=\"color:#7f848e;\">// What it touches</span>\n  \n  <span style=\"color:#7f848e;\">// Review status</span>\n  status: <span style=\"color:#98c379;\">\"made\"</span> | <span style=\"color:#98c379;\">\"reviewed\"</span> | <span style=\"color:#98c379;\">\"pivoted\"</span> | <span style=\"color:#98c379;\">\"documented\"</span>;\n  reviewedAt?: <span style=\"color:#98c379;\">Date</span>;\n  pivotedTo?: <span style=\"color:#98c379;\">string</span>;          <span style=\"color:#7f848e;\">// New decision ID if pivoted</span>\n}\n\n<span style=\"color:#c678dd;\">type</span> <span style=\"color:#e5c07b;\">DecisionType</span> = \n  | <span style=\"color:#98c379;\">\"architecture\"</span>    <span style=\"color:#7f848e;\">// System design</span>\n  | <span style=\"color:#98c379;\">\"pattern\"</span>         <span style=\"color:#7f848e;\">// Code pattern</span>\n  | <span style=\"color:#98c379;\">\"library\"</span>         <span style=\"color:#7f848e;\">// Dependency choice</span>\n  | <span style=\"color:#98c379;\">\"naming\"</span>          <span style=\"color:#7f848e;\">// Names for things</span>\n  | <span style=\"color:#98c379;\">\"api\"</span>             <span style=\"color:#7f848e;\">// API design</span>\n  | <span style=\"color:#98c379;\">\"ux\"</span>              <span style=\"color:#7f848e;\">// User experience</span>\n  | <span style=\"color:#98c379;\">\"data\"</span>            <span style=\"color:#7f848e;\">// Data model</span>\n  | <span style=\"color:#98c379;\">\"tradeoff\"</span>;       <span style=\"color:#7f848e;\">// Explicit tradeoff</span>\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">How Claude Reports Decisions</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;line-height:1.8;color:#e0e0e0;font-size:13px;\">\n<span style=\"color:#c678dd;\">Option A: Inline MCP Tool</span>\n<span style=\"color:#7f848e;\">────────────────────────</span>\nClaude calls <span style=\"color:#98c379;\">gvHub_record_decision()</span> during turn\n\n<span style=\"color:#e5c07b;\">Pros:</span> Real-time, precise\n<span style=\"color:#f43f5e;\">Cons:</span> Adds tool calls, Claude might skip it\n\n<span style=\"color:#22c55e;\">Option B: Structured Turn Output</span> <span style=\"color:#22c55e;\">← Recommended</span>\n<span style=\"color:#7f848e;\">────────────────────────</span>\nKontask context includes <span style=\"color:#98c379;\">decisions[]</span> array\nClaude summarizes decisions at end of turn\n\n<span style=\"color:#e5c07b;\">Pros:</span> Batched, natural flow\n<span style=\"color:#f43f5e;\">Cons:</span> Post-hoc, might miss some\n\n<span style=\"color:#c678dd;\">Option C: CLAUDE.md Instruction</span>\n<span style=\"color:#7f848e;\">────────────────────────</span>\n\"Always surface key decisions in kontask output\"\nParse from HTML output\n\n<span style=\"color:#e5c07b;\">Pros:</span> Simple, no new tools\n<span style=\"color:#f43f5e;\">Cons:</span> Relies on Claude compliance, parsing\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Decision Graph Visualization</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;line-height:1.8;color:#e0e0e0;font-size:13px;\">\n<span style=\"color:#c678dd;\">Flow: \"Implement gvFlows\"</span>\n\n<span style=\"color:#61afef;\">●</span> <span style=\"color:#61afef;\">human</span>: Use flows as container above sessions\n   <span style=\"color:#7f848e;\">│</span>\n   <span style=\"color:#7f848e;\">├──</span> <span style=\"color:#c678dd;\">○</span> <span style=\"color:#c678dd;\">claude</span>: Store flows in JSONL (like kontasks)\n   <span style=\"color:#7f848e;\">│      rationale: Consistent with existing patterns</span>\n   <span style=\"color:#7f848e;\">│      alternatives: SQLite, PostgreSQL</span>\n   <span style=\"color:#7f848e;\">│</span>\n   <span style=\"color:#7f848e;\">├──</span> <span style=\"color:#c678dd;\">○</span> <span style=\"color:#c678dd;\">claude</span>: Name it gvFlow (not WorkUnit, Task)\n   <span style=\"color:#7f848e;\">│      rationale: Matches gvShell/gvHub naming</span>\n   <span style=\"color:#7f848e;\">│</span>\n   <span style=\"color:#7f848e;\">└──</span> <span style=\"color:#61afef;\">●</span> <span style=\"color:#61afef;\">human</span>: Track key decisions in flows\n          <span style=\"color:#7f848e;\">│</span>\n          <span style=\"color:#7f848e;\">├──</span> <span style=\"color:#c678dd;\">○</span> <span style=\"color:#c678dd;\">claude</span>: Use structured output in kontask\n          <span style=\"color:#7f848e;\">│</span>\n          <span style=\"color:#7f848e;\">└──</span> <span style=\"color:#c678dd;\">○</span> <span style=\"color:#c678dd;\">claude</span>: Include alternatives + rationale\n\n<span style=\"color:#7f848e;\">● human decision  ○ claude decision</span>\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Decision Review Workflow</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;line-height:2;color:#e0e0e0;font-size:13px;\">\n<span style=\"color:#22c55e;\">1. During Flow</span>\n   Decisions accumulate in <span style=\"color:#c678dd;\">flow.decisions[]</span>\n   UI shows decision count badge: <span style=\"background:#c678dd;color:#fff;padding:1px 6px;border-radius:8px;font-size:11px;\">5 decisions</span>\n\n<span style=\"color:#e5c07b;\">2. Decision Review View</span>\n   <span style=\"color:#7f848e;\">\"/flows/:id/decisions\"</span>\n   List all decisions, filter by type/maker\n   Click to see context (which turn, what code)\n\n<span style=\"color:#f97316;\">3. Pivot Option</span>\n   User disagrees with Claude decision\n   Click [Pivot] → creates new turn to undo/redo\n   Original decision marked \"pivoted\"\n   New decision links to old\n\n<span style=\"color:#22c55e;\">4. Document Generation</span>\n   Flow complete → [Generate Docs]\n   Extracts all decisions into:\n   - ADR (Architecture Decision Records)\n   - README updates\n   - API documentation\n   - CHANGELOG entries\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Documentation Pipeline</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;line-height:1.8;color:#e0e0e0;font-size:13px;\">\n<span style=\"color:#c678dd;\">gvFlow</span> ─────────────────────────────────▶ <span style=\"color:#22c55e;\">Docs</span>\n  │\n  ├── decisions (architecture)  ──▶  <span style=\"color:#e5c07b;\">docs/adr/001-*.md</span>\n  │\n  ├── decisions (api)          ──▶  <span style=\"color:#e5c07b;\">API.md updates</span>\n  │\n  ├── decisions (pattern)      ──▶  <span style=\"color:#e5c07b;\">CLAUDE.md updates</span>\n  │\n  ├── all high-impact          ──▶  <span style=\"color:#e5c07b;\">CHANGELOG.md</span>\n  │\n  └── flow summary             ──▶  <span style=\"color:#e5c07b;\">README.md / docs/</span>\n\n<span style=\"color:#7f848e;\">Template:</span>\n  ## Decision: {title}\n  **Made by:** {claude|human} in Turn #{turnId}\n  **Type:** {architecture|pattern|...}\n  **Chosen:** {chosen}\n  **Alternatives considered:** {alternatives}\n  **Rationale:** {rationale}\n  **Impact:** {high|medium|low}\n  **Reversible:** {yes|no}\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Example: This Conversation's Decisions</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;\">\n<table style=\"width:100%;border-collapse:collapse;font-size:12px;\">\n<tr style=\"border-bottom:1px solid #3d3d3d;\">\n<th style=\"text-align:left;padding:8px 0;color:#7f848e;\">Decision</th>\n<th style=\"text-align:center;padding:8px;color:#7f848e;\">By</th>\n<th style=\"text-align:left;padding:8px 0;color:#7f848e;\">Type</th>\n</tr>\n<tr style=\"border-bottom:1px solid #3d3d3d;\">\n<td style=\"padding:8px 0;color:#e0e0e0;\">Show both session + active account in UI</td>\n<td style=\"text-align:center;padding:8px;\"><span style=\"color:#61afef;\">●</span></td>\n<td style=\"padding:8px 0;color:#e5c07b;\">ux</td>\n</tr>\n<tr style=\"border-bottom:1px solid #3d3d3d;\">\n<td style=\"padding:8px 0;color:#e0e0e0;\">Use hybrid approach for account switching</td>\n<td style=\"text-align:center;padding:8px;\"><span style=\"color:#c678dd;\">○</span></td>\n<td style=\"padding:8px 0;color:#e5c07b;\">architecture</td>\n</tr>\n<tr style=\"border-bottom:1px solid #3d3d3d;\">\n<td style=\"padding:8px 0;color:#e0e0e0;\">Flows as container above sessions</td>\n<td style=\"text-align:center;padding:8px;\"><span style=\"color:#61afef;\">●</span></td>\n<td style=\"padding:8px 0;color:#e5c07b;\">architecture</td>\n</tr>\n<tr style=\"border-bottom:1px solid #3d3d3d;\">\n<td style=\"padding:8px 0;color:#e0e0e0;\">Prototype in konsole/konui before gvHub</td>\n<td style=\"text-align:center;padding:8px;\"><span style=\"color:#61afef;\">●</span></td>\n<td style=\"padding:8px 0;color:#e5c07b;\">tradeoff</td>\n</tr>\n<tr>\n<td style=\"padding:8px 0;color:#e0e0e0;\">Track decisions with graph lineage</td>\n<td style=\"text-align:center;padding:8px;\"><span style=\"color:#61afef;\">●</span></td>\n<td style=\"padding:8px 0;color:#e5c07b;\">architecture</td>\n</tr>\n</table>\n<p style=\"margin:12px 0 0 0;color:#7f848e;font-size:11px;\"><span style=\"color:#61afef;\">●</span> = human &nbsp; <span style=\"color:#c678dd;\">○</span> = claude</p>\n</div>\n\n<hr style=\"border:none;border-top:1px solid #3d3d3d;margin:0 0 20px 0;\">\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Implementation Path</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;border-left:4px solid #22c55e;\">\n<pre style=\"margin:0;line-height:1.8;color:#e0e0e0;font-size:13px;\">\n<span style=\"color:#22c55e;\">Phase 1: Capture</span> (konsole/konui)\n  • Add <span style=\"color:#98c379;\">decisions[]</span> to kontask context schema\n  • Update CLAUDE.md to instruct decision surfacing\n  • Parse decisions from kontask output\n\n<span style=\"color:#61afef;\">Phase 2: Display</span> (konui)\n  • Decision list view per flow\n  • Decision graph visualization\n  • Pivot action (creates new turn)\n\n<span style=\"color:#e5c07b;\">Phase 3: Generate</span> (konui → gvHub)\n  • [Generate Docs] action on flow\n  • ADR template generation\n  • CHANGELOG extraction\n</pre>\n</div>\n\n</div>",
    "requestedAt": "2026-01-09T02:40:00.000Z",
    "requestId": "5b1cb956-3ec0-4652-9c76-a4e09bb56e53",
    "choices": [
      {
        "label": "Start capturing decisions",
        "value": "Update CLAUDE.md and kontask schema to start capturing decisions in turns now",
        "primary": true
      },
      {
        "label": "Design decision UI first",
        "value": "Design the decision review and graph visualization UI before implementing capture"
      },
      {
        "label": "Full flow + decisions",
        "value": "Implement gvFlow with decisions together as one cohesive feature"
      },
      {
        "label": "Add to design docs",
        "value": "Add this decision tracking design to gvPlatformVision.md or a new design doc"
      }
    ],
    "turnTiming": {
      "totalMs": 83525,
      "ttfeMs": 87,
      "thinkingMs": 83438,
      "toolExecutionMs": 0,
      "toolCallCount": 0,
      "thinkingPct": 100,
      "toolsPct": 0,
      "ttfePct": 0
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-09T03:07:11.750Z",
  "updatedAt": "2026-01-09T03:07:18.463Z",
  "requestId": "5b1cb956-3ec0-4652-9c76-a4e09bb56e53",
  "scope": "vibetools",
  "tags": [
    "gvshell",
    "gvhub",
    "flows",
    "decisions",
    "architecture"
  ],
  "targetUser": "claude"
}