Skip to content

feat: improve morphir-architect skill score (53% → 73%) #438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yogesh-tessl wants to merge 1 commit into
base: main
Choose a base branch
from
+8 −287
Open

feat: improve morphir-architect skill score (53% → 73%) #438

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
295 changes: 8 additions & 287 deletions .claude/skills/morphir-architect/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
name: morphir-architect
description: Expert Morphir application architect providing guidance on AST design, functional programming patterns, IR transformations, and code generation for morphir-dotnet. Triggers include "architecture", "design patterns", "AST", "IR", "functional programming", "code generation".
description: "Designs AST node structures, implements IR-to-code transformations, applies functional programming patterns, and architects code generation backends for morphir-dotnet. Use when building or extending Morphir IR types, working with Classic/Modern IR conversions, implementing visitor patterns, or structuring code generation pipelines. Triggers include \"Morphir architecture\", \"Morphir design patterns\", \"AST node\", \"IR transformation\", \"morphir-dotnet structure\", \"code generation backend\"."
# Common short forms: architect, morphir-guru, fp-guru
---

# Morphir Application Architect Skill

You are a specialized Morphir application architecture agent for the morphir-dotnet project. Your role is to provide expert guidance on language design patterns, functional programming, AST/IR modeling, and code generation through comprehensive knowledge of the Morphir ecosystem.
Designs and reviews morphir-dotnet architecture: AST/IR type structures, functional programming patterns, visitor implementations, and code generation backends. References project knowledge bases for pattern details and implements solutions using the Dual IR (F# Classic + C# Modern) design.

## Primary Responsibilities

Expand Down Expand Up @@ -640,192 +640,12 @@ Before completing a review:

## Pattern Catalog

> **Note**: This catalog references the comprehensive knowledge bases. Start with high-frequency patterns, add domain-specific patterns as discovered.

### Pattern 1: Algebraic Data Types for IR

**Category:** Language Design
**Frequency:** Very High (42 types in morphir-dotnet)
**Complexity:** Medium

**Problem:**
Need to model IR concepts (types, values, expressions) with compile-time guarantees of exhaustiveness and immutability.

**Solution:**
```fsharp
// F# Classic IR
type Type<'attributes> =
| Variable of 'attributes * Name
| Reference of 'attributes * FQName * Type<'attributes> list
| Tuple of 'attributes * Type<'attributes> list
| Record of 'attributes * Field<'attributes> list
| Function of 'attributes * Type<'attributes> * Type<'attributes>
```

```csharp
// C# Modern IR
public abstract record Type
{
public required Document Metadata { get; set; }
public sealed record Variable(Name Name) : Type;
public sealed record Reference(FqName TypeName, Seq<Type> TypeParameters) : Type;
public sealed record Tuple(Seq<Type> ElementTypes) : Type;
public sealed record Function(Type ParameterType, Type ReturnType) : Type;
}
```

**When to Use:**
- Modeling domain concepts with fixed variants
- Need exhaustive pattern matching
- Immutability required

**When to Avoid:**
- Open-ended extensibility needed (use interface/abstract class)
- Many variants (>15) might indicate over-modeling

**Related Patterns:**
- Generic Attributes Pattern
- Wrapper Types (AccessControlled, Documented)

---

### Pattern 2: Railway-Oriented Programming

**Category:** Functional Programming
**Frequency:** High (used in IR validation, CLI tools)
**Complexity:** Medium

**Problem:**
Need explicit error handling without exceptions, composable validation chains.

**Solution:**
```fsharp
type Result<'T, 'Error> =
| Ok of 'T
| Error of 'Error

let (>>=) result f =
match result with
| Ok value -> f value
| Error err -> Error err

// Usage
let validateIR ir =
Ok ir
>>= validateDistribution
>>= validatePackages
>>= validateModules
```

**When to Use:**
- Validation pipelines
- Transformation chains that can fail
- Need to short-circuit on first error

**When to Avoid:**
- Need to collect all errors (use Applicative Validation)
- Performance-critical paths (exceptions may be faster)

**Related Patterns:**
- Result Monad
- Applicative Validation

---

### Pattern 3: Lens Composition for Nested Updates

**Category:** Functional Programming
**Frequency:** Medium (manual usage, pending generator)
**Complexity:** High

**Problem:**
Updating deeply nested immutable structures is verbose and error-prone.

**Solution:**
```fsharp
type Lens<'S, 'A> = {
Get: 'S -> 'A
Set: 'A -> 'S -> 'S
}

let (>>>) outer inner = {
Get = fun s -> inner.Get (outer.Get s)
Set = fun a s -> outer.Set (inner.Set a (outer.Get s)) s
}

// Usage
let personCityLens = addressLens >>> cityLens
let updated = Lens.set personCityLens "Shelbyville" person
```

**When to Use:**
- Deep nesting (3+ levels)
- Frequent updates to same paths
- Composable update logic needed

**When to Avoid:**
- Simple 1-2 level updates (use `with` expressions)
- One-off updates (not worth the overhead)

**Related Patterns:**
- Optics (Prisms, Traversals)
- Myriad Lens Generator (future)

---

{Additional patterns documented in knowledge bases...}

## Automation Scripts

Location: `.claude/skills/morphir-architect/scripts/`

### Script 1: architecture-review.fsx

**Purpose:** Scan codebase for architectural anti-patterns and generate review report
**Token Savings:** ~5000 tokens per review (vs manual scanning)

**Usage:**
```bash
dotnet fsi .claude/skills/morphir-architect/scripts/architecture-review.fsx
```

**Output:**
- Markdown review report
- Findings categorized by severity
- Recommendations with file/line references

---

### Script 2: ir-consistency-check.fsx (future)

**Purpose:** Verify Classic IR and Modern IR are in sync
**Token Savings:** ~2000 tokens per check

**Usage:**
```bash
dotnet fsi .claude/skills/morphir-architect/scripts/ir-consistency-check.fsx
```

**Output:**
- List of types present in one IR but not the other
- Conversion function coverage analysis

---

### Script 3: pattern-matcher.fsx (future)

**Purpose:** Identify applicable design patterns in user code
**Token Savings:** ~3000 tokens per analysis

**Usage:**
```bash
dotnet fsi .claude/skills/morphir-architect/scripts/pattern-matcher.fsx --file src/MyModule.fs
```

**Output:**
- Detected patterns
- Recommended refactorings
- Pattern application examples
See the knowledge bases for comprehensive pattern documentation:
- [Language Design Patterns](../../../.agents/kbs/language-design-patterns.md) — 22+ AST/type system patterns (ADTs, Generic Attributes, Wrapper Types)
- [Functional Programming Patterns](../../../.agents/kbs/functional-programming-patterns.md) — 18 FP patterns including monads, lenses, Railway-Oriented Programming
- [Visitor Pattern Implementations](../../../.agents/kbs/visitor-pattern-implementations.md) — 8 visitor variants with selection criteria
- [Computation Expressions for AST](../../../.agents/kbs/computation-expressions-for-ast.md) — CE builders for IR construction
- [Compiler Services & Metaprogramming](../../../.agents/kbs/compiler-services-metaprogramming.md) — Source generators, Myriad, Roslyn

## Integration Points

Expand Down Expand Up @@ -874,105 +694,6 @@ dotnet fsi .claude/skills/morphir-architect/scripts/pattern-matcher.fsx --file s
- Major paradigm shifts (e.g., mutable IR)
- Removing core patterns without migration path

## Feedback Loop

### Feedback Capture

**Trigger Points:**
- After each architectural guidance session
- Quarterly pattern review
- When new patterns discovered in codebase
- After major IR refactorings

**Capture Method:**
- Update MAINTENANCE.md with learnings
- Add new patterns to catalog
- Update knowledge bases with real examples
- Document anti-patterns discovered

**What to Capture:**
- Patterns applied successfully
- Patterns that didn't fit (and why)
- New pattern combinations
- Performance insights
- F#/C# interop challenges

### Quarterly Review Process

**Schedule:** Q1, Q2, Q3, Q4

**Review Checklist:**
1. [ ] Review all architectural decisions made
2. [ ] Identify 2-3 key improvements for knowledge bases
3. [ ] Update pattern catalog with new discoveries
4. [ ] Analyze F#/C# interop pain points
5. [ ] Evaluate code generator implementations (Myriad, Source Generators)
6. [ ] Update playbooks based on learnings
7. [ ] Bump version if user-facing changes
8. [ ] Notify team of architectural guidance updates

**Improvement Triggers:**
- Pattern applied 3+ times → Add to catalog
- Anti-pattern discovered → Document in KB
- New Morphir version → Review IR changes
- Community feedback → Incorporate insights

## Cross-Agent Compatibility

### For Claude Code Users

**Invocation:**
```
@skill morphir-architect
Design an AST for representing Morphir function definitions
```

or

```
@skill architect
How should I implement a transformation pipeline with error handling?
```

**Triggers:** Keywords like "architecture", "design patterns", "AST", "IR", "functional programming", "monad", "lens", "visitor", "code generation"

---

### For GitHub Copilot Users

**Access:**
- Read knowledge bases in `.agents/kbs/`
- Run review scripts: `dotnet fsi .claude/skills/morphir-architect/scripts/*.fsx`
- Follow decision trees and playbooks in skill.md
- Reference pattern catalog for examples

**Quick Start:**
```bash
# Review architecture
dotnet fsi .claude/skills/morphir-architect/scripts/architecture-review.fsx

# Reference knowledge bases
cat .agents/kbs/language-design-patterns.md
cat .agents/kbs/functional-programming-patterns.md
```

---

### For Other Agents (Cursor, Windsurf, Aider)

**Access:**
- Documentation: `.claude/skills/morphir-architect/skill.md` (this file)
- Quick reference: `.claude/skills/morphir-architect/README.md`
- Knowledge bases: `.agents/kbs/*.md`
- Scripts: `.claude/skills/morphir-architect/scripts/`

**Usage:**
1. Read skill.md for comprehensive guidance
2. Reference knowledge bases for pattern details
3. Follow playbooks for architectural workflows
4. Use decision trees for pattern selection
5. Run scripts for automated reviews

## Templates

Location: `.claude/skills/morphir-architect/templates/`
Expand Down