# Maf Migration Retrospective

> Post-migration learning skill. After a migration completes, reads the migration plan notes, build history, and surprises to improve the registry, guide, and constraint rules. Invoked as the final step of any migration. This is how the toolkit gets smarter with each use.

- **Type:** Skill
- **Install:** `agentstack add skill-joslat-maf-doctor-maf-migration-retrospective`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [joslat](https://agentstack.voostack.com/s/joslat)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [joslat](https://github.com/joslat)
- **Source:** https://github.com/joslat/maf-doctor/tree/main/.github/skills/maf-migration-retrospective

## Install

```sh
agentstack add skill-joslat-maf-doctor-maf-migration-retrospective
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# migration-retrospective

## Purpose

Every migration surfaces surprises — patterns the plan didn't predict, docs that were wrong, APIs that behaved differently than expected. This skill captures those surprises systematically and feeds them back into the toolkit's knowledge base.

After 10 migrations, the `obsolete-api-registry.yaml` covers real-world CS0618 patterns that aren't in any official docs. After 20, the Known Misalignments section becomes the most battle-tested part of the guide. This is the compound effect.

---

## When to Use This Skill

- Immediately after a migration completes (`T11.2 — Done`)
- Before closing any migration branch or PR
- When a migration hit a surprise that wasn't in the plan

---

## The Retrospective Workflow

### Step 1 — Read the completed migration plan

Read `src/docs/migration-plan.md` — specifically:
- The **Notes** column of each task row (where surprises were recorded during execution)
- Any tasks with `% Done: 100%` that have non-empty notes
- The **Risk Register** section — were any predicted risks wrong or missing?

### Step 2 — Read build error history (if available)

If terminal output is available from the migration session:
```powershell
# Look for unexpected build errors in terminal history
# Focus on: CS0246 errors not predicted by the plan, runtime exceptions, CS0618 not in registry
```

Key questions:
- Were there CS0246 errors for types/members NOT in the migration plan?
- Were there CS0618 warnings NOT in the registry?
- Were there silent runtime failures detected by smoke tests?

### Step 3 — Identify surprises

For each surprise (unexpected error, wrong doc, new pattern):

| Surprise type | Action |
|--------------|--------|
| CS0618 not in registry | Add to `registry.yaml` |
| CS0246 for type/member not in plan | Add to registry + add to breaking changes table in `maf-constraints.instructions.md` |
| Official doc was wrong | Add to Known Misalignments in `maf-1.3.0-migration-guide.md` |
| Silent runtime failure | Add to maf-fan-out-validator skill |
| `dotnet-inspect` missed something | Note in `dotnet-inspect/SKILL.md` limitations section |
| New hard constraint discovered | Add to `maf-constraints.instructions.md` Hard Constraints section |

### Step 4 — Update registry.yaml

For each new CS0618 or unexpected breaking change:

```yaml
  - id: MAF130--
    package: Microsoft.Agents.AI[.Workflows]
    version_introduced: "1.3.0"
    type: 
    method: 
    obsolete_signature: ""
    replacement_signature: ""
    argument_order_change: 
    fix_description: ""
    example_before: |
      
    example_after: |
      
    cs_warning: CS0618
    guide_section: ""
    dotnet_inspect_detectable: false
    notes: >
      Discovered during: .
      Was NOT predicted by migration plan.
      
```

### Step 5 — Update Known Misalignments

For each official doc that was wrong, add to `guides/maf-1.3.0-migration-guide.md` → "Known Misalignments" section:

```markdown
|  |  |  |
```

### Step 6 — Update maf-constraints.instructions.md

For any new hard constraint discovered (e.g., "never use X in production", "always call Y before Z"):

Add to the **Hard Constraints** table in `.github/instructions/maf-constraints.instructions.md`.

Format:
```markdown
- **NEVER**  — discovered in 
```

### Step 7 — Check dotnet-inspect issue queue

For each surprise that dotnet-inspect should have caught but didn't:
- Was it the known `[Obsolete]` overload detection gap (issue #316)?
- Or is it a new gap worth filing separately?

If new → add a note in `.github/skills/dotnet-inspect/SKILL.md` under "Critical Limitation".

### Step 8 — Output the retrospective summary

```markdown
## Migration Retrospective Summary

**Migration:** 
**Date:** 
**Source version:** 
**Target version:** 

### Surprises Found

| # | Type | Description | Action taken |
|---|------|-------------|-------------|
| 1 | CS0618 not in registry | `SerializeSession` was obsolete — docs showed sync version | Added MAF130-SESSION-001 to registry |
| 2 | Doc misalignment | `RunAsync()` not on `IAIAgent` interface, only on `ChatClientAgent` | Added to Known Misalignments |
| 3 | Silent runtime | PropertyTheftFanOutExecutor returned non-generic ValueTask | Added to maf-fan-out-validator SKILL.md |

### Registry Updates
- Added N new entries to `registry.yaml`

### Guide Updates
- Added N new Known Misalignments entries

### Constraint Updates
- Added N new Hard Constraints

### For the Next Migration
> Key things to watch out for in the next migration of a similar codebase:
> [list of the most impactful surprises]
```

---

## The Compound Effect

Over time:
- **Registry:** Grows from 1 entry to dozens — covering real-world patterns that official docs miss
- **Known Misalignments:** Becomes the most reliable section of the guide — battle-tested across real codebases
- **Constraints:** Hard rules that prevent re-discovering the same mistakes
- **Skills:** Fan-out validator and static analyzer improve with each failure mode documented

Each migration makes the next one faster and more reliable.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [joslat](https://github.com/joslat)
- **Source:** [joslat/maf-doctor](https://github.com/joslat/maf-doctor)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-joslat-maf-doctor-maf-migration-retrospective
- Seller: https://agentstack.voostack.com/s/joslat
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.