{ "diagnosis_timestamp": "2026-01-28T00:00:00Z", "skill_name": "skill-generator", "skill_path": "D:\\Claude_dms3\\.claude\\skills\\skill-generator", "categories": ["context", "dataflow"], "severity_summary": { "critical": 3, "high": 4, "medium": 2, "low": 1 }, "issues": [ { "id": "CTX-002", "category": "context", "severity": "critical", "title": "Full State Serialization in Agent Prompts (Unbounded Context Growth)", "description": "Generated autonomous orchestrators pass FULL state object (JSON.stringify(state, null, 2)) directly into agent prompts. This violates context budget principles and causes exponential context growth in multi-iteration workflows. Each iteration adds the complete state (including all previously completed actions, errors, context history) to the prompt, making it grow linearly with iteration count.", "location": "phases/03-phase-generation.md:582, templates/autonomous-orchestrator.md:119, templates/autonomous-action.md:248", "evidence": "In 03-phase-generation.md line 582:\n```javascript\nconst result = await Task({\n subagent_type: 'universal-executor',\n run_in_background: false,\n prompt: `\n[STATE]\n${JSON.stringify(state, null, 2)} // <-- FULL STATE serialized here\n[ACTION]\n${actionPrompt}\n...\n```\n\nIn autonomous-orchestrator.md line 119:\n```javascript\nprompt: `\n[STATE]\n${JSON.stringify(state, null, 2)} // <-- UNBOUNDED serialization\n[ACTION]\n${actionPrompt}\n```\n\nFor a 50-iteration autonomous workflow with complex context, this generates:\n- Iteration 1: state ~2KB\n- Iteration 10: state ~10KB (5x growth)\n- Iteration 50: state ~50KB (25x growth)\nTotal context spent: 50 * avg(25KB) = 1.25MB+ just on state serialization", "impact": "Generated skills will fail on multi-step workflows. Context explosion triggers:\n- Rate limiting from API\n- Token budget exhaustion\n- Unpredictable behavior\n- Skills unusable for real workflows", "root_cause": "Templates directly embed full state object without summarization, filtering, or context windowing. No distinction between:\n- Metadata needed by agent (current status, last action)\n- Historical context (previous iterations)\n- Full state (all accumulated history)", "fix_strategy": "Implement state summarization in agent prompts:\n1. **Extract only essential fields** for decision-making:\n - current_action: for state tracking\n - status: for termination checks\n - error_count: for error limits\n - last_action: for context\n EXCLUDE: full errors array, all completed_actions history, raw context data\n\n2. **For complex context**, use path references instead:\n - Instead of: `context: { items: [...1000 items...] }`\n - Use: `context_file: \"${workDir}/context/items.json\" (1000 items)`\n\n3. **Implement context windowing**:\n - Keep last N completed_actions (e.g., N=5)\n - Keep last 3 errors only\n - Archive older iterations to separate file\n\n4. **Template change in autonomous-orchestrator.md**:\n```javascript\n// BEFORE (WRONG):\nprompt: `[STATE]\\n${JSON.stringify(state, null, 2)}\\n[ACTION]...`\n\n// AFTER (CORRECT):\nconst essentialState = {\n status: state.status,\n current_action: state.current_action,\n error_count: state.error_count,\n completed_actions_count: state.completed_actions.length,\n last_completed: state.completed_actions.slice(-3),\n recent_errors: state.errors.slice(-2),\n context_summary: `${Object.keys(state.context).length} context items`\n};\nprompt: `[STATE]\\n${JSON.stringify(essentialState, null, 2)}\\n[CONTEXT_REFERENCE]\\nFull context at: ${workDir}/state.json\\n[ACTION]...`\n```" }, { "id": "DF-001", "category": "dataflow", "severity": "critical", "title": "Scattered State Writing (Multiple Files, No Schema)", "description": "Generated orchestrators write state to multiple locations with no unified schema:\n- `${workDir}/state.json` (main state)\n- `${workDir}/execution-state.json` (execution tracking)\n- `${workDir}/context/{key}.json` (file strategy context)\n- Agent results parsed but not consistently saved\n\nNo validation between writes, no conflict resolution, no version control. When state updates fail halfway through iteration, system can't detect inconsistency.", "location": "phases/03-phase-generation.md:183, 191, 229, 462, 618", "evidence": "In 03-phase-generation.md line 191:\n```javascript\nWrite(`${workDir}/execution-state.json`, JSON.stringify(execution, null, 2));\n```\nLine 229:\n```javascript\nWrite(`${workDir}/execution-state.json`, JSON.stringify(execution, null, 2));\n```\nLine 462:\n```javascript\nWrite(`${workDir}/state.json`, JSON.stringify(state, null, 2));\n```\nLine 618:\n```javascript\nContextManager.writeState(workDir, state);\n```\n\nNo unified write pattern. Context Manager may write to:\n- File: `${workDir}/state.json` + `${workDir}/context/*.json`\n- Memory: in-memory state object\n\nNo transaction semantics, no atomic updates, no rollback.", "impact": "Generated skills have silent data corruption:\n- Partial state updates (write 1 succeeds, write 2 fails)\n- Orphaned context files\n- Inconsistent state across resume/retry\n- Debugging impossible (which file is source of truth?)", "root_cause": "Template generates multiple write operations scattered throughout orchestrator loop without centralized state management. File strategy and memory strategy both have separate write paths. No schema validation.", "fix_strategy": "Implement unified state management:\n1. **Single write endpoint** - Create StateManager abstraction:\n```javascript\nconst StateManager = {\n write: (workDir, state) => {\n // Atomic write to single file\n const tmpFile = `${workDir}/state.json.tmp`;\n Write(tmpFile, JSON.stringify(state, null, 2));\n // Validate before committing\n const written = JSON.parse(Read(tmpFile));\n if (written.version !== expectedVersion) throw Error('validation failed');\n Bash(`mv ${tmpFile} ${workDir}/state.json`);\n },\n read: (workDir) => JSON.parse(Read(`${workDir}/state.json`))\n};\n```\n\n2. **Unified write calls** - Replace scattered writes:\n- Remove execution-state.json (track in state.json instead)\n- All context writes go through StateManager\n- All agent results update via StateManager\n\n3. **Add schema validation**:\n```javascript\nconst STATE_SCHEMA = {\n version: '1.0',\n required: ['status', 'completed_actions', 'error_count'],\n updated_at: 'ISO8601',\n metadata: { iteration: 'number' }\n};\n```\n\n4. **Template change**:\nReplace all scattered writes with:\n```javascript\nStateManager.write(workDir, {\n ...state,\n completed_actions: [...state.completed_actions, actionId],\n updated_at: new Date().toISOString()\n});\n```" }, { "id": "DF-005", "category": "dataflow", "severity": "critical", "title": "Autonomous Orchestrator Lacks Input State Schema Validation", "description": "Generated autonomous orchestrators assume state.json exists and has expected structure, but never validate it. If state file is corrupted, missing fields, or created by external process, orchestrator proceeds blindly. No type checking on state object before using in decision logic.\n\nFunction `selectNextAction(state)` references fields like `state.status`, `state.error_count`, `state.completed_actions` without checking existence. This is unsafe for skills that might be resumed after state corruption.", "location": "phases/03-phase-generation.md:501-522, templates/autonomous-orchestrator.md:64-78", "evidence": "In 03-phase-generation.md line 554:\n```javascript\nconst state = ContextManager.readState(workDir);\nconsole.log(`[Iteration ${iteration}] Status: ${state.status}, Completed: ${state.completed_actions.length}`);\n// ^ No validation that state.status or state.completed_actions exist\n```\n\nLine 558:\n```javascript\nconst actionId = selectNextAction(state);\n// selectNextAction immediately accesses state.status without guards\n```\n\nIn selectNextAction (line 508):\n```javascript\nif (state.status === \"completed\") return null; // No null check\nif (state.error_count >= 3) ... // Assumes error_count exists\nconst availableActions = ACTION_CATALOG\n .filter(a => checkPreconditions(a.preconditions, state)) // state passed unchecked\n .sort((a, b) => b.priority - a.priority);\n```\n\nNo defensive checks like:\n```javascript\nif (!state || typeof state !== 'object') throw Error('Invalid state');\nif (!Array.isArray(state.completed_actions)) state.completed_actions = [];\n```", "impact": "Generated skills fail silently or crash on:\n- Corrupted state files\n- Partial resume after crash\n- State files edited manually\n- Version mismatches\n\nHard to debug: user sees cryptic errors (Cannot read property 'length' of undefined) rather than 'State file missing field: completed_actions'", "root_cause": "Template generator assumes ideal conditions. No defensive programming in generated code. No state schema versioning or migration path.", "fix_strategy": "Add state validation layer:\n\n1. **Define state schema in generated code**:\n```javascript\nconst DEFAULT_STATE = {\n status: 'pending',\n completed_actions: [],\n error_count: 0,\n errors: [],\n context: {},\n current_action: null,\n started_at: new Date().toISOString(),\n updated_at: new Date().toISOString()\n};\n\nfunction validateState(state) {\n if (!state || typeof state !== 'object') return DEFAULT_STATE;\n \n return {\n status: state.status || 'pending',\n completed_actions: Array.isArray(state.completed_actions) ? state.completed_actions : [],\n error_count: typeof state.error_count === 'number' ? state.error_count : 0,\n errors: Array.isArray(state.errors) ? state.errors : [],\n context: typeof state.context === 'object' ? state.context : {},\n current_action: state.current_action || null,\n started_at: state.started_at || new Date().toISOString(),\n updated_at: new Date().toISOString()\n };\n}\n```\n\n2. **Use validator on every read**:\n```javascript\nconst state = validateState(ContextManager.readState(workDir));\n```\n\n3. **Update template in autonomous-orchestrator.md** to include validation in Execution Loop section" }, { "id": "DF-002", "category": "dataflow", "severity": "high", "title": "Same Concept, Different Names (State vs Context Confusion)", "description": "Generated code uses overlapping terminology causing ambiguity:\n- `state.context` - arbitrary key-value storage for business data\n- `state` - entire execution state object\n- File strategy: `${workDir}/context/{key}.json` (separate files)\n- Memory strategy: `state.context` property\n\nCode mixing these produces bugs:\n- Action tries to read `state.context.items` (memory) but file strategy stored it in `${workDir}/context/items.json`\n- No clear contract about what 'context' means: business data? execution context? file directory?\n- Line 582 serializes full `state` including `state.context`, but line 679 tries to write context separately", "location": "phases/03-phase-generation.md:582, 674-686, 703-706", "evidence": "Line 582 in 03-phase-generation.md:\n```javascript\nprompt: `\n[STATE]\n${JSON.stringify(state, null, 2)} // state.context is here\n...\n```\n\nLine 679-680:\n```javascript\nconst sharedData = JSON.parse(Read(`${workDir}/context/shared.json`));\n// File strategy: context stored separately\n```\n\nLine 683:\n```javascript\nWrite(`${workDir}/context/shared.json`, JSON.stringify(updatedData, null, 2));\n// Writes to file, not to state.context\n```\n\nLine 703-706:\n```javascript\nconst input = JSON.parse(Read(`${workDir}/context/input.json`));\n// Action reads from context/ directory\n```\n\nLine 713:\n```javascript\nstate.context.shared = updatedData; // But state also has context property\n// Now state.context.shared has different data than ${workDir}/context/shared.json\n```\n\nFor file strategy, there's a mismatch:\n- Template shows both writing to `state.context` (line 713) AND `${workDir}/context/*.json` (line 705)\n- These are TWO SEPARATE STORAGE LOCATIONS for the same data\n- When next iteration reads state, it sees old data from state.context\n- But persistent layer has new data in ${workDir}/context/shared.json\n- Inconsistency!", "impact": "Generated skills have subtle data corruption:\n- File strategy: persistent state diverges from in-memory state\n- Memory strategy: code tries to write files that don't exist\n- Resume after crash: recovered state has stale context data\n- Race conditions between file and memory layers", "root_cause": "Template tries to support both file and memory strategies with same code, but they have fundamentally different data models. No clear separation of concerns. Template comments even indicate confusion ('文件策略：结果已保存到文件' vs state.context writes).", "fix_strategy": "Clarify separation between state and context:\n\n1. **Rename for clarity**:\n```javascript\n// state = execution metadata (status, completed_actions, errors)\n// businessData = actual business objects (items, results, etc.)\n\n// NOT: state.context = { items: [...], results: {...} }\n// YES: businessData = { items: [...], results: {...} }\n```\n\n2. **File strategy - separate storage**:\n```javascript\nconst StateManager = {\n readState: (workDir) => JSON.parse(Read(`${workDir}/state.json`)),\n readBusinessData: (workDir) => JSON.parse(Read(`${workDir}/business-data.json`)),\n writeState: (workDir, state) => Write(`${workDir}/state.json`, ...),\n writeBusinessData: (workDir, data) => Write(`${workDir}/business-data.json`, ...)\n};\n```\n\n3. **Memory strategy - single object**:\n```javascript\nconst runtime = {\n state: { status, completed_actions, errors, ... },\n businessData: { items, results, ... }\n};\n```\n\n4. **Template update**: Never nest businessData inside state\n```javascript\n// BEFORE (confusing):\nreturn {\n stateUpdates: {\n context: { ...state.context, items: [...] } // Context nested in state\n }\n};\n\n// AFTER (clear):\nreturn {\n stateUpdates: { ... }, // Only execution metadata\n businessDataUpdates: { items: [...] } // Separate\n};\n```" }, { "id": "CTX-001", "category": "context", "severity": "high", "title": "Unbounded History Array Growth in Autonomous Mode", "description": "The `state.completed_actions` array grows monotonically with no limit. In autonomous workflows that repeat actions in loops (e.g., issue-manage with LIST/CREATE/EDIT cycles), this array will accumulate all 1000+ completed action IDs, increasing state file size and prompt context linearly.\n\nNo windowing, no summarization, no cleanup mechanism. After 100 iterations of LIST action, `state.completed_actions` contains 100 'action-list' entries, all serialized in every subsequent prompt.", "location": "phases/03-phase-generation.md:513-514, 601, templates/autonomous-orchestrator.md:134", "evidence": "In 03-phase-generation.md line 601:\n```javascript\nstate.completed_actions.push(actionId);\n```\nNo limit, no dedup, no cleanup.\n\nLine 513-514:\n```javascript\nconst availableActions = ACTION_CATALOG\n .filter(a => !state.completed_actions.includes(a.id))\n // This filters all 100+ completed 'action-list' entries\n```\n\nLine 582 serializes it:\n```javascript\nprompt: `[STATE]\\n${JSON.stringify(state, null, 2)} // includes massive completed_actions array\n```\n\nFor issue-manage skill with 100+ iterations:\n```javascript\n\"completed_actions\": [\n \"action-list\",\n \"action-create\",\n \"action-list\",\n \"action-create\",\n \"action-list\",\n \"action-list\", // ... repeated 94 more times = ~3KB of repeated strings\n]\n```\n\nPrompt grows by 30B per iteration × 100 iterations = 3KB just for this array, plus serialization overhead.", "impact": "Long-running autonomous skills become impossible:\n- After 50 iterations: state file 30KB+\n- After 200 iterations: state file 100KB+ (token budget issues)\n- Comparison overhead: `.filter(a => !state.completed_actions.includes(a.id))` becomes O(n) slow\n- Serialization and parsing overhead increases", "root_cause": "Template treats completed_actions as persistent log (append-only), not as ephemeral working state. No cleanup, no summarization, no windowing mechanism.", "fix_strategy": "Implement history management:\n\n1. **Keep only recent window** (e.g., last 10 actions):\n```javascript\nstate.completed_actions = [\n ...state.completed_actions.slice(-10),\n actionId\n].slice(0, 10); // Keep only last 10\n```\n\n2. **Separate concerns** - count vs history:\n```javascript\nstate = {\n status: '...',\n action_count: 153, // Just the number\n last_actions: ['action-list', 'action-create', ...], // Last 5 only\n action_types_completed: { 'action-list': 50, 'action-create': 43, ... } // Summary\n};\n```\n\n3. **Archive to separate file** if full history needed:\n```javascript\nfunction logCompletedAction(workDir, actionId) {\n // Add to in-memory window\n state.last_actions = [...state.last_actions, actionId].slice(-5);\n state.action_count++;\n \n // Append to persistent log (separate file, not serialized in state)\n const log = Read(`${workDir}/action-log.json`) ? \n JSON.parse(Read(`${workDir}/action-log.json`)) : [];\n log.push({ action: actionId, timestamp: Date.now() });\n Write(`${workDir}/action-log.json`, JSON.stringify(log));\n}\n```\n\n4. **Template change in orchestrator**:\nRemove unbounded append, use windowing instead." }, { "id": "DF-004", "category": "dataflow", "severity": "high", "title": "Files Written But Never Read (Orphaned Outputs)", "description": "Generated templates write multiple files that may never be read:\n- `${workDir}/final-output.json` (line 248 in autonomous-action.md) - written but no orchestrator reads it\n- `${workDir}/action-log.json` (mentioned in action catalog) - written but no error recovery reads it\n- Context files like `${workDir}/context/{action.id}_result.json` (line 705) - written but how is it retrieved?\n- `${workDir}/execution-state.json` (line 183, 191, 229) - updated but never read back\n\nNo coherent file contract: what files exist? Which are write-only? Which are read-write? No manifest or registry.", "location": "templates/autonomous-action.md:248, phases/03-phase-generation.md:183, 705, 640", "evidence": "In autonomous-action.md line 248:\n```javascript\nWrite(`${workDir}/final-output.json`, JSON.stringify(state.context, null, 2));\n// Orchestrator never reads this\n```\n\nIn 03-phase-generation.md line 183:\n```javascript\nWrite(`${workDir}/execution-state.json`, JSON.stringify(execution, null, 2));\n// Written for tracking, but later code reads from state.json, not execution-state.json\n// So this file is orphaned\n```\n\nLine 705:\n```javascript\nWrite(`${workDir}/context/${action.id.replace(/-/g, '_')}_result.json`, \n JSON.stringify(result, null, 2));\n// Where is this file read? No action reads action-{x}_result.json\n```\n\nLine 640:\n```javascript\nreturn runOrchestrator(workDir);\n// Orchestrator resumes, but doesn't read previous final-output.json\n```", "impact": "Generated skills waste storage and create confusion:\n- Operators don't know which files are important\n- Cleanup scripts can't distinguish outputs from temp files\n- Disk usage grows unnecessarily\n- State recovery uncertain (which files matter?)\n- No audit trail of what was actually used", "root_cause": "Templates generate file writes opportunistically without planning consumption. No 'file contract' specifying what gets written and who reads it. No manifest file.", "fix_strategy": "Implement file manifest:\n\n1. **Create FILE_MANIFEST in generated code**:\n```javascript\nconst FILE_MANIFEST = {\n 'state.json': { \n type: 'state',\n read_by: ['orchestrator'],\n write_by: ['orchestrator'],\n retention: 'lifecycle',\n description: 'Primary execution state, required for resume'\n },\n 'final-output.json': {\n type: 'output',\n read_by: ['none - final artifact only'],\n write_by: ['action-complete'],\n retention: 'permanent',\n description: 'Final skill output, delivered to user'\n },\n 'context/{key}.json': {\n type: 'context',\n read_by: ['actions with file strategy'],\n write_by: ['actions with file strategy'],\n retention: 'lifecycle',\n description: 'Shared business data (file strategy only)'\n }\n};\n```\n\n2. **Validate writes against manifest**:\n```javascript\nfunction writeFile(path, data, type) {\n const entry = FILE_MANIFEST[path];\n if (!entry) throw new Error(`Unregistered file: ${path}`);\n Write(path, data);\n logFileOperation(path, 'write', type);\n}\n```\n\n3. **Eliminate orphaned files**:\n- Remove `execution-state.json` (use state.json for everything)\n- Remove `final-output.json` (return via stateUpdates)\n- Remove action result files (keep in state.context)\n\n4. **Document file contract in generated spec**:\nAdd to specs/action-catalog.md or SKILL.md" }, { "id": "DF-003", "category": "dataflow", "severity": "high", "title": "JSON.parse Without Validation", "description": "Generated code uses `JSON.parse()` in 6+ locations without try-catch or schema validation:\n- Line 42: `const config = JSON.parse(Read(...))` - no validation\n- Line 554: `const state = ContextManager.readState(workDir)` → `JSON.parse(Read(${workDir}/state.json))` - no validation\n- Line 598: `const actionResult = JSON.parse(result)` - agent result unchecked\n- Line 658: `const state = JSON.parse(Read(...))` - resume state unchecked\n\nIf any JSON file is corrupted or partially written, `JSON.parse` throws cryptic error, crashing orchestrator with no recovery path.", "location": "phases/03-phase-generation.md:42, 554, 598, 658, 738", "evidence": "Line 554:\n```javascript\nconst state = ContextManager.readState(workDir);\n// Inside ContextManager:\n// readState: () => JSON.parse(Read(`${workDir}/state.json`))\n// No try-catch, no validation\n```\n\nLine 598:\n```javascript\nconst actionResult = JSON.parse(result);\n// 'result' is from agent, could be invalid JSON\n// If agent returns incomplete JSON, this crashes\n```\n\nLine 658:\n```javascript\nconst state = ContextManager.readState(workDir);\n// During resume, if state.json is corrupted, crashes with:\n// \"Unexpected token < in JSON at position 0\" (uninformative)\n```", "impact": "Any file corruption causes catastrophic failure:\n- State file partially written due to crash → cannot resume\n- Agent returns malformed JSON → orchestrator crashes\n- Manual edit introduces syntax error → skill terminates\n- Error message: 'Unexpected token...' doesn't tell user which file is bad\n\nNo graceful degradation, no partial recovery.", "root_cause": "Template doesn't include defensive parsing. Treats JSON operations as infallible. No error boundaries.", "fix_strategy": "Add defensive parsing:\n\n1. **Safe parse wrapper**:\n```javascript\nfunction safeJsonParse(jsonString, defaultValue = null, context = '') {\n try {\n return JSON.parse(jsonString);\n } catch (error) {\n console.error(`JSON parse error in ${context}: ${error.message}`);\n console.error(`Input (first 200 chars): ${jsonString.substring(0, 200)}`);\n if (defaultValue !== null) {\n console.warn(`Returning default value for ${context}`);\n return defaultValue;\n }\n throw new Error(`Failed to parse JSON in ${context}: ${error.message}`);\n }\n}\n```\n\n2. **Use throughout generated code**:\n```javascript\n// BEFORE:\nconst state = ContextManager.readState(workDir);\n\n// AFTER:\nconst state = safeJsonParse(\n Read(`${workDir}/state.json`),\n DEFAULT_STATE,\n 'state.json during iteration ' + iteration\n);\n```\n\n3. **For agent results**:\n```javascript\ntry {\n const actionResult = safeJsonParse(result, null, 'action result');\n if (!actionResult) {\n console.error('Action returned invalid JSON');\n state.error_count++;\n continue;\n }\n} catch (error) {\n state.errors.push(...);\n continue;\n}\n```\n\n4. **Template update**: Add safeJsonParse to generated orchestrator preamble" }, { "id": "CTX-003", "category": "context", "severity": "medium", "title": "Multiple File Content Concatenation in Context", "description": "Sequential mode templates may concatenate full file contents for context passing between phases. When phase outputs are markdown files (like 5000+ character documents), these get embedded in phase prompts without summarization.\n\nLine 334 in 03-phase-generation.md reads previous phase output:\n```javascript\nconst prevOutput = JSON.parse(Read(`${workDir}/${params.input}`));\n```\n\nThis output is then passed to next phase as context, and next phase may serialize it into its prompt to agent. If output is large (5000+ chars), context bloat occurs.", "location": "phases/03-phase-generation.md:312-313, 344", "evidence": "In 03-phase-generation.md line 344:\n```javascript\n${params.phaseNumber > 1 ? contextCode.readPrev : '// 首阶段，直接从配置开始'}\n```\n\nTemplate assumes prev output fits in context. For software-manual skill that generates 20KB+ HTML, this becomes a problem:\n- Phase 1 generates 20KB manual HTML → output1.json\n- Phase 2 reads it: `const prevOutput = JSON.parse(Read(...output1.json...))` → 20KB in memory\n- Phase 2 prompt serializes this context → 20KB in prompt\n- Phase 3 reads Phase 2 output, which includes Phase 1 output → 40KB cumulative\n\nNo summarization flag, no size check, no content filtering.", "impact": "Sequential skills that process large artifacts (documents, code, reports) hit context limits:\n- Multi-phase document generation:\n - Phase 1: collect (1KB) → OK\n - Phase 2: analyze (5KB) → OK \n - Phase 3: generate (10KB) → OK\n - Phase 4: review (passes all previous) → 16KB → OK\n - Phase 5: finalize (passes all) → 32KB → Context budget exhausted\n\n- No way to drop old phases' work\n- No way to summarize intermediate results", "root_cause": "Templates pass full state linearly through phases without filtering or summarization. Assumes all outputs are small enough.", "fix_strategy": "Add context management for sequential mode:\n\n1. **Implement output summarization for large files**:\n```javascript\nfunction readPhaseOutput(filePath, maxSize = 2000) {\n const content = Read(filePath);\n const parsed = JSON.parse(content);\n \n if (typeof parsed === 'string' && parsed.length > maxSize) {\n return {\n type: 'large_content',\n size: parsed.length,\n preview: parsed.substring(0, maxSize) + '... [truncated]',\n path: filePath,\n note: 'Full content available at: ' + filePath\n };\n }\n return parsed;\n}\n```\n\n2. **Use path references instead of full content**:\n```javascript\n// BEFORE:\nconst prevOutput = JSON.parse(Read(`${workDir}/${params.input}`));\n// Agent sees full content\n\n// AFTER:\nconst prevOutput = {\n file_path: `${workDir}/${params.input}`,\n size_bytes: getFileSize(`${workDir}/${params.input}`),\n summary: 'Generated output from Phase ' + (params.phaseNumber - 1),\n preview: readPhaseOutput(`${workDir}/${params.input}`, 500).preview\n};\n```\n\n3. **Add phase output contract to template**:\nEach phase should return `{ summary, key_points, data_path }` instead of full content.\n\n4. **Template update in sequential-phase.md**:\nDocument how to return results with summarization" }, { "id": "CTX-004", "category": "context", "severity": "medium", "title": "Agents Return Full Content Instead of Paths/Summaries", "description": "Generated action templates show agents returning full content. Line 594 in 03-phase-generation.md returns full stateUpdates:\n```javascript\nreturn {\n status: 'completed',\n stateUpdates: { // Agent populates this with full data\n context: { ...state.context, items: [...], results: {...} }, // All data\n summary: 'xxx' // Just summary\n }\n};\n```\n\nIf `items` array contains 100 complex objects (like 100 github issues), agent serializes all 100 into JSON response, which gets parsed and re-serialized into prompt for next iteration. This is inefficient and grows context.", "location": "templates/autonomous-action.md:199-208, phases/03-phase-generation.md:594", "evidence": "In autonomous-action.md lines 199-208:\n```javascript\nreturn {\n stateUpdates: {\n context: {\n ...state.context,\n items: [...(state.context.items || []), newItem] // Entire items array returned\n },\n last_action: 'create'\n }\n};\n```\n\nAgent returns full context including all items, orchestrator receives it:\n```javascript\nconst actionResult = JSON.parse(result);\nObject.assign(state, actionResult.stateUpdates || {});\n// state.context.items now has all 100 items, serialized in prompt next iteration\n```\n\nIf each item is 500B, 100 items = 50KB just for this field, repeated in every prompt.", "impact": "Generated autonomous skills become inefficient:\n- Long-running issue-manage skill: after 50 CREATE/EDIT operations, context bloat\n- Code analysis skill: after collecting 100 files, returning all in state\n- No partial updates\n- No delta encoding", "root_cause": "Template shows agents returning full stateUpdates without guidance on what to include. No distinction between:\n- Transient data (agent working memory)\n- Persistent data (must be in state)\n- Large collections (should use path references)", "fix_strategy": "Guide agents to return minimal updates:\n\n1. **Template shows correct pattern**:\n```javascript\n// BEFORE (returns full state):\nreturn {\n stateUpdates: {\n context: { ...state.context, items: [...full array...] }\n }\n};\n\n// AFTER (returns only what changed):\nreturn {\n stateUpdates: {\n last_action: 'create',\n last_action_time: Date.now(),\n items_count: state.context.items.length + 1,\n // NOT: full items array\n },\n output_note: 'New item saved. Full state in ' + workDir + '/state.json'\n};\n```\n\n2. **For large collections, use file storage**:\n```javascript\n// If items array is large:\nif (Array.isArray(state.context.items) && state.context.items.length > 10) {\n // Save to file, return path\n Write(`${workDir}/items.json`, JSON.stringify(state.context.items, null, 2));\n return {\n stateUpdates: {\n items_file: `${workDir}/items.json`,\n items_count: state.context.items.length\n }\n };\n}\n```\n\n3. **Document in template**:\nAdd section: 'Returning Minimal Updates' with examples" }, { "id": "CTX-005", "category": "context", "severity": "low", "title": "No Content Size Checks Before Serialization", "description": "Templates serialize objects without checking size. If `state.context` contains large data (>5000 chars), `JSON.stringify(state)` can produce 50KB+ output that gets embedded in prompts. No warnings or safeguards.", "location": "phases/03-phase-generation.md:582, templates/autonomous-orchestrator.md:119", "evidence": "Line 582:\n```javascript\nprompt: `\n[STATE]\n${JSON.stringify(state, null, 2)} // No size check\n```\n\nNo defensive check like:\n```javascript\nconst stateSize = JSON.stringify(state).length;\nif (stateSize > 10000) {\n console.warn(`WARNING: State size ${stateSize} bytes may cause context issues`);\n}\n```", "impact": "Skills can unknowingly hit context limits. No warning until failure. Operators can't debug 'why does skill suddenly fail on iteration 47?'", "root_cause": "Template doesn't include observability. No metrics or checks for context health.", "fix_strategy": "Add context monitoring:\n\n1. **Track state size per iteration**:\n```javascript\nconst stateJson = JSON.stringify(state);\nconst stateSize = stateJson.length;\nconsole.log(`[Iteration ${iteration}] State size: ${(stateSize/1024).toFixed(1)}KB`);\n\nif (stateSize > 50000) {\n console.warn('⚠️ WARNING: State exceeds 50KB, context may be limited');\n}\n```\n\n2. **Return from orchestrator template**:\nAdd state size tracking to the generated code." } ], "summary": { "context_management": "CRITICAL - Full state serialization in agent prompts causes unbounded context growth. Templates directly embed `JSON.stringify(state, null, 2)` without filtering or summarization. Multi-iteration workflows (50+) will exhaust context budgets. History array (`completed_actions`) grows unbounded, with no windowing or cleanup. Large files in sequential phases get concatenated without size checks.", "data_flow": "CRITICAL - State management is scattered across 4+ files with no unified schema or atomic updates. State validation is missing entirely. Same concepts have different names (state.context vs context/ files), causing data flow confusion. Files are written but never read (orphaned outputs). JSON parsing is unsafe, with no error handling for corrupted files.", "recommendations_priority": [ "P0 (URGENT): Fix CTX-002 - Implement state summarization in agent prompts. Remove full state serialization, use only essential fields + path references", "P0 (URGENT): Fix DF-001 - Unify state management. Single write endpoint with schema validation. Remove execution-state.json and scattered writes", "P0 (URGENT): Fix DF-005 - Add state validation layer. Generated orchestrators must validate state before using. Handle corrupted/missing fields gracefully", "P1 (HIGH): Fix DF-002 - Clarify state vs context distinction. Separate execution state from business data", "P1 (HIGH): Fix CTX-001 - Implement history windowing. Keep only last N completed_actions, not all", "P1 (HIGH): Fix DF-003 - Add safe JSON parsing. Wrap all JSON.parse with try-catch and schema validation", "P2 (MEDIUM): Fix CTX-003 - Implement output summarization for sequential phases. Don't concatenate large files", "P2 (MEDIUM): Fix CTX-004 - Teach agents to return only deltas, not full state", "P3 (LOW): Fix DF-004 - Create file manifest to eliminate orphaned outputs", "P3 (LOW): Fix CTX-005 - Add state size monitoring and warnings" ], "impact_assessment": "The skill-generator produces skills that will FAIL in production multi-agent workflows with >10 iterations or complex context. Context explosion is inevitable in autonomous mode. Data corruption is likely when state updates are interrupted. Resume/recovery is unreliable due to validation gaps and scattered state. These are not edge cases - they're guaranteed failures for any realistic long-running skill." } }