← Back to Kontasks
gvDecision Complete Schema Specification
Full spectrum decision schema designed for long-term stability
Output
gvDecision Complete Schema
Version 1.0 - Designed for long-term stability
Core Interface
interface gvDecision { // ═══════════════════════════════════════════════════════════════ // IDENTITY (immutable after creation) // ═══════════════════════════════════════════════════════════════ id: string; // "dec-{ulid}" - globally unique version: 1; // Schema version for migrations // ═══════════════════════════════════════════════════════════════ // RELATIONSHIPS (foreign keys) // ═══════════════════════════════════════════════════════════════ flowId: string; // Parent flow (required) turnId: string; // Turn where decision was made sessionId?: string; // Session (for cross-session tracking) // Lineage (decision graph) dependsOn?: string[]; // Decision IDs this depends on supersedes?: string; // Decision ID this replaces (pivot) supersededBy?: string; // Decision ID that replaced this relatedTo?: string[]; // Loosely related decisions // ═══════════════════════════════════════════════════════════════ // CLASSIFICATION // ═══════════════════════════════════════════════════════════════ category: DecisionCategory; // "design" | "action" | "deferred" type: DecisionType; // Specific type within category // Scope & visibility scope: DecisionScope; // How far this decision reaches visibility: DecisionVisibility; // Who should see this // ═══════════════════════════════════════════════════════════════ // THE DECISION ITSELF // ═══════════════════════════════════════════════════════════════ title: string; // Short summary (< 80 chars) description?: string; // Longer explanation if needed // What was chosen chosen: { value: string; // The actual choice made label?: string; // Human-friendly label }; // What else was considered alternatives: { value: string; // The alternative option label?: string; // Human-friendly label whyNot?: string; // Why this wasn't chosen }[]; // Reasoning rationale: string; // Why this choice (required) constraints?: string[]; // What limited the options assumptions?: string[]; // What we assumed to be true // ═══════════════════════════════════════════════════════════════ // DECISION MAKER // ═══════════════════════════════════════════════════════════════ madeBy: { agent: "claude" | "human"; // Who made it userId?: string; // If human, which user model?: string; // If Claude, which model }; // Confidence & certainty confidence: ConfidenceLevel; // How sure about this decision uncertainty?: string; // What's uncertain about it // Origin context origin: DecisionOrigin; // How decision came about trigger?: string; // What prompted this decision // ═══════════════════════════════════════════════════════════════ // IMPACT & RISK // ═══════════════════════════════════════════════════════════════ impact: { level: "low" | "medium" | "high" | "critical"; areas?: ImpactArea[]; // What areas are affected description?: string; // Impact explanation }; risk?: { level: "low" | "medium" | "high"; factors?: string[]; // What makes it risky mitigations?: string[]; // How to reduce risk }; reversibility: { reversible: boolean; // Can this be undone? cost?: "trivial" | "moderate" | "expensive"; howToReverse?: string; // Steps to undo }; // ═══════════════════════════════════════════════════════════════ // AFFECTED ARTIFACTS // ═══════════════════════════════════════════════════════════════ affects?: { files?: string[]; // File paths affected functions?: string[]; // Function names affected types?: string[]; // Type names affected apis?: string[]; // API endpoints affected tests?: string[]; // Test files affected docs?: string[]; // Documentation affected }; // ═══════════════════════════════════════════════════════════════ // DEFERRED DECISION (when Claude asks human) // ═══════════════════════════════════════════════════════════════ deferred?: { question: string; // What Claude asked options?: string[]; // Options presented kontaskId: string; // The kontask that asked resolvedAt?: Date; // When human responded resolvedBy?: string; // Which kontask response resolution?: string; // What human decided }; // ═══════════════════════════════════════════════════════════════ // TIMESTAMPS (append-only, never modified) // ═══════════════════════════════════════════════════════════════ createdAt: Date; // When decision was made reviewedAt?: Date; // When human acknowledged approvedAt?: Date; // When explicitly approved documentedAt?: Date; // When exported to docs // ═══════════════════════════════════════════════════════════════ // DOCUMENTATION OUTPUT // ═══════════════════════════════════════════════════════════════ documentation?: { adrId?: string; // ADR document ID if generated changelogEntry?: string; // CHANGELOG entry text exportedTo?: string[]; // Paths where documented }; // ═══════════════════════════════════════════════════════════════ // EXTENSIBILITY // ═══════════════════════════════════════════════════════════════ tags?: string[]; // Custom tags for filtering metadata?: Record<string, unknown>; // Custom data (future-proof) }
Supporting Types
// ═══════════════════════════════════════════════════════════════ // DECISION CATEGORIES // ═══════════════════════════════════════════════════════════════ type DecisionCategory = "design" | "action" | "deferred"; type DecisionType = // ───────────────────────────────────────────────────────────── // DESIGN DECISIONS (affect codebase structure) // ───────────────────────────────────────────────────────────── | "design:architecture" // System structure, components | "design:pattern" // Code patterns, conventions | "design:data" // Data models, schemas | "design:api" // API design, contracts | "design:interface" // TypeScript interfaces | "design:library" // Dependency choices | "design:naming" // Naming conventions | "design:ux" // User experience | "design:security" // Security approach | "design:performance" // Performance tradeoffs | "design:storage" // Data storage approach | "design:algorithm" // Algorithm choice | "design:tradeoff" // Explicit tradeoff made | "design:other" // Other design decision // ───────────────────────────────────────────────────────────── // ACTION DECISIONS (affect workflow/process) // ───────────────────────────────────────────────────────────── | "action:test" // Test now/later/skip | "action:commit" // Commit now/batch more | "action:explore" // Read more/start coding | "action:scope" // Fix now/note for later | "action:rollback" // Undo/push forward | "action:refactor" // Refactor now/later | "action:validate" // Validate/trust input | "action:deploy" // Deploy now/wait | "action:document" // Document now/skip | "action:cleanup" // Clean up/leave | "action:continue" // Continue flow/start new | "action:other" // Other action decision // ───────────────────────────────────────────────────────────── // DEFERRED DECISIONS (asked human) // ───────────────────────────────────────────────────────────── | "deferred:clarification" // Needed more info | "deferred:approval" // Needed explicit approval | "deferred:choice" // Multiple valid options | "deferred:risk" // Too risky to decide alone | "deferred:policy" // Policy/preference needed | "deferred:other"; // Other reason to defer // ═══════════════════════════════════════════════════════════════ // SCOPE & VISIBILITY // ═══════════════════════════════════════════════════════════════ type DecisionScope = | "turn" // Only relevant to this turn | "flow" // Relevant to entire flow | "project" // Project-wide convention | "organization"; // Org-wide standard type DecisionVisibility = | "internal" // Implementation detail | "team" // Team should know | "stakeholder" // Stakeholders should know | "public"; // Public documentation // ═══════════════════════════════════════════════════════════════ // CONFIDENCE & ORIGIN // ═══════════════════════════════════════════════════════════════ type ConfidenceLevel = | "certain" // No doubt, clear best choice | "high" // Pretty confident | "medium" // Reasonable choice | "low" // Uncertain, could be wrong | "guess"; // Best guess, high uncertainty type DecisionOrigin = | "explicit" // Human explicitly decided | "kontask" // From kontask approval | "implementation" // Emerged during coding | "discussion" // From conversation | "convention" // Following existing pattern | "constraint" // Forced by constraints | "default"; // Default/fallback choice // ═══════════════════════════════════════════════════════════════ // IMPACT AREAS // ═══════════════════════════════════════════════════════════════ type ImpactArea = | "code" // Source code structure | "api" // API contracts | "database" // Data storage | "ui" // User interface | "performance" // System performance | "security" // Security posture | "testing" // Test strategy | "deployment" // Deployment process | "documentation" // Documentation | "workflow" // Development workflow | "cost" // Resource costs | "maintenance"; // Long-term maintenance
Computed Properties
// Status computed from timestamps (not stored) function getDecisionStatus(d: gvDecision): DecisionStatus { if (d.supersededBy) return "superseded"; if (d.category === "deferred" && !d.deferred?.resolvedAt) return "pending"; if (d.documentedAt) return "documented"; if (d.approvedAt) return "approved"; if (d.reviewedAt) return "reviewed"; return "made"; } type DecisionStatus = | "pending" // Deferred, awaiting human | "made" // Decision made, not reviewed | "reviewed" // Human has seen it | "approved" // Explicitly approved | "documented" // Exported to docs | "superseded"; // Replaced by another decision // Needs attention computed function needsAttention(d: gvDecision): boolean { if (d.category === "deferred" && !d.deferred?.resolvedAt) return true; if (d.madeBy.agent === "claude" && !d.reviewedAt) { if (d.confidence === "low" || d.confidence === "guess") return true; if (d.risk?.level === "high") return true; if (d.impact.level === "critical") return true; } return false; }
Example Instances
// Design decision example { id: "dec-01HX5K3M2N4P5Q6R7S8T9U0V", version: 1, flowId: "flow-gvshell-refactor", turnId: "turn-abc123", category: "design", type: "design:architecture", scope: "project", visibility: "team", title: "Use CLAUDE_CONFIG_DIR per-spawn instead of symlink", chosen: { value: "env-var-per-spawn", label: "Per-spawn config dir" }, alternatives: [ { value: "symlink-switch", label: "Symlink switching", whyNot: "Requires hot pool restart" } ], rationale: "Sessions can use different accounts without pool restarts", madeBy: { agent: "human", userId: "stephanie" }, confidence: "high", origin: "kontask", impact: { level: "high", areas: ["code", "workflow"] }, reversibility: { reversible: true, cost: "moderate" }, createdAt: "2026-01-09T01:00:00Z" } // Action decision example { id: "dec-01HX5K3M2N4P5Q6R7S8T9U0W", version: 1, flowId: "flow-gvshell-refactor", turnId: "turn-abc123", category: "action", type: "action:test", scope: "turn", visibility: "internal", title: "Run type check before full tests", chosen: { value: "typecheck-first" }, alternatives: [{ value: "full-test-suite", whyNot: "Slower, type errors first" }], rationale: "Catch type errors quickly before longer test run", madeBy: { agent: "claude", model: "claude-opus-4-5" }, confidence: "certain", origin: "convention", impact: { level: "low" }, risk: { level: "low" }, reversibility: { reversible: true, cost: "trivial" }, createdAt: "2026-01-09T01:15:00Z" } // Deferred decision example { id: "dec-01HX5K3M2N4P5Q6R7S8T9U0X", version: 1, flowId: "flow-gvshell-refactor", turnId: "turn-abc123", category: "deferred", type: "deferred:choice", scope: "flow", visibility: "team", title: "Keep or remove /accounts/switch endpoint", chosen: { value: "keep-repurpose", label: "Keep and repurpose" }, alternatives: [{ value: "remove", label: "Remove entirely" }], rationale: "UI still needs way to change default account", madeBy: { agent: "claude" }, confidence: "medium", origin: "implementation", deferred: { question: "Should we keep or remove the switch endpoint?", options: ["Keep and repurpose", "Remove entirely"], kontaskId: "kontask-xyz789", resolvedAt: "2026-01-09T01:20:00Z", resolution: "Keep - UI needs it" }, impact: { level: "medium", areas: ["api", "ui"] }, createdAt: "2026-01-09T01:18:00Z" }
Storage Strategy
Files: /data/gvdecisions.jsonl // Primary storage (append-only) /data/gvflows.jsonl // Flows (has decisionIds[]) Indexes (computed on load): byFlow: Map<flowId, Decision[]> byTurn: Map<turnId, Decision[]> byType: Map<type, Decision[]> needsAttn: Decision[] // Unreviewed + risky/uncertain Immutability rules: • Core fields never change after creation • Timestamps only added (never removed) • Pivots create new decision with supersedes link • deferred.resolvedAt/resolution added when resolved
Design Principles
✓ Immutable core - decisions never change, only timestamps added ✓ Append-only timestamps - status computed, not stored ✓ Rich alternatives - capture what wasn't chosen and why ✓ Explicit uncertainty - confidence + uncertainty fields ✓ Full lineage - dependsOn, supersedes, relatedTo ✓ Doc pipeline ready - documentation section for ADR export ✓ Extensible - metadata field for future needs ✓ Version field - enables schema migrations
Quick Actions
Original Request
No layout configured
Details
Type
General
Status
Completed
Scope
vibetools
Tags
gvshellgvhubdecisionsschemaspecification
Created
9 Jan 2026, 1:44 pm
Updated
9 Jan 2026, 1:50 pm
Timing
⏱️ 451.6s
0 tools
● TTFE 0%
● Thinking 100%
● Tools 0%
Created By
claude
Raw Data
{
"id": "2cea3d22-b683-4d94-b548-89e5a53d8e00",
"type": "general",
"status": "completed",
"title": "gvDecision Complete Schema Specification",
"description": "Full spectrum decision schema designed for long-term stability",
"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 8px 0;\">gvDecision Complete Schema</h2>\n<p style=\"color:#7f848e;margin:0 0 20px 0;\">Version 1.0 - Designed for long-term stability</p>\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:#22c55e;margin:0 0 12px 0;\">Core Interface</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;\">\n<pre style=\"margin:0;line-height:1.5;color:#e0e0e0;font-size:11px;background:#1e1e1e;padding:12px;border-radius:4px;overflow-x:auto;\">\n<span style=\"color:#c678dd;\">interface</span> <span style=\"color:#e5c07b;\">gvDecision</span> {\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// IDENTITY (immutable after creation)</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n id: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// \"dec-{ulid}\" - globally unique</span>\n version: <span style=\"color:#d19a66;\">1</span>; <span style=\"color:#7f848e;\">// Schema version for migrations</span>\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// RELATIONSHIPS (foreign keys)</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n flowId: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Parent flow (required)</span>\n turnId: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Turn where decision was made</span>\n sessionId?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Session (for cross-session tracking)</span>\n \n <span style=\"color:#7f848e;\">// Lineage (decision graph)</span>\n dependsOn?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// Decision IDs this depends on</span>\n supersedes?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Decision ID this replaces (pivot)</span>\n supersededBy?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Decision ID that replaced this</span>\n relatedTo?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// Loosely related decisions</span>\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// CLASSIFICATION</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n category: <span style=\"color:#e5c07b;\">DecisionCategory</span>; <span style=\"color:#7f848e;\">// \"design\" | \"action\" | \"deferred\"</span>\n type: <span style=\"color:#e5c07b;\">DecisionType</span>; <span style=\"color:#7f848e;\">// Specific type within category</span>\n \n <span style=\"color:#7f848e;\">// Scope & visibility</span>\n scope: <span style=\"color:#e5c07b;\">DecisionScope</span>; <span style=\"color:#7f848e;\">// How far this decision reaches</span>\n visibility: <span style=\"color:#e5c07b;\">DecisionVisibility</span>; <span style=\"color:#7f848e;\">// Who should see this</span>\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// THE DECISION ITSELF</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n title: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Short summary (< 80 chars)</span>\n description?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Longer explanation if needed</span>\n \n <span style=\"color:#7f848e;\">// What was chosen</span>\n chosen: {\n value: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// The actual choice made</span>\n label?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Human-friendly label</span>\n };\n \n <span style=\"color:#7f848e;\">// What else was considered</span>\n alternatives: {\n value: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// The alternative option</span>\n label?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Human-friendly label</span>\n whyNot?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Why this wasn't chosen</span>\n }[];\n \n <span style=\"color:#7f848e;\">// Reasoning</span>\n rationale: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Why this choice (required)</span>\n constraints?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// What limited the options</span>\n assumptions?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// What we assumed to be true</span>\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// DECISION MAKER</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n madeBy: {\n agent: <span style=\"color:#98c379;\">\"claude\"</span> | <span style=\"color:#98c379;\">\"human\"</span>; <span style=\"color:#7f848e;\">// Who made it</span>\n userId?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// If human, which user</span>\n model?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// If Claude, which model</span>\n };\n \n <span style=\"color:#7f848e;\">// Confidence & certainty</span>\n confidence: <span style=\"color:#e5c07b;\">ConfidenceLevel</span>; <span style=\"color:#7f848e;\">// How sure about this decision</span>\n uncertainty?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// What's uncertain about it</span>\n \n <span style=\"color:#7f848e;\">// Origin context</span>\n origin: <span style=\"color:#e5c07b;\">DecisionOrigin</span>; <span style=\"color:#7f848e;\">// How decision came about</span>\n trigger?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// What prompted this decision</span>\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// IMPACT & RISK</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n impact: {\n level: <span style=\"color:#98c379;\">\"low\"</span> | <span style=\"color:#98c379;\">\"medium\"</span> | <span style=\"color:#98c379;\">\"high\"</span> | <span style=\"color:#98c379;\">\"critical\"</span>;\n areas?: <span style=\"color:#e5c07b;\">ImpactArea</span>[]; <span style=\"color:#7f848e;\">// What areas are affected</span>\n description?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Impact explanation</span>\n };\n \n risk?: {\n level: <span style=\"color:#98c379;\">\"low\"</span> | <span style=\"color:#98c379;\">\"medium\"</span> | <span style=\"color:#98c379;\">\"high\"</span>;\n factors?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// What makes it risky</span>\n mitigations?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// How to reduce risk</span>\n };\n \n reversibility: {\n reversible: <span style=\"color:#98c379;\">boolean</span>; <span style=\"color:#7f848e;\">// Can this be undone?</span>\n cost?: <span style=\"color:#98c379;\">\"trivial\"</span> | <span style=\"color:#98c379;\">\"moderate\"</span> | <span style=\"color:#98c379;\">\"expensive\"</span>;\n howToReverse?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Steps to undo</span>\n };\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// AFFECTED ARTIFACTS</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n affects?: {\n files?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// File paths affected</span>\n functions?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// Function names affected</span>\n types?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// Type names affected</span>\n apis?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// API endpoints affected</span>\n tests?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// Test files affected</span>\n docs?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// Documentation affected</span>\n };\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// DEFERRED DECISION (when Claude asks human)</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n deferred?: {\n question: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// What Claude asked</span>\n options?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// Options presented</span>\n kontaskId: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// The kontask that asked</span>\n resolvedAt?: <span style=\"color:#98c379;\">Date</span>; <span style=\"color:#7f848e;\">// When human responded</span>\n resolvedBy?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// Which kontask response</span>\n resolution?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// What human decided</span>\n };\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// TIMESTAMPS (append-only, never modified)</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n createdAt: <span style=\"color:#98c379;\">Date</span>; <span style=\"color:#7f848e;\">// When decision was made</span>\n reviewedAt?: <span style=\"color:#98c379;\">Date</span>; <span style=\"color:#7f848e;\">// When human acknowledged</span>\n approvedAt?: <span style=\"color:#98c379;\">Date</span>; <span style=\"color:#7f848e;\">// When explicitly approved</span>\n documentedAt?: <span style=\"color:#98c379;\">Date</span>; <span style=\"color:#7f848e;\">// When exported to docs</span>\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// DOCUMENTATION OUTPUT</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n documentation?: {\n adrId?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// ADR document ID if generated</span>\n changelogEntry?: <span style=\"color:#98c379;\">string</span>; <span style=\"color:#7f848e;\">// CHANGELOG entry text</span>\n exportedTo?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// Paths where documented</span>\n };\n \n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n <span style=\"color:#7f848e;\">// EXTENSIBILITY</span>\n <span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n \n tags?: <span style=\"color:#98c379;\">string</span>[]; <span style=\"color:#7f848e;\">// Custom tags for filtering</span>\n metadata?: <span style=\"color:#e5c07b;\">Record</span><<span style=\"color:#98c379;\">string</span>, <span style=\"color:#98c379;\">unknown</span>>; <span style=\"color:#7f848e;\">// Custom data (future-proof)</span>\n}\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#61afef;margin:0 0 12px 0;\">Supporting Types</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;\">\n<pre style=\"margin:0;line-height:1.5;color:#e0e0e0;font-size:11px;background:#1e1e1e;padding:12px;border-radius:4px;overflow-x:auto;\">\n<span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n<span style=\"color:#7f848e;\">// DECISION CATEGORIES</span>\n<span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n\n<span style=\"color:#c678dd;\">type</span> <span style=\"color:#e5c07b;\">DecisionCategory</span> = <span style=\"color:#98c379;\">\"design\"</span> | <span style=\"color:#98c379;\">\"action\"</span> | <span style=\"color:#98c379;\">\"deferred\"</span>;\n\n<span style=\"color:#c678dd;\">type</span> <span style=\"color:#e5c07b;\">DecisionType</span> = \n <span style=\"color:#7f848e;\">// ─────────────────────────────────────────────────────────────</span>\n <span style=\"color:#7f848e;\">// DESIGN DECISIONS (affect codebase structure)</span>\n <span style=\"color:#7f848e;\">// ─────────────────────────────────────────────────────────────</span>\n | <span style=\"color:#98c379;\">\"design:architecture\"</span> <span style=\"color:#7f848e;\">// System structure, components</span>\n | <span style=\"color:#98c379;\">\"design:pattern\"</span> <span style=\"color:#7f848e;\">// Code patterns, conventions</span>\n | <span style=\"color:#98c379;\">\"design:data\"</span> <span style=\"color:#7f848e;\">// Data models, schemas</span>\n | <span style=\"color:#98c379;\">\"design:api\"</span> <span style=\"color:#7f848e;\">// API design, contracts</span>\n | <span style=\"color:#98c379;\">\"design:interface\"</span> <span style=\"color:#7f848e;\">// TypeScript interfaces</span>\n | <span style=\"color:#98c379;\">\"design:library\"</span> <span style=\"color:#7f848e;\">// Dependency choices</span>\n | <span style=\"color:#98c379;\">\"design:naming\"</span> <span style=\"color:#7f848e;\">// Naming conventions</span>\n | <span style=\"color:#98c379;\">\"design:ux\"</span> <span style=\"color:#7f848e;\">// User experience</span>\n | <span style=\"color:#98c379;\">\"design:security\"</span> <span style=\"color:#7f848e;\">// Security approach</span>\n | <span style=\"color:#98c379;\">\"design:performance\"</span> <span style=\"color:#7f848e;\">// Performance tradeoffs</span>\n | <span style=\"color:#98c379;\">\"design:storage\"</span> <span style=\"color:#7f848e;\">// Data storage approach</span>\n | <span style=\"color:#98c379;\">\"design:algorithm\"</span> <span style=\"color:#7f848e;\">// Algorithm choice</span>\n | <span style=\"color:#98c379;\">\"design:tradeoff\"</span> <span style=\"color:#7f848e;\">// Explicit tradeoff made</span>\n | <span style=\"color:#98c379;\">\"design:other\"</span> <span style=\"color:#7f848e;\">// Other design decision</span>\n \n <span style=\"color:#7f848e;\">// ─────────────────────────────────────────────────────────────</span>\n <span style=\"color:#7f848e;\">// ACTION DECISIONS (affect workflow/process)</span>\n <span style=\"color:#7f848e;\">// ─────────────────────────────────────────────────────────────</span>\n | <span style=\"color:#98c379;\">\"action:test\"</span> <span style=\"color:#7f848e;\">// Test now/later/skip</span>\n | <span style=\"color:#98c379;\">\"action:commit\"</span> <span style=\"color:#7f848e;\">// Commit now/batch more</span>\n | <span style=\"color:#98c379;\">\"action:explore\"</span> <span style=\"color:#7f848e;\">// Read more/start coding</span>\n | <span style=\"color:#98c379;\">\"action:scope\"</span> <span style=\"color:#7f848e;\">// Fix now/note for later</span>\n | <span style=\"color:#98c379;\">\"action:rollback\"</span> <span style=\"color:#7f848e;\">// Undo/push forward</span>\n | <span style=\"color:#98c379;\">\"action:refactor\"</span> <span style=\"color:#7f848e;\">// Refactor now/later</span>\n | <span style=\"color:#98c379;\">\"action:validate\"</span> <span style=\"color:#7f848e;\">// Validate/trust input</span>\n | <span style=\"color:#98c379;\">\"action:deploy\"</span> <span style=\"color:#7f848e;\">// Deploy now/wait</span>\n | <span style=\"color:#98c379;\">\"action:document\"</span> <span style=\"color:#7f848e;\">// Document now/skip</span>\n | <span style=\"color:#98c379;\">\"action:cleanup\"</span> <span style=\"color:#7f848e;\">// Clean up/leave</span>\n | <span style=\"color:#98c379;\">\"action:continue\"</span> <span style=\"color:#7f848e;\">// Continue flow/start new</span>\n | <span style=\"color:#98c379;\">\"action:other\"</span> <span style=\"color:#7f848e;\">// Other action decision</span>\n \n <span style=\"color:#7f848e;\">// ─────────────────────────────────────────────────────────────</span>\n <span style=\"color:#7f848e;\">// DEFERRED DECISIONS (asked human)</span>\n <span style=\"color:#7f848e;\">// ─────────────────────────────────────────────────────────────</span>\n | <span style=\"color:#98c379;\">\"deferred:clarification\"</span> <span style=\"color:#7f848e;\">// Needed more info</span>\n | <span style=\"color:#98c379;\">\"deferred:approval\"</span> <span style=\"color:#7f848e;\">// Needed explicit approval</span>\n | <span style=\"color:#98c379;\">\"deferred:choice\"</span> <span style=\"color:#7f848e;\">// Multiple valid options</span>\n | <span style=\"color:#98c379;\">\"deferred:risk\"</span> <span style=\"color:#7f848e;\">// Too risky to decide alone</span>\n | <span style=\"color:#98c379;\">\"deferred:policy\"</span> <span style=\"color:#7f848e;\">// Policy/preference needed</span>\n | <span style=\"color:#98c379;\">\"deferred:other\"</span>; <span style=\"color:#7f848e;\">// Other reason to defer</span>\n\n<span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n<span style=\"color:#7f848e;\">// SCOPE & VISIBILITY</span>\n<span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n\n<span style=\"color:#c678dd;\">type</span> <span style=\"color:#e5c07b;\">DecisionScope</span> = \n | <span style=\"color:#98c379;\">\"turn\"</span> <span style=\"color:#7f848e;\">// Only relevant to this turn</span>\n | <span style=\"color:#98c379;\">\"flow\"</span> <span style=\"color:#7f848e;\">// Relevant to entire flow</span>\n | <span style=\"color:#98c379;\">\"project\"</span> <span style=\"color:#7f848e;\">// Project-wide convention</span>\n | <span style=\"color:#98c379;\">\"organization\"</span>; <span style=\"color:#7f848e;\">// Org-wide standard</span>\n\n<span style=\"color:#c678dd;\">type</span> <span style=\"color:#e5c07b;\">DecisionVisibility</span> = \n | <span style=\"color:#98c379;\">\"internal\"</span> <span style=\"color:#7f848e;\">// Implementation detail</span>\n | <span style=\"color:#98c379;\">\"team\"</span> <span style=\"color:#7f848e;\">// Team should know</span>\n | <span style=\"color:#98c379;\">\"stakeholder\"</span> <span style=\"color:#7f848e;\">// Stakeholders should know</span>\n | <span style=\"color:#98c379;\">\"public\"</span>; <span style=\"color:#7f848e;\">// Public documentation</span>\n\n<span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n<span style=\"color:#7f848e;\">// CONFIDENCE & ORIGIN</span>\n<span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n\n<span style=\"color:#c678dd;\">type</span> <span style=\"color:#e5c07b;\">ConfidenceLevel</span> = \n | <span style=\"color:#98c379;\">\"certain\"</span> <span style=\"color:#7f848e;\">// No doubt, clear best choice</span>\n | <span style=\"color:#98c379;\">\"high\"</span> <span style=\"color:#7f848e;\">// Pretty confident</span>\n | <span style=\"color:#98c379;\">\"medium\"</span> <span style=\"color:#7f848e;\">// Reasonable choice</span>\n | <span style=\"color:#98c379;\">\"low\"</span> <span style=\"color:#7f848e;\">// Uncertain, could be wrong</span>\n | <span style=\"color:#98c379;\">\"guess\"</span>; <span style=\"color:#7f848e;\">// Best guess, high uncertainty</span>\n\n<span style=\"color:#c678dd;\">type</span> <span style=\"color:#e5c07b;\">DecisionOrigin</span> = \n | <span style=\"color:#98c379;\">\"explicit\"</span> <span style=\"color:#7f848e;\">// Human explicitly decided</span>\n | <span style=\"color:#98c379;\">\"kontask\"</span> <span style=\"color:#7f848e;\">// From kontask approval</span>\n | <span style=\"color:#98c379;\">\"implementation\"</span> <span style=\"color:#7f848e;\">// Emerged during coding</span>\n | <span style=\"color:#98c379;\">\"discussion\"</span> <span style=\"color:#7f848e;\">// From conversation</span>\n | <span style=\"color:#98c379;\">\"convention\"</span> <span style=\"color:#7f848e;\">// Following existing pattern</span>\n | <span style=\"color:#98c379;\">\"constraint\"</span> <span style=\"color:#7f848e;\">// Forced by constraints</span>\n | <span style=\"color:#98c379;\">\"default\"</span>; <span style=\"color:#7f848e;\">// Default/fallback choice</span>\n\n<span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n<span style=\"color:#7f848e;\">// IMPACT AREAS</span>\n<span style=\"color:#7f848e;\">// ═══════════════════════════════════════════════════════════════</span>\n\n<span style=\"color:#c678dd;\">type</span> <span style=\"color:#e5c07b;\">ImpactArea</span> = \n | <span style=\"color:#98c379;\">\"code\"</span> <span style=\"color:#7f848e;\">// Source code structure</span>\n | <span style=\"color:#98c379;\">\"api\"</span> <span style=\"color:#7f848e;\">// API contracts</span>\n | <span style=\"color:#98c379;\">\"database\"</span> <span style=\"color:#7f848e;\">// Data storage</span>\n | <span style=\"color:#98c379;\">\"ui\"</span> <span style=\"color:#7f848e;\">// User interface</span>\n | <span style=\"color:#98c379;\">\"performance\"</span> <span style=\"color:#7f848e;\">// System performance</span>\n | <span style=\"color:#98c379;\">\"security\"</span> <span style=\"color:#7f848e;\">// Security posture</span>\n | <span style=\"color:#98c379;\">\"testing\"</span> <span style=\"color:#7f848e;\">// Test strategy</span>\n | <span style=\"color:#98c379;\">\"deployment\"</span> <span style=\"color:#7f848e;\">// Deployment process</span>\n | <span style=\"color:#98c379;\">\"documentation\"</span> <span style=\"color:#7f848e;\">// Documentation</span>\n | <span style=\"color:#98c379;\">\"workflow\"</span> <span style=\"color:#7f848e;\">// Development workflow</span>\n | <span style=\"color:#98c379;\">\"cost\"</span> <span style=\"color:#7f848e;\">// Resource costs</span>\n | <span style=\"color:#98c379;\">\"maintenance\"</span>; <span style=\"color:#7f848e;\">// Long-term maintenance</span>\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#c678dd;margin:0 0 12px 0;\">Computed Properties</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;\">\n<pre style=\"margin:0;line-height:1.5;color:#e0e0e0;font-size:11px;background:#1e1e1e;padding:12px;border-radius:4px;overflow-x:auto;\">\n<span style=\"color:#7f848e;\">// Status computed from timestamps (not stored)</span>\n<span style=\"color:#c678dd;\">function</span> <span style=\"color:#61afef;\">getDecisionStatus</span>(d: <span style=\"color:#e5c07b;\">gvDecision</span>): <span style=\"color:#e5c07b;\">DecisionStatus</span> {\n <span style=\"color:#c678dd;\">if</span> (d.supersededBy) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"superseded\"</span>;\n <span style=\"color:#c678dd;\">if</span> (d.category === <span style=\"color:#98c379;\">\"deferred\"</span> && !d.deferred?.resolvedAt) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"pending\"</span>;\n <span style=\"color:#c678dd;\">if</span> (d.documentedAt) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"documented\"</span>;\n <span style=\"color:#c678dd;\">if</span> (d.approvedAt) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"approved\"</span>;\n <span style=\"color:#c678dd;\">if</span> (d.reviewedAt) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"reviewed\"</span>;\n <span style=\"color:#c678dd;\">return</span> <span style=\"color:#98c379;\">\"made\"</span>;\n}\n\n<span style=\"color:#c678dd;\">type</span> <span style=\"color:#e5c07b;\">DecisionStatus</span> = \n | <span style=\"color:#98c379;\">\"pending\"</span> <span style=\"color:#7f848e;\">// Deferred, awaiting human</span>\n | <span style=\"color:#98c379;\">\"made\"</span> <span style=\"color:#7f848e;\">// Decision made, not reviewed</span>\n | <span style=\"color:#98c379;\">\"reviewed\"</span> <span style=\"color:#7f848e;\">// Human has seen it</span>\n | <span style=\"color:#98c379;\">\"approved\"</span> <span style=\"color:#7f848e;\">// Explicitly approved</span>\n | <span style=\"color:#98c379;\">\"documented\"</span> <span style=\"color:#7f848e;\">// Exported to docs</span>\n | <span style=\"color:#98c379;\">\"superseded\"</span>; <span style=\"color:#7f848e;\">// Replaced by another decision</span>\n\n<span style=\"color:#7f848e;\">// Needs attention computed</span>\n<span style=\"color:#c678dd;\">function</span> <span style=\"color:#61afef;\">needsAttention</span>(d: <span style=\"color:#e5c07b;\">gvDecision</span>): <span style=\"color:#98c379;\">boolean</span> {\n <span style=\"color:#c678dd;\">if</span> (d.category === <span style=\"color:#98c379;\">\"deferred\"</span> && !d.deferred?.resolvedAt) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#d19a66;\">true</span>;\n <span style=\"color:#c678dd;\">if</span> (d.madeBy.agent === <span style=\"color:#98c379;\">\"claude\"</span> && !d.reviewedAt) {\n <span style=\"color:#c678dd;\">if</span> (d.confidence === <span style=\"color:#98c379;\">\"low\"</span> || d.confidence === <span style=\"color:#98c379;\">\"guess\"</span>) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#d19a66;\">true</span>;\n <span style=\"color:#c678dd;\">if</span> (d.risk?.level === <span style=\"color:#98c379;\">\"high\"</span>) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#d19a66;\">true</span>;\n <span style=\"color:#c678dd;\">if</span> (d.impact.level === <span style=\"color:#98c379;\">\"critical\"</span>) <span style=\"color:#c678dd;\">return</span> <span style=\"color:#d19a66;\">true</span>;\n }\n <span style=\"color:#c678dd;\">return</span> <span style=\"color:#d19a66;\">false</span>;\n}\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#e5c07b;margin:0 0 12px 0;\">Example Instances</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;\">\n<pre style=\"margin:0;line-height:1.4;color:#e0e0e0;font-size:10px;background:#1e1e1e;padding:12px;border-radius:4px;overflow-x:auto;\">\n<span style=\"color:#7f848e;\">// Design decision example</span>\n{\n id: <span style=\"color:#98c379;\">\"dec-01HX5K3M2N4P5Q6R7S8T9U0V\"</span>,\n version: <span style=\"color:#d19a66;\">1</span>,\n flowId: <span style=\"color:#98c379;\">\"flow-gvshell-refactor\"</span>,\n turnId: <span style=\"color:#98c379;\">\"turn-abc123\"</span>,\n category: <span style=\"color:#98c379;\">\"design\"</span>,\n type: <span style=\"color:#98c379;\">\"design:architecture\"</span>,\n scope: <span style=\"color:#98c379;\">\"project\"</span>,\n visibility: <span style=\"color:#98c379;\">\"team\"</span>,\n title: <span style=\"color:#98c379;\">\"Use CLAUDE_CONFIG_DIR per-spawn instead of symlink\"</span>,\n chosen: { value: <span style=\"color:#98c379;\">\"env-var-per-spawn\"</span>, label: <span style=\"color:#98c379;\">\"Per-spawn config dir\"</span> },\n alternatives: [\n { value: <span style=\"color:#98c379;\">\"symlink-switch\"</span>, label: <span style=\"color:#98c379;\">\"Symlink switching\"</span>, whyNot: <span style=\"color:#98c379;\">\"Requires hot pool restart\"</span> }\n ],\n rationale: <span style=\"color:#98c379;\">\"Sessions can use different accounts without pool restarts\"</span>,\n madeBy: { agent: <span style=\"color:#98c379;\">\"human\"</span>, userId: <span style=\"color:#98c379;\">\"stephanie\"</span> },\n confidence: <span style=\"color:#98c379;\">\"high\"</span>,\n origin: <span style=\"color:#98c379;\">\"kontask\"</span>,\n impact: { level: <span style=\"color:#98c379;\">\"high\"</span>, areas: [<span style=\"color:#98c379;\">\"code\"</span>, <span style=\"color:#98c379;\">\"workflow\"</span>] },\n reversibility: { reversible: <span style=\"color:#d19a66;\">true</span>, cost: <span style=\"color:#98c379;\">\"moderate\"</span> },\n createdAt: <span style=\"color:#98c379;\">\"2026-01-09T01:00:00Z\"</span>\n}\n\n<span style=\"color:#7f848e;\">// Action decision example</span>\n{\n id: <span style=\"color:#98c379;\">\"dec-01HX5K3M2N4P5Q6R7S8T9U0W\"</span>,\n version: <span style=\"color:#d19a66;\">1</span>,\n flowId: <span style=\"color:#98c379;\">\"flow-gvshell-refactor\"</span>,\n turnId: <span style=\"color:#98c379;\">\"turn-abc123\"</span>,\n category: <span style=\"color:#98c379;\">\"action\"</span>,\n type: <span style=\"color:#98c379;\">\"action:test\"</span>,\n scope: <span style=\"color:#98c379;\">\"turn\"</span>,\n visibility: <span style=\"color:#98c379;\">\"internal\"</span>,\n title: <span style=\"color:#98c379;\">\"Run type check before full tests\"</span>,\n chosen: { value: <span style=\"color:#98c379;\">\"typecheck-first\"</span> },\n alternatives: [{ value: <span style=\"color:#98c379;\">\"full-test-suite\"</span>, whyNot: <span style=\"color:#98c379;\">\"Slower, type errors first\"</span> }],\n rationale: <span style=\"color:#98c379;\">\"Catch type errors quickly before longer test run\"</span>,\n madeBy: { agent: <span style=\"color:#98c379;\">\"claude\"</span>, model: <span style=\"color:#98c379;\">\"claude-opus-4-5\"</span> },\n confidence: <span style=\"color:#98c379;\">\"certain\"</span>,\n origin: <span style=\"color:#98c379;\">\"convention\"</span>,\n impact: { level: <span style=\"color:#98c379;\">\"low\"</span> },\n risk: { level: <span style=\"color:#98c379;\">\"low\"</span> },\n reversibility: { reversible: <span style=\"color:#d19a66;\">true</span>, cost: <span style=\"color:#98c379;\">\"trivial\"</span> },\n createdAt: <span style=\"color:#98c379;\">\"2026-01-09T01:15:00Z\"</span>\n}\n\n<span style=\"color:#7f848e;\">// Deferred decision example</span>\n{\n id: <span style=\"color:#98c379;\">\"dec-01HX5K3M2N4P5Q6R7S8T9U0X\"</span>,\n version: <span style=\"color:#d19a66;\">1</span>,\n flowId: <span style=\"color:#98c379;\">\"flow-gvshell-refactor\"</span>,\n turnId: <span style=\"color:#98c379;\">\"turn-abc123\"</span>,\n category: <span style=\"color:#98c379;\">\"deferred\"</span>,\n type: <span style=\"color:#98c379;\">\"deferred:choice\"</span>,\n scope: <span style=\"color:#98c379;\">\"flow\"</span>,\n visibility: <span style=\"color:#98c379;\">\"team\"</span>,\n title: <span style=\"color:#98c379;\">\"Keep or remove /accounts/switch endpoint\"</span>,\n chosen: { value: <span style=\"color:#98c379;\">\"keep-repurpose\"</span>, label: <span style=\"color:#98c379;\">\"Keep and repurpose\"</span> },\n alternatives: [{ value: <span style=\"color:#98c379;\">\"remove\"</span>, label: <span style=\"color:#98c379;\">\"Remove entirely\"</span> }],\n rationale: <span style=\"color:#98c379;\">\"UI still needs way to change default account\"</span>,\n madeBy: { agent: <span style=\"color:#98c379;\">\"claude\"</span> },\n confidence: <span style=\"color:#98c379;\">\"medium\"</span>,\n origin: <span style=\"color:#98c379;\">\"implementation\"</span>,\n deferred: {\n question: <span style=\"color:#98c379;\">\"Should we keep or remove the switch endpoint?\"</span>,\n options: [<span style=\"color:#98c379;\">\"Keep and repurpose\"</span>, <span style=\"color:#98c379;\">\"Remove entirely\"</span>],\n kontaskId: <span style=\"color:#98c379;\">\"kontask-xyz789\"</span>,\n resolvedAt: <span style=\"color:#98c379;\">\"2026-01-09T01:20:00Z\"</span>,\n resolution: <span style=\"color:#98c379;\">\"Keep - UI needs it\"</span>\n },\n impact: { level: <span style=\"color:#98c379;\">\"medium\"</span>, areas: [<span style=\"color:#98c379;\">\"api\"</span>, <span style=\"color:#98c379;\">\"ui\"</span>] },\n createdAt: <span style=\"color:#98c379;\">\"2026-01-09T01:18:00Z\"</span>\n}\n</pre>\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;\">Storage Strategy</h3>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:20px;\">\n<pre style=\"margin:0;line-height:1.6;color:#e0e0e0;font-size:12px;\">\n<span style=\"color:#7f848e;\">Files:</span>\n /data/gvdecisions.jsonl <span style=\"color:#7f848e;\">// Primary storage (append-only)</span>\n /data/gvflows.jsonl <span style=\"color:#7f848e;\">// Flows (has decisionIds[])</span>\n\n<span style=\"color:#7f848e;\">Indexes (computed on load):</span>\n byFlow: Map<flowId, Decision[]>\n byTurn: Map<turnId, Decision[]>\n byType: Map<type, Decision[]>\n needsAttn: Decision[] <span style=\"color:#7f848e;\">// Unreviewed + risky/uncertain</span>\n\n<span style=\"color:#7f848e;\">Immutability rules:</span>\n • Core fields never change after creation\n • Timestamps only added (never removed)\n • Pivots create new decision with supersedes link\n • deferred.resolvedAt/resolution added when resolved\n</pre>\n</div>\n\n<h3 style=\"font-family:sans-serif;color:#fff;margin:0 0 12px 0;\">Design Principles</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:12px;\">\n<span style=\"color:#22c55e;\">✓</span> <span style=\"color:#22c55e;\">Immutable core</span> - decisions never change, only timestamps added\n<span style=\"color:#22c55e;\">✓</span> <span style=\"color:#22c55e;\">Append-only timestamps</span> - status computed, not stored\n<span style=\"color:#22c55e;\">✓</span> <span style=\"color:#22c55e;\">Rich alternatives</span> - capture what wasn't chosen and why\n<span style=\"color:#22c55e;\">✓</span> <span style=\"color:#22c55e;\">Explicit uncertainty</span> - confidence + uncertainty fields\n<span style=\"color:#22c55e;\">✓</span> <span style=\"color:#22c55e;\">Full lineage</span> - dependsOn, supersedes, relatedTo\n<span style=\"color:#22c55e;\">✓</span> <span style=\"color:#22c55e;\">Doc pipeline ready</span> - documentation section for ADR export\n<span style=\"color:#22c55e;\">✓</span> <span style=\"color:#22c55e;\">Extensible</span> - metadata field for future needs\n<span style=\"color:#22c55e;\">✓</span> <span style=\"color:#22c55e;\">Version field</span> - enables schema migrations\n</pre>\n</div>\n\n</div>",
"requestedAt": "2026-01-09T03:10:00.000Z",
"requestId": "b6e986e0-e282-40ac-b766-44886f71b9dc",
"choices": [
{
"label": "Approve schema",
"value": "Approve this gvDecision schema as the complete specification",
"primary": true
},
{
"label": "Add more fields",
"value": "I want to add additional fields to cover more cases"
},
{
"label": "Simplify some areas",
"value": "Some areas are over-engineered, let's simplify"
},
{
"label": "Write to design doc",
"value": "Write this schema to /gv/docs/gvDecisionSchema.md as the specification"
}
],
"turnTiming": {
"totalMs": 451558,
"ttfeMs": 52,
"thinkingMs": 451506,
"toolExecutionMs": 0,
"toolCallCount": 0,
"thinkingPct": 100,
"toolsPct": 0,
"ttfePct": 0
}
},
"createdBy": "claude",
"createdAt": "2026-01-09T03:44:55.709Z",
"updatedAt": "2026-01-09T03:50:08.967Z",
"requestId": "b6e986e0-e282-40ac-b766-44886f71b9dc",
"scope": "vibetools",
"tags": [
"gvshell",
"gvhub",
"decisions",
"schema",
"specification"
],
"targetUser": "claude"
}