AI Migration Patterns - Core Architectural Philosophies

Section 1: The "Reduce and Delegate" (R&D) Philosophy

The central challenge in production-grade agentics is not context size but context management. Large, bloated contexts lead to the "lost-in-the-middle" problem, where models ignore instructions buried deep in the context, resulting in catastrophic unreliability.

The solution is the "Reduce and Delegate" (R&D) philosophy:

"Reduce": Actively shrink the context window by removing static, token-heavy "how-to" knowledge from prompts (e.g., "how to parse a 10,000-line Godot scene file").

"Delegate": Move that complex "how-to" knowledge into deterministic, executable Python code, and "Delegate" the entire complex task to that reliable tool.

Practical Implementation

• When faced with complex parsing tasks, don't try to explain the algorithm in natural language
• Instead, create a deterministic Python script and delegate the execution
• The skill's SKILL.md acts as the semantic interface, not the implementation
• The GodotProject class provides the deterministic backend methods

Economic Benefits

• Token Efficiency: Reserve expensive context for high-value reasoning, not procedural details
• Reliability: Replace volatile prompt instructions with 100% reliable Python implementations
• Performance: Scripts execute without context window constraints
• Maintainability: Code can be versioned, tested, and debugged independently

Section 2: The "Gold Standard" (GodotProject Wrapper)

All executable skills are methods on a unified GodotProject Python class. This de-risks execution by encapsulating complex logic in a single, coherent API.

Key Principles

• Unified Interface: All skills access project data through the same class
• Deterministic Execution: Every method returns structured, predictable results
• Error Handling: Centralized error handling with structured JSON output
• State Management: Consistent state across all skill operations

Example Pattern

# Instead of explaining how to parse a POF file:
project = GodotProject("/path/to/project")
metadata = project.parse_pof("models/scimitar.pof")  # Returns structured JSON

# Instead of explaining how to run tests:
results = project.run_tests()  # Returns structured test results

Section 3: The "Automated Remediation Loop"

This is the core "agentic immune system" pattern that ensures self-correcting behavior.

The Loop Process

1. Implementation: An "Engineer" agent implements a task using skills
2. Validation: A "QA" agent validates the task using deterministic skills (run_gdlint, run_gdunit4_tests)
3. Structured Failure Data: Skills return structured JSON/ XML data, not raw text
4. Feedback Integration: Orchestration hooks append structured failure data to task Markdown files
5. Remediation: The original Engineer agent is re-invoked on the same file with explicit, structured instructions to fix specific failures

Critical Requirements

• Structured Output: Validation skills must return JSON, not text
• Explicit Instructions: Feedback must be specific and actionable
• File Persistence: Task state is maintained in Markdown files with YAML frontmatter
• Agent Continuity: Same agent that implements fixes the failures

Example Feedback Integration

## Feedback

### GDLint Violations (2 errors)
```json
[
  {
    "filepath": "res://scripts/ship_controller.gd",
    "line": 42,
    "error": "Variable 'target_pos' not typed",
    "rule": "typing-required",
    "suggestion": "Add type annotation: var target_pos: Vector3"
  }
]

GDUnit4 Test Failures (1 error)

[
  {
    "test_name": "test_ship_rotation",
    "message": "Expected rotation of 90 degrees, got 85 degrees",
    "stack_trace": "res://scripts/test_ship_controller.gd:25",
    "file": "scripts/ship_controller.gd",
    "line": 67,
    "automated_fix_possible": true
  }
]

## Section 4: Skill Type Architecture

### Type 1 Skills: Model-Invoked ("The Brain")
**Purpose**: Knowledge injection for stochastic reasoning tasks
**Characteristics**:
- Task requires interpretation or judgment
- Multiple valid outcomes possible
- Domain expertise and pattern recognition needed
- Creative or analytical thinking required

**Examples**:
- Code style validation ("Does this follow Godot conventions?")
- Architectural review ("Is this design pattern appropriate?")
- Migration strategy analysis

### Type 2 Skills: Executable ("The Hands")
**Purpose**: Deterministic automation for repetitive tasks
**Characteristics**:
- Task is deterministic with clear right/wrong outcomes
- Same input should always produce same output
- Complex logic that would bloat context windows
- Integration with external systems or file formats

**Examples**:
- File parsing (`parse-pof`, `parse-tbl`)
- Code generation (`generate-resource`, `generate-importer`)
- Validation (`run-gdlint`, `run-gdunit4-tests`)

## Section 5: Progressive Disclosure Design

Skills implement a three-tier loading system:

### Tier 1: Metadata Layer (Always Loaded)
- **Scope**: YAML frontmatter only (~100 tokens)
- **Purpose**: Semantic matching for skill invocation
- **Content**: `name`, `description`, `command`, `version`

### Tier 2: Knowledge Layer (Conditionally Loaded)
- **Scope**: SKILL.md body (<5k words)
- **Purpose**: Procedural knowledge and workflow guidance
- **Trigger**: Semantic match with user prompt

### Tier 3: Resource Layer (On-Demand Loading)
- **Scope**: Bundled resources (unlimited size)
- **Purpose**: Detailed reference material and executable code
- **Mechanism**: Scripts execute, references load as needed

## Section 6: Implementation Guidelines

### When to Apply This Philosophy
- **Complex Parsing**: Binary file formats (.pof), large text files (.tbl)
- **Code Generation**: Creating complex GDScript structures
- **Asset Processing**: 3D model conversion, texture processing
- **Validation**: Linting, testing, quality assurance

### What to "Reduce" (Move from Context to Code)
- File format specifications and parsing algorithms
- Complex algorithms (BSP tree traversal, XML parsing)
- Build system knowledge and dependency management
- Testing framework setup and JUnit XML parsing
- Error handling patterns and validation logic

### What to "Delegate" (Move to Isolated Execution)
- Parsing scripts with proper error handling
- Code generation with template systems
- Build automation with proper dependency management
- Test execution with structured output parsing
- Asset conversion with proper validation

## Section 7: Agent Roles and Responsibilities

### Migration Architect
- **Reduces**: Complex analysis questions to structured plans
- **Delegates**: Parsing tasks to GodotProject methods
- **Output**: Structured plans (JSON) for other agents
- **Skills**: `parse-pof`, `parse-tbl`, `godot-parser`

### Engineer Agents (GDScriptEngineer, AssetPipelineEngineer)
- **Implement**: Use deterministic skills to create assets
- **Delegate**: Complex generation tasks to Python scripts
- **Handle**: Structured feedback from QA agents
- **Skills**: `generate-resource`, `generate-importer`, `convert-pof-to-glb`

### QA Engineer
- **Execute**: Deterministic validation skills
- **Return**: Structured failure data (JSON/XML)
- **Enable**: The remediation loop through proper reporting
- **Skills**: `run-gdlint`, `run-gdunit4-tests`

## Section 8: WCS Migration Application

This philosophy is applied throughout the Wing Commander Saga migration:

### Asset Conversion Pipeline
- **Parse Phase**: `parse-pof` extracts metadata (Reduce file format knowledge)
- **Convert Phase**: `convert-pof-to-glb` handles geometry (Delegate to Python)
- **Integrate Phase**: `generate-importer` creates composite asset solution

### Data Migration Pipeline
- **Parse Phase**: `parse-tbl` extracts structured data (Reduce parsing logic)
- **Generate Phase**: `generate-resource` creates Godot classes (Delegate generation)

### AI Migration Pipeline
- **Analysis Phase**: C++ Code Analyst creates structured analysis (Reduce complexity)
- **Generate Phase**: `generate-limboai-tree` creates behavior trees (Delegate structure)

### Quality Assurance Pipeline
- **Static Analysis**: `run-gdlint` validates style (structured JSON output)
- **Dynamic Testing**: `run-gdunit4-tests` validates functionality (JUnit XML parsing)

## Section 9: Success Metrics

### Reliability Metrics
- **Zero Context Pollution**: No complex procedures explained in prompts
- **Deterministic Output**: Same input always produces same structured output
- **Error Recovery**: All errors include structured remediation information

### Efficiency Metrics
- **Context Reduction**: >90% reduction in procedural token usage
- **Performance Improvement**: Scripts execute faster than prompt-based processing
- **Scalability**: System can handle arbitrarily large files without context limits

### Quality Metrics
- **Test Coverage**: All skills have comprehensive test suites
- **Error Handling**: All failure modes return structured JSON with remediation
- **Documentation**: All skills include complete usage examples

The result is a reliable, self-correcting migration system that can handle the complexity of converting a large C++ codebase to modern Godot patterns while maintaining high quality and reliability standards.