Turn → Flow/Decision Integration Gap Analysis

Details

Raw Data

{
  "id": "c0a4acbc-16e3-479c-beee-bcfa271f2fc0",
  "type": "general",
  "status": "completed",
  "title": "Turn → Flow/Decision Integration Gap Analysis",
  "description": "Analysis of what's needed to automatically populate gvFlows and gvDecisions from turns",
  "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;\">🔗 Turn → Flow/Decision Integration Gap Analysis</h2>\n\n<h3 style=\"color:#61afef;margin:16px 0 8px 0;\">Current State</h3>\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#98c379;\">✓ COMPLETE:</span>\n  • gvDecision types + JSONL store (konui)\n  • gvFlow types + JSONL store (konui)\n  • 9 MCP tools for create/list/get/update\n  • Schema documentation (gvDecisionSchema.md, gvFlowSchema.md)\n\n<span style=\"color:#e5c07b;\">⚠ MISSING:</span>\n  • konsole → konui bridge (turns don't create gvTurns)\n  • flowId/turnId injection in session context\n  • Automatic decision detection\n</pre>\n\n<h3 style=\"color:#61afef;margin:16px 0 8px 0;\">Gap 1: Session ↔ Flow Binding</h3>\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\"># konsole/src/session.ts has NO flowId field</span>\n\ninterface Session {\n  id: string;\n  sessionType: SessionType;\n  provider: Provider;\n  <span style=\"color:#f44747;\">// flowId?: string;      ← MISSING</span>\n  <span style=\"color:#f44747;\">// turnSequence?: number; ← MISSING</span>\n}\n\n<span style=\"color:#c678dd;\">Needed:</span>\n  • Add flowId to Session interface\n  • Add turnSequence counter\n  • Bind session to flow on creation or first turn\n</pre>\n\n<h3 style=\"color:#61afef;margin:16px 0 8px 0;\">Gap 2: Turn → gvTurn Transformation</h3>\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\"># konsole produces Kontext, not GvTurn</span>\n\nKontext (current)        →   GvTurn (needed)\n────────────────────────────────────────────────\n• id                     →   id ✓\n• sessionId              →   sessionId ✓\n• <span style=\"color:#f44747;\">—</span>                     →   sequence (need counter)\n• prompt                 →   prompt.content ✓\n• <span style=\"color:#f44747;\">—</span>                     →   prompt.source (device, viewerId)\n• output.text            →   response.content ✓\n• <span style=\"color:#f44747;\">—</span>                     →   response.model (need from stream)\n• workingHistory         →   toolCalls ✓ (transform needed)\n• tokenUsage             →   metrics ✓ (partially available)\n• requestedAt            →   createdAt ✓\n• completedAt            →   completedAt ✓\n</pre>\n\n<h3 style=\"color:#61afef;margin:16px 0 8px 0;\">Gap 3: Turn Event → Konui</h3>\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\"># Need to emit turn events to konui</span>\n\n<span style=\"color:#56b6c2;\">Option A:</span> HTTP POST on turn complete\n  POST /api/gv/turns  { turn: GvTurn }\n\n<span style=\"color:#56b6c2;\">Option B:</span> WebSocket event\n  { type: \"turn:complete\", turn: GvTurn }\n\n<span style=\"color:#56b6c2;\">Option C:</span> MCP tool call\n  Claude calls konui_create_turn() internally\n</pre>\n\n<h3 style=\"color:#61afef;margin:16px 0 8px 0;\">Gap 4: Automatic Decision Detection</h3>\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\"># Decisions are NOT automatically captured</span>\n\nCurrently: Claude must <span style=\"color:#e5c07b;\">manually</span> call konui_create_decision()\n\nMissing:\n  • System prompt instruction to track decisions\n  • Auto-detection from tool calls (git commit → action:commit)\n  • Hooks for commit/deploy/test → action decisions\n  • Pattern matching for design decisions in output\n</pre>\n\n<h3 style=\"color:#61afef;margin:16px 0 8px 0;\">Implementation Plan</h3>\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#98c379;\">Phase 1:</span> Session-Flow Binding\n  1. Add flowId to konsole Session type\n  2. Add /api/gv/flows endpoint to konui\n  3. Create/bind flow on first turn of session\n\n<span style=\"color:#98c379;\">Phase 2:</span> Turn Persistence\n  4. Add gvturns.jsonl store in konui\n  5. Transform Kontext → GvTurn on complete\n  6. POST turn to konui on completion\n\n<span style=\"color:#98c379;\">Phase 3:</span> Decision Automation\n  7. Add decision hints to system prompt\n  8. Auto-create decisions for git commits\n  9. Pattern matching for design decisions\n</pre>\n\n<h3 style=\"color:#61afef;margin:16px 0 8px 0;\">Quick Win: Manual Instrumentation</h3>\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;\">\n<span style=\"color:#7f848e;\"># Add to CLAUDE.md instructions:</span>\n\n<span style=\"color:#c678dd;\">## Turn Tracking (Optional)</span>\n\nWhen working on tracked flows, create decisions:\n\n<span style=\"color:#56b6c2;\">// After git commit</span>\nawait konui_create_decision({\n  flowId: \"flow_xxx\",  // From session context\n  turnId: \"turn_xxx\",  // Current turn ID\n  category: \"action\",\n  type: \"action:commit\",\n  title: \"Committed: {message}\",\n  chosen: { value: \"commit\", label: \"Git Commit\" },\n  rationale: \"Changes ready for review\",\n  ...\n});\n</pre>\n\n<div style=\"margin-top:16px;padding:12px;background:#2d2d2d;border-radius:6px;border-left:3px solid #f59e0b;\">\n<strong style=\"color:#f59e0b;\">⚡ Summary:</strong> Types and storage are complete. Missing the <strong>plumbing</strong> - konsole doesn't emit turn events to konui, and there's no flowId in session context. Phase 1-2 would enable turns to populate flows. Phase 3 would automate decision capture.\n</div>\n</div>",
    "requestedAt": "2026-01-09T05:30:00.000Z",
    "requestId": "7848b25e-e544-4e8b-ad40-6dc74954a483",
    "choices": [
      {
        "label": "Start Phase 1",
        "value": "Start implementing Phase 1: Session-Flow Binding - add flowId to konsole Session type and create /api/gv/flows endpoint",
        "primary": true
      },
      {
        "label": "Quick Win First",
        "value": "Add manual instrumentation instructions to CLAUDE.md for tracking decisions during turns"
      },
      {
        "label": "Design Discussion",
        "value": "Let's discuss the architecture options (HTTP vs WebSocket vs MCP) for turn events before implementing"
      }
    ],
    "turnTiming": {
      "totalMs": 69717,
      "ttfeMs": 402,
      "thinkingMs": 69315,
      "toolExecutionMs": 0,
      "toolCallCount": 0,
      "thinkingPct": 99,
      "toolsPct": 0,
      "ttfePct": 1
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-09T05:28:15.473Z",
  "updatedAt": "2026-01-09T05:28:20.556Z",
  "requestId": "7848b25e-e544-4e8b-ad40-6dc74954a483",
  "scope": "vibetools",
  "tags": [
    "gvDecision",
    "gvFlow",
    "konsole",
    "integration"
  ],
  "targetUser": "claude"
}