Issue #240: Create Elm to F# Guru Skill - Enhanced Edition

Enhancement of: Issue #240
Enhancement based on: Issue #253 - Unified Cross-Agent AI Skill Framework Architecture
Related Issues: #254, #255, #241, #242

Summary

Create a specialized Elm-to-F# Guru skill that facilitates high-quality migration of Elm code to idiomatic F#, with proactive review capability built-in from day one. This guru combines domain expertise, automation, continuous improvement, and cross-project portability principles from the unified skill framework.

The Elm-to-F# Guru will be the first guru built with review capability from the start, establishing a pattern for future gurus and demonstrating the full power of the guru framework.

1. Proactive Review Capability ⭐ NEW

The Elm-to-F# Guru includes proactive review as a core competency, not an afterthought. This sets it apart from earlier gurus where review capabilities were added later.

What the Guru Reviews

The Elm-to-F# Guru actively monitors migration progress and quality, identifying:

1.1 Anti-Patterns

• Elm idioms ported literally instead of idiomatically
  • Example: Elm’s Maybe translated directly to Option without considering F#’s ValueOption or nullable reference types where appropriate
  • Example: Elm’s union types with overly verbose F# discriminated unions when simpler patterns exist

1.2 Myriad Plugin Opportunities

• Patterns appearing 3+ times that should be automated via code generation
  • Example: Repetitive JSON serialization patterns across multiple types
  • Example: Boilerplate for F# record validation that mirrors Elm’s structure
  • Example: Type conversions between Elm and F# representations

1.3 F# Idiom Violations

• Code using non-idiomatic F# patterns
  • Example: Excessive use of mutable variables when immutable patterns are clearer
  • Example: Missing type annotations in public APIs
  • Example: Not using F# computation expressions where appropriate
  • Example: Ignoring F# pattern matching exhaustiveness

1.4 Migration Anti-Patterns

• Common mistakes repeated across modules
  • Example: Incorrect type mappings (Elm Int → F# int32 vs int64 vs bigint)
  • Example: Lost type safety during translation
  • Example: Performance issues from naive translations (e.g., list operations)

1.5 Generated Code Safety

• Verify code generated by Myriad plugins is correct
  • Example: Plugin-generated serializers match hand-written versions
  • Example: Generated validation logic preserves Elm’s semantics
  • Example: Type provider output is AOT-compatible (coordination with AOT Guru)

Review Triggers

The guru performs reviews at multiple cadences:

Session-Based Review (After Each Module Migration)

Trigger: Module migration marked complete
Action: Analyze migration for:
  - Pattern frequency (track repetitions)
  - Idiom compliance (F# best practices)
  - Type safety preservation (Elm → F#)
  - Test coverage (coordinate with QA Tester)
Output: Session summary with patterns discovered

Weekly Pattern Inventory Review

Trigger: Weekly scheduled scan (CI job or manual)
Action: Review all migrations from past week:
  - Aggregate pattern occurrences
  - Identify patterns appearing 3+ times
  - Check for emerging anti-patterns
Output: Weekly pattern report

Quarterly Comprehensive Review

Trigger: End of quarter (Q1, Q2, Q3, Q4)
Action: Deep analysis across all migrations:
  - Pattern frequency trends (increasing/decreasing)
  - Myriad plugin opportunities (automation candidates)
  - Migration quality metrics (idiom compliance, safety)
  - Coordination effectiveness (AOT Guru, QA Tester)
Output: Quarterly review report with improvement recommendations

Review Output Format

Reviews produce structured output for consumption by other gurus and developers:

## Elm-to-F# Migration Review Report
**Date:** 2025-12-19  
**Scope:** Modules migrated since last review  
**Reviewer:** Elm-to-F# Guru

### Pattern Frequency Report
| Pattern | Count | Example Locations | Status |
|---------|-------|-------------------|--------|
| ValueType boxing in pattern matching | 7 | `Module.A:45`, `Module.B:23`, ... | ⚠️ Recommend Myriad plugin |
| Manual JSON serialization | 5 | `Module.C:12`, `Module.D:67`, ... | ⚠️ Consider automation |
| Recursive union type translation | 12 | `Module.E:89`, `Module.F:34`, ... | ✅ Pattern documented |

### Myriad Plugin Recommendations
1. **Auto-Serializer Plugin** (Priority: High)
   - **Pattern:** Manual JSON serialization appears 5+ times
   - **Impact:** Reduce boilerplate, improve consistency
   - **Effort:** ~2-3 days to implement
   - **Token Savings:** ~50 tokens per type × 20 types = ~1000 tokens

2. **ValueType Boxing Detector** (Priority: Medium)
   - **Pattern:** Boxing detected 7 times
   - **Impact:** Performance + AOT compatibility
   - **Effort:** ~1 day to implement detection script
   - **Token Savings:** ~30 tokens per detection × 10/quarter = ~300 tokens

### Automation Script Suggestions
1. **Create `detect-boxing-patterns.fsx`**
   - Scans F# code for ValueType boxing in pattern matches
   - Integrates with AOT Guru's IL analysis
   
2. **Create `validate-type-mappings.fsx`**
   - Verifies Elm → F# type mappings are correct
   - Checks for precision loss (e.g., Elm Int → F# int vs int64)

### Migration Quality Metrics
- **Modules Migrated:** 80
- **Idiom Violations:** 1,200 (decreasing from 1,500 last quarter)
- **Patterns Discovered:** 45 total (12 new this quarter)
- **Test Coverage:** 82% (target: 80%, ✅ on target)
- **AOT Compatibility:** 95% (5% needs Myriad plugins)

### Coordination Status
- **With AOT Guru:** 3 generated code reviews completed, 2 IL warnings resolved
- **With QA Tester:** Test coverage verified, 5 edge cases added
- **With Release Manager:** Migration progress tracked, on schedule for Q1 2026

### Next Quarter Focus
1. Implement auto-serializer Myriad plugin
2. Add boxing detection to quarterly scans
3. Document recursive union type pattern (12 occurrences suggest it's stable)
4. Coordinate with AOT Guru on plugin IL output

2. Automated Feedback & Continuous Improvement

The Elm-to-F# Guru implements a continuous learning loop inspired by the guru framework’s retrospective philosophy.

Session Capture

Every migration session includes a “Patterns Discovered” section:

## Migration Session: Module.BusinessLogic
**Status:** Complete  
**Lines Migrated:** 450  
**F# Output:** 380 lines

### Patterns Discovered
1. **Union Type with Private State**: Elm's opaque types → F# with private constructor pattern
2. **Computation Expression Candidate**: Repeated `Result` chaining → F# `result { }` CE
3. **Myriad Opportunity**: 3rd occurrence of manual JSON serialization for discriminated unions

### Idiom Improvements
- Changed: Mutable loop → `List.fold` (idiomatic F#)
- Fixed: Added explicit type annotations to public API
- Enhanced: Used `ValueOption` instead of `Option` for high-frequency code paths

### Questions for Next Review
- Should we create a Myriad plugin for opaque type translation?
- Is the `Result` computation expression approach consistent with project standards?

Quarterly Reviews

At the end of each quarter, the guru performs a comprehensive pattern review:

Process:

1. Collect: Gather all “Patterns Discovered” sections from the quarter
2. Analyze: Identify top 3-5 patterns by frequency
3. Decide: Determine which patterns warrant automation (Myriad plugin, script, or decision tree update)
4. Document: Update the guru’s pattern catalog and playbooks
5. Plan: Set improvement goals for next quarter

Example Quarterly Review Outcomes:

Q1 2025 Review:
- Discovered 15 new patterns (total: 45)
- Top pattern: JSON serialization (appeared 18 times)
- Decision: Create Myriad plugin for auto-serialization
- Playbook updated: Added decision tree for union type translation

Q2 2025 Review:
- Created 2 Myriad plugins (auto-serialization, validation)
- JSON serialization occurrences dropped from 18 → 2 (automation working!)
- New pattern emerged: Recursive tree structures (8 occurrences)
- Decision: Document pattern, not yet frequent enough for plugin

Q3 2025 Review:
- Updated migration decision tree based on Q1-Q2 learnings
- Pattern catalog now has 52 patterns (7 added, no removals)
- Token savings from automation: ~2,500 tokens per quarter
- Coordination with AOT Guru improved (generated code review process)

Playbook Evolution

The guru’s playbooks and decision trees evolve based on learnings:

• Before: Generic “Translate Elm to F#” steps
• After Q1: Specific guidance on union types, computation expressions, serialization
• After Q2: Automation scripts integrated, Myriad plugin usage documented
• After Q3: Common pitfalls section added, anti-pattern detection automated

Automation Loop

The feedback loop prioritizes automation:

Pattern appears 1-2 times → Document in catalog
Pattern appears 3-5 times → Create detection script + decision tree entry
Pattern appears 6+ times → Strong candidate for Myriad plugin or major automation
Pattern appears 10+ times → Critical to automate (prevent technical debt)

3. Token Efficiency Analysis

The Elm-to-F# Guru includes 3+ F# automation scripts designed to save significant agent tokens by replacing high-cost manual operations.

Script 1: extract-elm-tests.fsx

Purpose: Extract test structure from Elm test files to guide F# test creation

Reusability: ⭐ Highly portable - works for any Elm-to-X migration, not F#-specific

Workflow:

# Input: Elm test file
dotnet fsi .claude/skills/elm-to-fsharp/scripts/extract-elm-tests.fsx tests/Module.elm

# Output: Structured test plan
{
  "module": "Module",
  "testCount": 12,
  "scenarios": [
    {
      "name": "should handle empty list",
      "type": "unit",
      "inputs": ["[]"],
      "expected": "Ok(0)"
    },
    {
      "name": "should sum positive numbers",
      "type": "property",
      "property": "forAll (list Int) (fun xs -> sum xs >= 0)",
      "inputs": ["[1, 2, 3]"],
      "expected": "6"
    }
  ]
}

Token Savings:

• Manual: Read Elm test file (200 tokens), understand structure (100 tokens), write F# test plan (150 tokens) = 450 tokens
• Automated: Run script (5 tokens), parse JSON output (25 tokens) = 30 tokens
• Savings: 420 tokens per module × 80 modules = 33,600 tokens annually

Script 2: analyze-elm-module.fsx

Purpose: Structural analysis of Elm modules to plan F# translation

Reusability: ⭐ Portable - core analysis logic works for any Elm module, F#-specific mappings can be parameterized

Workflow:

# Input: Elm source file
dotnet fsi .claude/skills/elm-to-fsharp/scripts/analyze-elm-module.fsx src/Module.elm

# Output: Translation plan
{
  "module": "Module",
  "types": [
    { "name": "Status", "kind": "union", "variants": ["Loading", "Success Data", "Error String"] },
    { "name": "Config", "kind": "record", "fields": ["timeout: Int", "retries: Int"] }
  ],
  "functions": [
    { "name": "init", "signature": "Config -> Status", "complexity": "low" },
    { "name": "update", "signature": "Msg -> Status -> Status", "complexity": "medium" }
  ],
  "dependencies": ["Http", "Json.Decode"],
  "translationHints": [
    "union type 'Status' → F# discriminated union with private state",
    "record 'Config' → F# record with [<CLIMutable>] if used with JSON",
    "Http dependency → use FsHttp or System.Net.Http.Json"
  ]
}

Token Savings:

• Manual: Read Elm file (300 tokens), identify types/functions (150 tokens), plan translation (200 tokens) = 650 tokens
• Automated: Run script (5 tokens), parse output (40 tokens), review hints (50 tokens) = 95 tokens
• Savings: 555 tokens per module × 80 modules = 44,400 tokens annually

Script 3: verify-migration.fsx

Purpose: Validate F# migration against Elm source for correctness

Reusability: ⚠️ Partially portable - validation logic can be reused, but type mappings are F#-specific

Workflow:

# Inputs: Elm source + F# target
dotnet fsi .claude/skills/elm-to-fsharp/scripts/verify-migration.fsx src/Module.elm src/Module.fs

# Output: Verification report
{
  "module": "Module",
  "status": "warning",
  "typeMappings": [
    { "elm": "Status", "fsharp": "Status", "status": "✅ correct" },
    { "elm": "Config", "fsharp": "Config", "status": "✅ correct" }
  ],
  "functionMappings": [
    { "elm": "init", "fsharp": "init", "status": "✅ correct" },
    { "elm": "update", "fsharp": "update", "status": "⚠️ signature differs" }
  ],
  "issues": [
    {
      "severity": "warning",
      "location": "Module.fs:45",
      "message": "Function 'update' signature differs from Elm: expected 'Msg -> Status -> Status', found 'Msg -> Status -> Status * Cmd'",
      "suggestion": "Verify this is intentional (F# may have richer return type)"
    }
  ],
  "testCoverage": {
    "elm": 12,
    "fsharp": 10,
    "missing": ["should handle empty list", "should reject invalid input"]
  }
}

Token Savings:

• Manual: Compare Elm + F# (400 tokens), check types (150 tokens), verify functions (200 tokens), test coverage (100 tokens) = 850 tokens
• Automated: Run script (5 tokens), review report (80 tokens) = 85 tokens
• Savings: 765 tokens per module × 80 modules = 61,200 tokens annually

Script 4: detect-patterns.fsx (Review Capability)

Purpose: Find anti-patterns and idiom violations in migrated F# code

Reusability: ⚠️ F#-specific - detection rules are F# idiom-specific, but framework is portable

Workflow:

# Input: F# files from migration
dotnet fsi .claude/skills/elm-to-fsharp/scripts/detect-patterns.fsx src/*.fs

# Output: Pattern detection report
{
  "scannedFiles": 25,
  "patterns": [
    {
      "pattern": "ValueType boxing in pattern match",
      "severity": "warning",
      "count": 7,
      "locations": [
        { "file": "Module.fs", "line": 45, "context": "match x with | Some (y: struct ValueType) -> ..." },
        { "file": "Other.fs", "line": 23, "context": "..." }
      ],
      "recommendation": "Use 'ValueOption' instead of 'Option' for value types to avoid boxing"
    },
    {
      "pattern": "Mutable variable in pure function",
      "severity": "info",
      "count": 3,
      "locations": [
        { "file": "Logic.fs", "line": 67, "context": "let mutable acc = 0; for x in xs do acc <- acc + x; acc" }
      ],
      "recommendation": "Consider using 'List.fold' or other functional patterns"
    }
  ],
  "myriadOpportunities": [
    {
      "pattern": "Manual JSON serialization",
      "count": 5,
      "priority": "high",
      "recommendation": "Create Myriad plugin for auto-serialization"
    }
  ]
}

Token Savings:

• Manual: Read F# files (500 tokens), identify patterns (300 tokens), categorize (150 tokens) = 950 tokens
• Automated: Run script (5 tokens), review report (100 tokens) = 105 tokens
• Savings: 845 tokens per review × 4 reviews/quarter = 3,380 tokens per quarter

Total Token Savings (All Scripts)

Note: These savings assume 80 modules to migrate over the project lifetime. Actual savings will scale with the number of modules.

4. Cross-Project Portability

The Elm-to-F# Guru is designed with portability in mind, making it easier to adapt to other Elm migration projects or even other functional language migrations.

Portable Components ✅

These components can be reused in other projects with minimal changes:

4.1 Pattern Detection Logic

• What: Structural analysis of source code (identifying types, functions, dependencies)
• Portable to: Elm-to-Haskell, Elm-to-OCaml, Elm-to-ReasonML, Elm-to-PureScript
• Adaptation effort: Low (~1-2 hours to adjust output format)

4.2 Structural Analysis

• What: Understanding Elm module structure, type definitions, function signatures
• Portable to: Any Elm-to-X migration
• Adaptation effort: Very low (~30 minutes, mostly path configuration)

4.3 Idiom Checkers (Framework)

• What: Framework for detecting anti-patterns and idiom violations
• Portable to: Any source-to-target language migration
• Adaptation effort: Medium (~4-8 hours to define target language idioms)

4.4 Review Philosophy and Feedback Loops

• What: Session capture, quarterly reviews, automation loop, retrospective integration
• Portable to: Any guru (not specific to Elm-to-F# at all)
• Adaptation effort: Very low (~1 hour to customize templates)

4.5 Core Review Capability Pattern

• What: Proactive scanning → issue detection → reporting → improvement cycle
• Portable to: Any guru (already used by QA Tester, AOT Guru, Release Manager)
• Adaptation effort: Low (~2-4 hours to define domain-specific scan criteria)

Non-Portable Components ⚠️

These components are specific to F# and morphir-dotnet:

4.6 F#-Specific Idioms

• What: F# best practices, computation expressions, ValueOption vs Option, etc.
• Portable to: Other F# projects (yes), other languages (no)
• Reason: Deeply tied to F# language features

4.7 Myriad Plugin Examples

• What: F# code generation via Myriad (F#-specific tool)
• Portable to: Other F# projects (yes), other languages (no, but similar tools exist)
• Reason: Myriad is F#-specific, though concepts apply to other compile-time code generation tools

4.8 Type System Mappings (Elm → F#)

• What: Specific rules for translating Elm types to F# types
• Portable to: Elm-to-Haskell (partial), Elm-to-OCaml (partial), Elm-to-X (needs remapping)
• Reason: Type systems differ across target languages

Reusable Across Gurus ⭐

Some components are valuable for all gurus, not just migration gurus:

4.9 Automation Script Framework

• What: F# script structure, argument parsing, JSON output, error handling
• Reusable by: QA Tester, AOT Guru, Release Manager, future gurus
• Adaptation effort: Very low (copy template, customize logic)

4.10 Pattern Catalog Structure

• What: Markdown-based catalog of patterns with examples, pros/cons, recommendations
• Reusable by: All gurus
• Adaptation effort: Very low (change domain-specific patterns)

4.11 Quarterly Review Template

• What: Structured review process with findings, metrics, improvement recommendations
• Reusable by: All gurus
• Adaptation effort: Very low (customize review criteria)

Adaptation Guide for Other Projects

If adapting Elm-to-F# Guru to another project:

For Elm-to-Haskell:

1. ✅ Keep: extract-elm-tests.fsx, analyze-elm-module.fsx (Elm parsing logic)
2. ✅ Keep: Pattern detection framework, review philosophy
3. ⚠️ Modify: Type mappings (Elm → Haskell instead of Elm → F#)
4. ⚠️ Replace: Myriad plugins → Template Haskell or other Haskell code generation
5. ⚠️ Replace: F# idiom checkers → Haskell idiom checkers (e.g., prefer fmap over liftM)

Estimated adaptation effort: 12-20 hours (2-3 days)

For Elm-to-OCaml:

1. ✅ Keep: Same as Elm-to-Haskell
2. ⚠️ Modify: Type mappings (Elm → OCaml)
3. ⚠️ Replace: Myriad plugins → PPX preprocessors (OCaml code generation)
4. ⚠️ Replace: F# idiom checkers → OCaml idiom checkers

Estimated adaptation effort: 12-20 hours (2-3 days)

For Python-to-F# (different source language):

1. ⚠️ Modify: Source language parsing (Python AST instead of Elm)
2. ✅ Keep: Target language idioms (F#)
3. ✅ Keep: Review philosophy, pattern detection framework
4. ✅ Keep: Myriad plugins (F# target)
5. ⚠️ Replace: Type mappings (Python → F# is more complex due to dynamic typing)

Estimated adaptation effort: 24-40 hours (4-6 days)

5. Guru Coordination

The Elm-to-F# Guru coordinates with other gurus to ensure high-quality, production-ready migrations.

With AOT Guru

Direction: Elm-to-F# → AOT Guru (generated code review)

Coordination Point: After migration, before release

Workflow:

Elm-to-F# Guru: "I've migrated Module.fs and generated serialization code via Myriad plugin"
   ↓
AOT Guru: "Let me review for AOT safety..."
   ↓ [scans IL output]
AOT Guru: "Found IL2026 warning in generated serializer. Recommend using source generator instead."
   ↓
Elm-to-F# Guru: "Updated Myriad plugin to generate AOT-compatible code"
   ↓
AOT Guru: "Verified. No IL warnings. Binary size within target."

Integration Points:

• IL Warning Analysis: AOT Guru scans generated code for reflection usage (IL2026, IL3050)
• Binary Size Impact: AOT Guru reports if migration increases binary size beyond targets
• Plugin Compatibility: AOT Guru verifies Myriad-generated code is AOT-compatible
• Feedback Loop: AOT findings feed back to Elm-to-F# playbooks (avoid reflection patterns)

Review Coordination:

• Elm-to-F# quarterly review includes “Generated Code AOT Status” section
• AOT Guru quarterly review includes “Myriad Plugin Compatibility” section
• Both gurus participate in joint retrospectives when IL warnings are found

With QA Tester

Direction: Elm-to-F# → QA Tester (test coverage verification)

Coordination Point: After migration, before marking module complete

Workflow:

Elm-to-F# Guru: "I've migrated Module.fs. Original Elm had 12 tests."
   ↓
QA Tester: "Checking F# test coverage..."
   ↓ [runs verify-migration.fsx]
QA Tester: "Found 10/12 tests. Missing: 'should handle empty list', 'should reject invalid input'"
   ↓
Elm-to-F# Guru: "Added missing tests. Coverage now 12/12."
   ↓
QA Tester: "Verified. Coverage 82% (target: 80%). ✅"

Integration Points:

• Test Extraction: QA Tester validates output of extract-elm-tests.fsx
• Coverage Verification: QA Tester ensures F# tests match or exceed Elm coverage
• Edge Case Detection: QA Tester identifies missing edge cases in migrated code
• Regression Testing: QA Tester runs regression tests after bulk migrations

Review Coordination:

• Elm-to-F# quarterly review includes “Test Coverage Status” section
• QA Tester quarterly review includes “Migration Test Quality” section
• Both gurus collaborate on test plan templates for common migration scenarios

With Release Manager

Direction: Release Manager → Elm-to-F# (version tracking for milestones)

Coordination Point: Release planning and retrospectives

Workflow:

Release Manager: "Planning v1.0.0 release. What's migration status?"
   ↓
Elm-to-F# Guru: "80 modules completed, 20 remaining. On track for Q1 2026."
   ↓
Release Manager: "Noted. Including 'Elm-to-F# migration: 80% complete' in release notes."
   ↓ [release happens]
Release Manager: "v1.0.0 deployed. Any migration-related issues?"
   ↓
Elm-to-F# Guru: "No issues reported. 2 edge cases found in testing, fixed in v1.0.1."

Integration Points:

• Milestone Tracking: Release Manager tracks migration progress for release notes
• Version Milestones: Elm-to-F# reports which modules are included in each release
• Release Notes: Release Manager includes migration status and highlights
• Retrospectives: Both gurus participate in post-release retrospectives

Review Coordination:

• Elm-to-F# quarterly review includes “Release Milestones Achieved” section
• Release Manager quarterly review includes “Feature Parity Progress” section
• Both gurus align on Q1/Q2/Q3/Q4 migration goals

Common Feedback: Retrospectives

All gurus participate in retrospectives after significant events:

Post-Release Retrospective:

Facilitator: "What went well with the Elm-to-F# migration in v1.0.0?"
Elm-to-F# Guru: "80 modules migrated with no blocking issues. Myriad plugin saved significant time."
QA Tester: "Test coverage stayed above 80%. Found 2 edge cases, both resolved quickly."
AOT Guru: "Generated code is AOT-compatible. Binary size within targets."
Release Manager: "Migration progressed as planned. Communication was clear."

Facilitator: "What could improve?"
Elm-to-F# Guru: "Myriad plugin created IL warnings initially. Need earlier AOT review."
AOT Guru: "Agree. Let's add AOT review to migration checklist before PR approval."
QA Tester: "Some tests were added late. Extract Elm tests earlier in migration workflow."
Release Manager: "Milestone tracking was manual. Automate migration progress reporting."

Facilitator: "Action items?"
ALL: 
  1. Update migration checklist: Add AOT review step
  2. Update migration playbook: Extract Elm tests as step 1 (not step 3)
  3. Create migration-progress.fsx script (automate status reporting)
  4. Next quarter: Monitor if changes reduce issues

Retrospective Outputs Feed Back to Gurus:

• Elm-to-F# Guru: Updates playbooks, adds AOT review step, documents new patterns
• AOT Guru: Updates review criteria to include Myriad plugin output
• QA Tester: Updates test plan template to prioritize early test extraction
• Release Manager: Automates migration progress tracking for release notes

6. Review Integration with Retrospectives

The Elm-to-F# Guru combines proactive review (finding issues before they cause problems) with reactive retrospectives (learning from problems that occurred).

How They Work Together

┌─────────────────────────────────────────────────────────────┐
│                    CONTINUOUS IMPROVEMENT CYCLE              │
└─────────────────────────────────────────────────────────────┘

Q1 REVIEWS (Proactive):
  Findings:
    - "ValueType boxing pattern found in 7 places"
    - "Elm pattern 'Result.andThen chains' not idiomatic in F#"
    - "3 modules using old F# style (mutable loops)"
    - "Myriad plugin opportunity: JSON serialization (5 occurrences)"

         ↓ Feed into retrospectives

Q1 RETROSPECTIVES (Reactive):
  Questions:
    - "Why does ValueType boxing happen?"
      → Root cause: Developers unaware of ValueOption vs Option
    - "Are we teaching F# idioms correctly?"
      → Root cause: Migration playbook lacks idiom guidance
    - "Should we automate this pattern?"
      → Root cause: Repetitive manual work → errors

         ↓ Decisions & Actions

Q1 OUTCOMES:
  Actions:
    1. Create Myriad plugin for auto-serialization (eliminates repetitive manual work)
    2. Update migration decision tree:
       - Add "ValueOption vs Option" decision point
       - Document Elm Result → F# Result CE pattern
    3. Add pattern detection to verify.fsx (prevent old F# style from recurring)
    4. Update playbooks:
       - Add "F# Idioms" section with examples
       - Include checklist: "Did you consider computation expressions?"

         ↓ Improvements deployed

Q2 REVIEWS (Next Cycle):
  Findings:
    - "ValueType boxing reduced from 7 → 2 occurrences" ✅ Improvement!
    - "0 old F# style issues (automated detection working)" ✅ Improvement!
    - "JSON serialization: 5 → 0 occurrences (Myriad plugin working)" ✅ Improvement!
    - "New pattern discovered: Recursive tree structures (4 modules)"

         ↓ New questions, new cycle

Example Integration: ValueType Boxing Pattern

Quarter 1: Discovery

Review Findings (Proactive):

Pattern: ValueType boxing in pattern matching
Occurrences: 7
Locations: Module.A:45, Module.B:23, Module.C:67, ...
Severity: Warning
Impact: Performance degradation + AOT compatibility concerns
Recommendation: Use ValueOption instead of Option for value types

Retrospective Analysis (Reactive):

Question: "Why does ValueType boxing happen so frequently?"

Investigation:
- Reviewed 7 occurrences
- Pattern: All in code migrated from Elm's Maybe type
- Root cause: Migration playbook says "Elm Maybe → F# Option" (generic)
- Developers followed playbook literally without considering performance

Conclusion: Playbook lacks guidance on ValueOption vs Option choice

Q1 Outcomes:

Action 1: Update migration playbook
  Before: "Elm Maybe → F# Option"
  After: "Elm Maybe → F# Option (reference types) or ValueOption (value types)"
  Added: Decision tree with examples

Action 2: Create detection script
  Script: detect-boxing-patterns.fsx
  Integration: Run as part of verify-migration.fsx
  Output: Warning if Option used with value types

Action 3: Document pattern
  Added to pattern catalog: "Pattern #23: ValueOption for Value Types"
  Examples: 7 real cases from Q1 migrations
  Guideline: "Use ValueOption<int>, ValueOption<DateTime> to avoid boxing"

Quarter 2: Validation

Review Findings (Proactive):

Pattern: ValueType boxing in pattern matching
Occurrences: 2 (down from 7) ✅
Locations: Module.X:89, Module.Y:12
Severity: Warning
Status: IMPROVING (71% reduction)
Note: 2 occurrences are in legacy code, not new migrations

Retrospective Analysis (Reactive):

Question: "Why do 2 occurrences still exist?"

Investigation:
- Both in legacy code (pre-Q1 improvements)
- Not flagged because verify-migration.fsx only runs on new migrations
- Opportunity: Run detection script on entire codebase, not just new code

Conclusion: Expand automated detection to full codebase

Q2 Outcomes:

Action 1: Expand detection scope
  Before: verify-migration.fsx runs only on new migrations
  After: detect-patterns.fsx runs on entire codebase weekly

Action 2: Fix legacy code
  Created PRs to fix 2 legacy occurrences
  Added to backlog: "Modernize legacy code patterns"

Action 3: Celebrate improvement
  Shared success with team: "ValueType boxing reduced 71% via playbook updates"

Quarter 3: Stability

Review Findings (Proactive):

Pattern: ValueType boxing in pattern matching
Occurrences: 0 ✅
Severity: N/A (no longer occurring)
Status: RESOLVED
Note: Pattern detection active, no new occurrences in Q3

Retrospective Analysis (Reactive):

Question: "What made this improvement successful?"

Reflection:
- Proactive review discovered the pattern early (Q1)
- Retrospective identified root cause (playbook gap)
- Combined action: Updated playbook + automated detection
- Validation: Q2 review confirmed improvement, Q3 confirmed resolution

Conclusion: Review + Retrospective cycle works! Apply to other patterns.

Q3 Outcomes:

Action 1: Document success
  Added case study to guru-creation-guide.md: "ValueType Boxing Pattern Resolution"
  Template for future pattern improvements

Action 2: Apply learnings to new pattern
  Q3 discovered: "Recursive tree structure pattern (8 occurrences)"
  Following same process: Review → Retrospective → Action → Validate

Review vs Retrospective: Key Differences

Mutual Benefits

Reviews inform retrospectives:

• Review findings become retrospective discussion topics
• Pattern frequency data helps prioritize retrospective focus
• Metrics show whether improvements are working

Retrospectives improve reviews:

• Root cause analysis refines what reviews should look for
• Process insights suggest new review criteria
• Team feedback identifies blind spots in automated reviews

Together:

• Reviews catch issues early (prevent problems)
• Retrospectives understand why issues occur (prevent recurrence)
• Continuous cycle drives improvement quarter-over-quarter

7. Enhanced Success Criteria

The Elm-to-F# Guru defines success across functional, learning, automation, and maturity dimensions, with clear metrics for each phase.

Functional Criteria ✅

Core functionality that must work:

• Elm modules successfully migrated to F#

  • All Elm syntax translated to valid F# code
  • Code compiles without errors
  • Type safety preserved (no unsafe casts or failwith unless in Elm source)

• Generated code compiles and tests pass

  • F# output passes dotnet build
  • All tests from Elm are represented in F# (via extract-elm-tests.fsx)
  • Tests pass with same semantics as Elm tests

• Myriad plugins operational

  • Plugins generate valid F# code
  • Generated code is AOT-compatible (verified by AOT Guru)
  • Plugins integrated into build process

Learning Criteria 📚

Evidence of continuous improvement:

• 20+ patterns documented in pattern catalog

  • Each pattern includes: name, description, examples, pros/cons, recommendations
  • Patterns categorized: type translation, function translation, idioms, anti-patterns
  • Catalog updated quarterly

• 5+ Myriad plugins implemented (from patterns)

  • Plugins created for patterns appearing 6+ times
  • Examples: auto-serialization, validation, union type helpers
  • Each plugin documented with usage guide

• Quarterly reviews showing pattern frequency trends

  • Q1 baseline established
  • Q2/Q3/Q4 show trends (increasing/decreasing)
  • Improvements correlated with actions taken (e.g., “boxing reduced 71% after playbook update”)

• Migration decision tree improved 3+ times based on learnings

  • Q1: Initial decision tree (basic Elm → F# mappings)
  • Q2: Updated with ValueOption vs Option guidance
  • Q3: Added computation expression decision points
  • Q4: Expanded with recursive type handling
  • Evidence: Git history shows decision tree evolution

Automation Criteria 🤖

Scripts and automation in place:

• 3 core F# scripts (extract, analyze, verify)

  • extract-elm-tests.fsx: Working and tested
  • analyze-elm-module.fsx: Working and tested
  • verify-migration.fsx: Working and tested
  • All scripts have JSON output option
  • All scripts have error handling and help text

• 1+ review/detection scripts live

  • detect-patterns.fsx: Working and integrated
  • Runs weekly or on-demand
  • Produces actionable reports
  • False positive rate < 10%

• Token savings measured and documented

  • Baseline manual costs documented
  • Automated costs measured
  • Savings calculated per script
  • Annual savings: 150,000+ tokens (see Section 3)

Maturity Phases 🎯

The guru progresses through phases over time:

Phase 1: Alpha (Manual Migration, Pattern Capturing)

Duration: Q1 (first 3 months of use)

Criteria:

• Directory structure created (.claude/skills/elm-to-fsharp/)
• skill.md complete (1000+ lines)
• README.md and MAINTENANCE.md created
• 3 core automation scripts working
• 10+ seed patterns documented
• Manual migration workflow established
• First module migrated successfully
• Pattern capture template in use

Characteristics:

• High manual effort (guru guides, but humans do most work)
• Pattern discovery is primary focus
• Scripts are helpers, not fully automated
• Quarterly review captures learnings

Success Metric: 10+ modules migrated, 15+ patterns discovered

Phase 2: Beta (Review Capability Working, Myriad Plugins Created)

Duration: Q2-Q3 (months 4-9)

Criteria:

• Review capability implemented (detect-patterns.fsx)
• Review scripts tested on real data (10+ modules)
• Feedback mechanism working (session capture + quarterly reviews)
• First quarterly review completed with actionable findings
• 20+ patterns in catalog (10 baseline + 10 new)
• 2-3 Myriad plugins implemented (from frequent patterns)
• Decision tree improved based on Q1 learnings
• Coordination with AOT Guru and QA Tester tested

Characteristics:

• Automation emerging (Myriad plugins reduce manual work)
• Proactive review finds issues before they accumulate
• Patterns guide most decisions (less ad-hoc translation)
• Integration with other gurus proven

Success Metric: 40+ modules migrated, 3 Myriad plugins live, pattern frequency trending down (automation working)

Phase 3: Stable (Automated Patterns, Predictable Quarterly Improvement)

Duration: Q4+ (month 10 onwards)

Criteria:

• 25+ patterns in catalog
• 5+ Myriad plugins operational
• Review capability proven reliable (4+ reviews completed)
• Automated feedback generating insights quarterly
• 3+ quarters of successful evolution (Q1 → Q4)
• Token efficiency documented (150,000+ tokens saved)
• Cross-project reuse strategy documented
• Continuous improvement cycle established (review → retrospective → action → validate)
• Integration with other gurus seamless

Characteristics:

• High automation (many patterns handled by Myriad plugins)
• Predictable quarterly improvements (process refined)
• Review findings feed back smoothly (no manual intervention)
• New patterns emerge slowly (most common cases automated)

Success Metric: 80+ modules migrated, pattern discovery rate stabilizes, quarterly improvements sustain

Phase Transition Criteria

Alpha → Beta:

• Triggered by: First quarterly review complete
• Required: 10+ modules migrated, 15+ patterns documented, 3 scripts operational
• Validation: Team feedback confirms guru is useful (not just experimental)

Beta → Stable:

• Triggered by: Third quarterly review complete (end of Q3)
• Required: 40+ modules migrated, 20+ patterns, 3+ Myriad plugins, review capability working
• Validation: Pattern frequency shows automation is working (e.g., JSON serialization 18 → 2 occurrences)

Stable → Excellence (future):

• Triggered by: After 2+ years of use
• Required: 100+ modules, 30+ patterns, 10+ Myriad plugins, cross-project reuse proven
• Validation: Guru is used by other projects (Elm-to-Haskell, Elm-to-OCaml, etc.)

Success Metrics Summary

Acceptance Criteria

This issue enhancement is complete when:

• Issue #240 body updated with all 7 sections

  • Section 1: Proactive Review Capability ⭐
  • Section 2: Automated Feedback & Continuous Improvement
  • Section 3: Token Efficiency Analysis (4 F# scripts)
  • Section 4: Cross-Project Portability
  • Section 5: Guru Coordination (AOT, QA, Release Manager)
  • Section 6: Review Integration with Retrospectives
  • Section 7: Enhanced Success Criteria (maturity phases)

• Review capability prominently featured

  • Review is Section 1 (not hidden or afterthought)
  • Review triggers documented (session, weekly, quarterly)
  • Review output format includes examples
  • Review integration with retrospectives illustrated

• Links to related issues established

  • Issue #253 - Unified Cross-Agent AI Skill Framework
  • Issue #254 - Cross-Agent Skill Accessibility
  • Issue #255 - Guru Creation Guide & Template
  • Issue #241 - CodeGeneration Project
  • Issue #242 - Fabulous.AST for F# Codegen

• F# script list specified with token savings estimates

  • 4 scripts: extract-elm-tests.fsx, analyze-elm-module.fsx, verify-migration.fsx, detect-patterns.fsx
  • Token savings per script documented
  • Annual savings calculated: 152,720 tokens

• Review triggers and output format documented

  • Triggers: Session-based, weekly, quarterly
  • Output format: Markdown report with structured findings
  • Example output provided in Section 1

• Guru coordination matrix with review integration points

  • AOT Guru: Generated code IL review
  • QA Tester: Test coverage verification
  • Release Manager: Milestone tracking
  • Retrospectives: Common feedback hub

• Success criteria measurable, time-bound, and includes review metrics

  • Functional, Learning, Automation, Maturity criteria defined
  • Phases: Alpha (Q1), Beta (Q2-Q3), Stable (Q4+)
  • Metrics: modules migrated, patterns documented, plugins created, token savings

• Retrospective + Review integration illustrated with example

  • Section 6 provides Q1-Q3 cycle example
  • ValueType boxing pattern case study
  • Shows how review findings → retrospective analysis → improvements → validation

Implementation Checklist

When implementing the Elm-to-F# Guru based on this enhanced specification:

Planning Phase (Before Code)

• Review this document with maintainers
• Confirm Myriad plugins are acceptable approach
• Identify 80 Elm modules for migration (prioritize by complexity)
• Set up tracking issue for quarterly reviews
• Create .claude/skills/elm-to-fsharp/ directory

Alpha Phase Implementation (Q1)

• Create skill.md (1000+ lines) following guru template
• Create README.md and MAINTENANCE.md
• Implement 3 core scripts: extract-elm-tests.fsx, analyze-elm-module.fsx, verify-migration.fsx
• Document 10 seed patterns from existing Elm code
• Migrate first 10 modules manually (capture patterns in session notes)
• Complete Q1 review: Identify top 3 patterns for automation

Beta Phase Implementation (Q2-Q3)

• Implement detect-patterns.fsx (review capability)
• Create 2-3 Myriad plugins (based on Q1 pattern frequency)
• Update decision tree with Q1 learnings
• Coordinate with AOT Guru on generated code review
• Coordinate with QA Tester on test coverage verification
• Migrate 30 more modules (total: 40)
• Complete Q2 and Q3 reviews: Track pattern frequency trends

Stable Phase Implementation (Q4+)

• Implement 2-3 more Myriad plugins (total: 5+)
• Expand pattern catalog to 25+ patterns
• Document token savings (validate 150K+ tokens annually)
• Create cross-project portability guide (for Elm-to-Haskell, etc.)
• Migrate remaining 40 modules (total: 80)
• Complete Q4 review: Demonstrate sustained improvement

Documentation & Integration

• Add Elm-to-F# Guru to .agents/skills-reference.md
• Update .agents/skill-matrix.md with maturity tracking
• Add to .agents/capabilities-matrix.md for cross-agent compatibility
• Reference in AGENTS.md for discoverability
• Create release notes summarizing guru capabilities

References

• Issue #253 - Unified Cross-Agent AI Skill Framework Architecture
• Issue #254 - Cross-Agent Skill Accessibility & Consolidation
• Issue #255 - Guru Creation Guide & Skill Template
• Issue #241 - Create CodeGeneration Project
• Issue #242 - Integrate Fabulous.AST for F# Code Generation
• Guru Creation Guide
• Guru Philosophy
• Skills Reference
• Skill Matrix

Last Updated: 2025-12-19
Status: Enhanced Issue Specification Ready for Implementation
Next Steps: Update GitHub Issue #240 with this content