gvDecision Creation Architecture

Details

Raw Data

{
  "id": "a6180dbb-88ef-4453-81ec-0dff359c2f68",
  "type": "general",
  "status": "completed",
  "title": "gvDecision Creation Architecture",
  "description": "How gvDecisions are created in the Konnect codebase",
  "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 16px 0;\">gvDecision Creation Architecture</h2>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#61afef;margin:0 0 12px 0;\">Creation Flow</h3>\n<pre style=\"margin:0;line-height:1.8;color:#e0e0e0;\">\n<span style=\"color:#c678dd;\">Claude/MCP</span> → <span style=\"color:#98c379;\">konui_create_decision</span> → <span style=\"color:#e5c07b;\">POST /api/gv/decisions</span>\n     ↓\n<span style=\"color:#56b6c2;\">gv-decision-store.ts</span> → <span style=\"color:#98c379;\">gvdecisions.jsonl</span>\n</pre>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#61afef;margin:0 0 12px 0;\">Key Files</h3>\n<pre style=\"margin:0;line-height:1.8;\">\n<span style=\"color:#56b6c2;font-weight:bold;\">/konui/</span>\n├── <span style=\"color:#98c379;font-weight:bold;\">mcp/</span>\n│   └── <span style=\"color:#e5c07b;\">server.ts</span>            <span style=\"color:#7f848e;\"># MCP tool def (L845-935, L2644-2752)</span>\n├── <span style=\"color:#98c379;font-weight:bold;\">src/</span>\n│   ├── <span style=\"color:#e5c07b;\">gv-decision-types.ts</span> <span style=\"color:#7f848e;\"># TypeScript types & enums</span>\n│   ├── <span style=\"color:#e5c07b;\">gv-decision-store.ts</span> <span style=\"color:#7f848e;\"># Storage layer (L178-213)</span>\n│   └── <span style=\"color:#e5c07b;\">router.ts</span>            <span style=\"color:#7f848e;\"># API routes (L3156-3167)</span>\n└── <span style=\"color:#98c379;font-weight:bold;\">data/</span>\n    └── <span style=\"color:#e5c07b;\">gvdecisions.jsonl</span>    <span style=\"color:#7f848e;\"># Append-only storage</span>\n</pre>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#61afef;margin:0 0 12px 0;\">Required Fields</h3>\n<pre style=\"margin:0;line-height:1.6;\">\n<span style=\"color:#c678dd;\">flowId</span>       <span style=\"color:#7f848e;\">- Parent gvFlow ID</span>\n<span style=\"color:#c678dd;\">turnId</span>       <span style=\"color:#7f848e;\">- Turn where decision was made</span>\n<span style=\"color:#c678dd;\">category</span>     <span style=\"color:#7f848e;\">- design | action | deferred</span>\n<span style=\"color:#c678dd;\">type</span>         <span style=\"color:#7f848e;\">- e.g. design:architecture, action:commit</span>\n<span style=\"color:#c678dd;\">title</span>        <span style=\"color:#7f848e;\">- Short descriptive title</span>\n<span style=\"color:#c678dd;\">chosen</span>       <span style=\"color:#7f848e;\">- { value, label? } what was selected</span>\n<span style=\"color:#c678dd;\">rationale</span>   <span style=\"color:#7f848e;\">- Why this choice was made</span>\n<span style=\"color:#c678dd;\">scope</span>        <span style=\"color:#7f848e;\">- turn | flow | project | organization</span>\n<span style=\"color:#c678dd;\">visibility</span>   <span style=\"color:#7f848e;\">- internal | team | stakeholder | public</span>\n<span style=\"color:#c678dd;\">confidence</span>   <span style=\"color:#7f848e;\">- certain | high | medium | low | guess</span>\n<span style=\"color:#c678dd;\">origin</span>       <span style=\"color:#7f848e;\">- explicit | kontask | implementation | ...</span>\n<span style=\"color:#c678dd;\">impact</span>       <span style=\"color:#7f848e;\">- { level, areas?, description? }</span>\n<span style=\"color:#c678dd;\">reversibility</span> <span style=\"color:#7f848e;\">- { reversible, cost?, howToReverse? }</span>\n</pre>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#61afef;margin:0 0 12px 0;\">Decision Categories</h3>\n<table style=\"width:100%;border-collapse:collapse;\">\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px 0;\"><span style=\"color:#98c379;\">design</span></td>\n<td style=\"color:#7f848e;\">Architecture, API design, data modeling, tooling choices</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px 0;\"><span style=\"color:#e5c07b;\">action</span></td>\n<td style=\"color:#7f848e;\">Commits, deploys, config changes, rollbacks</td>\n</tr>\n<tr>\n<td style=\"padding:8px 0;\"><span style=\"color:#c678dd;\">deferred</span></td>\n<td style=\"color:#7f848e;\">Questions needing approval, research, follow-up</td>\n</tr>\n</table>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#61afef;margin:0 0 12px 0;\">Storage Mechanism</h3>\n<pre style=\"margin:0;line-height:1.6;\">\n<span style=\"color:#7f848e;\">Format:</span>    <span style=\"color:#e5c07b;\">Append-only JSONL</span>\n<span style=\"color:#7f848e;\">ID Format:</span> <span style=\"color:#98c379;\">dec_{ULID}</span>\n<span style=\"color:#7f848e;\">Index:</span>     <span style=\"color:#7f848e;\">In-memory by flow, turn, session, category</span>\n</pre>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#61afef;margin:0 0 12px 0;\">MCP Tool Example</h3>\n<pre style=\"margin:0;line-height:1.6;font-size:12px;\">\n<span style=\"color:#c678dd;\">await</span> konui_create_decision({\n  flowId: <span style=\"color:#98c379;\">\"flow_abc123\"</span>,\n  turnId: <span style=\"color:#98c379;\">\"turn_xyz789\"</span>,\n  category: <span style=\"color:#98c379;\">\"design\"</span>,\n  type: <span style=\"color:#98c379;\">\"design:architecture\"</span>,\n  title: <span style=\"color:#98c379;\">\"Use SQLite for local storage\"</span>,\n  chosen: { value: <span style=\"color:#98c379;\">\"sqlite\"</span>, label: <span style=\"color:#98c379;\">\"SQLite\"</span> },\n  rationale: <span style=\"color:#98c379;\">\"Simple, file-based, no server needed\"</span>,\n  scope: <span style=\"color:#98c379;\">\"project\"</span>,\n  visibility: <span style=\"color:#98c379;\">\"team\"</span>,\n  confidence: <span style=\"color:#98c379;\">\"high\"</span>,\n  origin: <span style=\"color:#98c379;\">\"explicit\"</span>,\n  impact: { level: <span style=\"color:#98c379;\">\"medium\"</span> },\n  reversibility: { reversible: <span style=\"color:#c678dd;\">true</span>, cost: <span style=\"color:#98c379;\">\"moderate\"</span> }\n});\n</pre>\n</div>\n\n<div style=\"background:#1a3a1a;border:1px solid #2d5a2d;padding:12px;border-radius:6px;\">\n<span style=\"color:#98c379;\">ℹ</span> <strong style=\"color:#98c379;\">Key Insight:</strong> Decisions are linked to gvFlows (parent workflows) and can track alternatives, impact, and reversibility. They use an immutable append-only storage pattern.\n</div>\n</div>",
    "requestedAt": "2026-01-09T08:39:00.000Z",
    "requestId": "03f01046-a961-4961-b556-38f75f96ea70",
    "choices": [
      {
        "label": "View decision types",
        "value": "Show me all the decision type definitions",
        "primary": false
      },
      {
        "label": "Create a test decision",
        "value": "Create a sample gvDecision to test the system"
      },
      {
        "label": "View decisions API",
        "value": "Show me the full gvDecisions API endpoints"
      }
    ],
    "turnTiming": {
      "totalMs": 110289,
      "ttfeMs": 43,
      "thinkingMs": 110246,
      "toolExecutionMs": 0,
      "toolCallCount": 0,
      "thinkingPct": 100,
      "toolsPct": 0,
      "ttfePct": 0
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-09T08:42:44.764Z",
  "updatedAt": "2026-01-09T08:42:49.371Z",
  "requestId": "03f01046-a961-4961-b556-38f75f96ea70",
  "scope": "vibetools",
  "tags": [
    "gvdecisions",
    "architecture",
    "documentation"
  ],
  "sessionId": "ses_9c69cb59-31c",
  "flowId": "flow_01KEGVRXHHK7E25VFSX4HCV289",
  "flowLinks": [
    {
      "flowId": "flow_01KEGVRXHHK7E25VFSX4HCV289",
      "edgeType": "evidence",
      "createdAt": "2026-01-09T08:42:44.764Z"
    }
  ],
  "targetUser": "claude"
}