CLAUDE.md Structure Audit & Reorganization

Details

Raw Data

{
  "id": "289b3dd0-0a8b-46bb-967c-4fa97568034a",
  "type": "general",
  "status": "completed",
  "title": "CLAUDE.md Structure Audit & Reorganization",
  "description": "Audited and reorganized critical instructions in CLAUDE.md, placing gvFlow curation alongside context recovery",
  "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;\">CLAUDE.md Structure Audit & Reorganization</h2>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:16px 0 8px 0;\">Problem Identified</h3>\n<p style=\"line-height:1.6;margin:0 0 16px 0;\">\nThe gvFlow instructions were placed 500+ lines below the context recovery instructions, making it unlikely Claude would notice and follow both. Critical behaviors were:\n</p>\n<ul style=\"margin:0 0 16px 0;line-height:1.8;\">\n<li><span style=\"color:#e5c07b;\">Context Recovery</span> - buried at line 482-498 inside Kontasks section</li>\n<li><span style=\"color:#e5c07b;\">gvFlow Curation</span> - separate section starting at line 695</li>\n<li><span style=\"color:#c678dd;\">Neither marked as equally critical</span></li>\n</ul>\n\n<h3 style=\"font-family:sans-serif;color:#98c379;margin:16px 0 8px 0;\">Changes Made</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h4 style=\"color:#56b6c2;margin:0 0 8px 0;\">1. New Critical Section (lines 199-252)</h4>\n<pre style=\"margin:0;color:#e0e0e0;white-space:pre-wrap;\">## CRITICAL: Turn Start Behaviors (MANDATORY)\n\n⚠️ Every turn MUST begin with these actions in order:\n1. Context Recovery - konui_get_recent_kontasks\n2. Flow Curation - konui_suggest_matching_flows + konui_get_or_create_flow\n3. Process Approved Tasks (if hook shows any)</pre>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h4 style=\"color:#56b6c2;margin:0 0 8px 0;\">2. Cross-References Added</h4>\n<ul style=\"margin:0;line-height:1.8;\">\n<li>Kontasks section now points to Turn Start Behaviors</li>\n<li>gvFlow section now points to Turn Start Behaviors</li>\n<li>Turn Start section links back to both for full docs</li>\n</ul>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h4 style=\"color:#56b6c2;margin:0 0 8px 0;\">3. Combined Turn Start Pattern</h4>\n<pre style=\"margin:0;color:#98c379;font-size:13px;\">// At turn start, call in parallel:\nawait Promise.all([\n  konui_get_recent_kontasks({ count: 3 }),\n  konui_suggest_matching_flows({ prompt: userPrompt }),\n]);\n\n// Then get/create flow for session linking\nconst flow = await konui_get_or_create_flow({ sessionId, prompt });</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#c678dd;margin:16px 0 8px 0;\">New Files Created</h3>\n\n<table style=\"width:100%;border-collapse:collapse;margin-bottom:16px;\">\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;color:#e5c07b;\">docs/CLAUDE-STRUCTURE.md</td>\n<td style=\"padding:8px;\">Expected section order, regression indicators, common issues</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;color:#e5c07b;\">tests/claude-structure.test.ts</td>\n<td style=\"padding:8px;\">19 regression tests for CLAUDE.md layout</td>\n</tr>\n</table>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:16px 0 8px 0;\">Regression Tests (19 total)</h3>\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<pre style=\"margin:0;color:#98c379;\">✓ Turn Start Behaviors section exists with CRITICAL marker\n✓ Turn Start Behaviors section marked as MANDATORY\n✓ Turn Start Behaviors appears before Project Overview\n✓ Turn Start Behaviors appears after Approved Task Handling\n✓ konui_get_recent_kontasks documented at least 3 times\n✓ konui_suggest_matching_flows documented at least 2 times\n✓ konui_get_or_create_flow documented at least 2 times\n✓ Kontasks section back-references Turn Start Behaviors\n✓ gvFlow section back-references Turn Start Behaviors\n✓ Combined Turn Start Pattern exists\n✓ No duplicate MANDATORY context recovery sections\n... and 8 more</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#f97316;margin:16px 0 8px 0;\">Section Order (Critical sections highlighted)</h3>\n<pre style=\"background:#2d2d2d;padding:16px;border-radius:6px;overflow-x:auto;line-height:1.6;color:#e0e0e0;\">\n<span style=\"color:#7f848e;\">1. Header & Platform Migration</span>\n<span style=\"color:#f43f5e;font-weight:bold;\">2. Production System Warning ⚠️</span>\n<span style=\"color:#7f848e;\">3. Trusted Pair Programmer</span>\n<span style=\"color:#7f848e;\">4. Coding Standards (gv/)</span>\n<span style=\"color:#f43f5e;font-weight:bold;\">5. Service Restart Safety ⚠️</span>\n<span style=\"color:#f43f5e;font-weight:bold;\">6. Turn Completion Protocol ⚠️</span>\n<span style=\"color:#f43f5e;font-weight:bold;\">7. Approved Task Handling ⚠️</span>\n<span style=\"color:#22c55e;font-weight:bold;\">8. CRITICAL: Turn Start Behaviors ⚠️ (NEW - lines 199-252)</span>\n<span style=\"color:#7f848e;\">9. Project Overview</span>\n<span style=\"color:#7f848e;\">... (reference sections) ...</span>\n<span style=\"color:#61afef;\">19. Kontasks (→ references Turn Start)</span>\n<span style=\"color:#61afef;\">20. gvFlow (→ references Turn Start)</span>\n<span style=\"color:#7f848e;\">21. Dashboard Console</span>\n<span style=\"color:#7f848e;\">... (remaining sections) ...</span>\n</pre>\n\n<div style=\"margin-top:20px;padding:12px;background:#2d4a2d;border-radius:6px;border-left:4px solid #22c55e;\">\n<strong style=\"color:#22c55e;\">Commit:</strong> <code style=\"color:#e5c07b;\">7aedd479</code><br/>\n<span style=\"color:#98c379;\">3 files changed, 527 insertions(+), 15 deletions(-)</span>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:20px 0 8px 0;\">Run Tests</h3>\n<pre style=\"background:#2d2d2d;padding:12px;border-radius:6px;color:#61afef;\">deno test -A tests/claude-structure.test.ts</pre>\n\n</div>",
    "requestedAt": "2026-01-09T00:00:00.000Z",
    "requestId": "966343da-b374-4e34-bb9d-7a894b8748d6",
    "commitSha": "7aedd479",
    "choices": [
      {
        "label": "Run regression tests",
        "value": "Run the CLAUDE.md structure regression tests to verify everything passes",
        "primary": true
      },
      {
        "label": "View full CLAUDE.md",
        "value": "Show me the current CLAUDE.md file structure"
      },
      {
        "label": "Add more tests",
        "value": "Add additional regression tests for other critical sections in CLAUDE.md"
      }
    ],
    "turnTiming": {
      "totalMs": 256104,
      "ttfeMs": 125,
      "thinkingMs": 255978,
      "toolExecutionMs": 0,
      "toolCallCount": 0,
      "thinkingPct": 100,
      "toolsPct": 0,
      "ttfePct": 0
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-09T10:26:43.942Z",
  "updatedAt": "2026-01-09T10:26:51.345Z",
  "targetUser": "claude",
  "requestId": "966343da-b374-4e34-bb9d-7a894b8748d6",
  "scope": "vibetools",
  "tags": [
    "claude-md",
    "documentation",
    "gvflow",
    "kontasks"
  ],
  "sessionId": "ses_d3abe491-395",
  "flowId": "flow_01KEGVRXHHK7E25VFSX4HCV289",
  "flowLinks": [
    {
      "flowId": "flow_01KEGVRXHHK7E25VFSX4HCV289",
      "edgeType": "evidence",
      "createdAt": "2026-01-09T10:26:43.942Z"
    }
  ]
}