Bugfix: How to fix systemic prompt-vs-type mismatches across ANALYZE...

Documentation for Sessions

🐛 Bugfix: How to fix systemic prompt-vs-type mismatches across ANALYZE...

Date: 2026-02-23
Time: 18:59:43 UTC
Session: gspace1-138.10
Agent: architecture
Confidence: 96%
Status: ✅ Documented

📋 Decision Context

Question:

How to fix systemic prompt-vs-type mismatches across ANALYZE, DECOMPOSE, and PLAN phases that cause runtime crashes?

Task: S138 fix systemic prompt-vs-type mismatches

🎯 Decision Made

Chosen:

Added normalizer functions (normalizeAnalyzeResult, normalizeDecomposeResult, normalizePlanResult) that map LLM output shape to TypeScript expected shape, applied in each phase after parseJsonResponse()

Options Considered:

  1. Fix types to match prompts (change TypeScript interfaces)
  2. Fix prompts to match types (rewrite LLM prompt templates)
  3. Add normalizer/adapter functions between LLM output and TypeScript types

💭 Reasoning

The root cause is that prompt templates were written independently from TypeScript type definitions, creating 13 field mismatches across 3 phases. The normalizer approach is most robust because: (1) it handles both the LLM shape and the TypeScript shape (idempotent — if the LLM format changes, normalizers still work), (2) it doesn't modify working prompts (ENHANCE and ANALYZE already complete successfully with current prompts), (3) it's explicit, testable, and documents the mapping in one place, (4) it matches the pattern already established for enhancedPrompt (getEnhancedPromptTitle, serializeEnhancedPrompt). Specific mappings: ANALYZE: roles[]→role, attributes→fields, object steps→string[], object NFRs→string[]. DECOMPOSE: priority number→enum, per-module deps→DependencyMap, from/to→fromModule/toModule. PLAN: {phases:[]}→flat array, navigation→navigationStructure, moduleId→moduleName, estimatedDuration→estimatedComplexity.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation