copybook-to-dotnet

The full skill.

Original instructions from the publisher’s SKILL.md

# Copybook to .NET

Agent generates deterministic C# models, metadata, and tests from COBOL copybooks.

## When to Use

| Condition | Use |
|---|---|
| Work needs C# contracts generated from a copybook | Use this skill |
| Work needs Roslyn source generation for compile-time copybook models | Use this skill |
| Work needs fixed-width serialization metadata aligned to COBOL offsets | Use this skill |
| Work needs tests that lock field mapping and generated output | Use this skill |

## When Not to Use

| Condition | Route |
|---|---|
| Work needs copybook parsing or validation only | Use `mainframe-copybook-parsing` |
| Work needs byte-to-value conversion for raw mainframe files | Use `copybook-data-conversion` |
| Work needs handwritten domain models with no generation path | Use direct C# authoring |
| Work targets non-.NET consumers only | Use platform-specific generation |

## Required Inputs

| Input | Required | Notes |
|---|---|---|
| Parsed copybook model | Yes | Use a validated hierarchy with offsets and data types. |
| Namespace and output path | Yes | Record generated scope. |
| Emission model | Yes | Record class, record, or partial-type strategy. |
| Serialization attribute pattern | No | Record fixed-width library or repository-local attribute shape. |
| REDEFINES policy | No | Record alternate-view properties, union wrapper, or raw-span metadata. |

## Workflow

| Step | Action | Pass |
|---|---|---|
| 1 | Validate the parsed copybook model and reject blocking parse errors. | Input hierarchy has zero unresolved errors. |
| 2 | Map groups, elementary items, `OCCURS`, `REDEFINES`, and `FILLER` rules to deterministic C# shapes. | Every source element has one stable emission pattern. |
| 3 | Map PIC and USAGE metadata to C# types, offsets, lengths, scale, and converter metadata. | Every field keeps one stable type and layout contract. |
| 4 | Convert COBOL names and comments into PascalCase members and XML docs. | Public members follow naming and comment rules. |
| 5 | Choose Roslyn, CLI, or scripted generation and verify repeatable output plus targeted tests. | Generation is deterministic and happy, edge, and invalid-layout tests pass. |


## Hierarchy Matrix

| COBOL structure | C# emission pattern | Notes |
|---|---|---|
| Root `01` group | Top-level class or record | One file per root record |
| Nested group with business meaning | Nested type or sibling partial type | Pattern stays stable across regenerations |
| Elementary item | Property | Property carries length and offset metadata |
| `FILLER` item | No public property, optional private metadata row | Record length remains accurate |
| `OCCURS` group | Array or `List<T>` plus count metadata | Arrays fit fixed count layouts best |
| `REDEFINES` group | Alternate-view property set or overlay wrapper | Shared offset stays explicit |

## COBOL Data Type Mapping

| COBOL syntax | C# type | Metadata |
|---|---|---|
| `PIC X(n)` | `string` | Length attribute |
| `PIC 9(n)` | `int` or `long` | Length and numeric-style metadata |
| `PIC S9(n)V9(m)` | `decimal` | Scale metadata |
| `PIC S9(n)V9(m) COMP-3` | `decimal` | Packed-decimal converter attribute |
| `PIC 9(n) COMP` | `short`, `int`, or `long` | Binary converter attribute by dialect width |
| `PIC X(1) OCCURS n TIMES` | `string[]` or `char[]` | Element length and count metadata |
| Group item | Nested type | Group offset metadata |

## Mainframe Pattern Matrix

| Pattern | Emission rule | Generated artifact |
|---|---|---|
| `COMP-3` | Emit `decimal` property plus packed-decimal converter metadata | Property and converter attribute |
| EBCDIC source data | Keep encoding choice in reader layer, not model layer | Reader configuration hook |
| Fixed-width layout | Emit offset and length metadata on every elementary field | Attributes or generated descriptors |
| `OCCURS` | Emit arrays for fixed counts or `List<T>` for post-parse projection | Repeating group container |
| `REDEFINES` | Emit alternate view members with shared offset contract | Overlay descriptor or partial helper |
| COBOL comments | Emit XML doc comments on generated public members | `<summary>` blocks |

## Generation Matrix

| Condition | Pattern | Result |
|---|---|---|
| Build-time deterministic generation inside `src/ifx` or analyzer package | Roslyn source generator | Compile-time emitted models and diagnostics |
| Repository needs checked-in generated files | CLI or MSBuild task emission | Reviewable generated source |
| Mixed runtime and design-time consumers exist | Generate descriptors plus partial models | Shared metadata for readers and ORMs |
| One-off migration or discovery work | Scripted generator | Fast conversion with lower infrastructure cost |

## Integration Hooks

| Target | Result |
|---|---|
| Microsoft Fabric ingestion | Landing and silverization stages reuse one generated field contract. |
| EF Core storage | Staging entities preserve copybook lineage plus numeric precision and scale. |


## Before and After Example

```cobol
01 CUSTOMER-REC.
   05 CUSTOMER-ID     PIC 9(7).
   05 CUSTOMER-NAME   PIC X(30).
   05 CURRENT-BALANCE PIC S9(7)V99 COMP-3.
   05 STATUS-CODE     PIC X(1) OCCURS 3 TIMES.
```

```csharp
[FixedWidthRecord(Length = 45)]
public sealed partial class CustomerRec
{
    [FixedWidthField(Offset = 0, Length = 7)]
    public int CustomerId { get; init; }
    [FixedWidthField(Offset = 7, Length = 30)]
    public string CustomerName { get; init; } = string.Empty;
    [PackedDecimalField(Offset = 37, Length = 5, Scale = 2)]
    public decimal CurrentBalance { get; init; }
    [FixedWidthArrayField(Offset = 42, Count = 3, ElementLength = 1)]
    public string[] StatusCodes { get; init; } = [];
}
```


## Verification Checklist

| Check | Test | Pass |
|---|---|---|
| Front matter and STE wording | Run `npm run frontmatter:validate` and the modal-verb scan. | Front matter validates and banned modal verbs do not appear. |
| Naming, type, and layout fidelity | Compare COBOL names, PIC or USAGE metadata, and parsed spans to generated members. | Names stay deterministic and every emitted field preserves type, scale, offset, and length. |
| Repeatability and tests | Run the generator twice, then execute targeted generator or model tests. | Output diff is empty and happy, edge, and invalid-layout cases pass. |


## Common Pitfalls

| Pitfall | Agent Fix |
|---|---|
| Map `COMP-3` to `double` | Map packed decimal to `decimal` and preserves scale metadata. |
| Agent hides `REDEFINES` overlays behind duplicated offsets with no metadata | Emit one overlay contract with shared-span descriptors. |
| Agent drops COBOL comments during generation | Promote comments into XML docs on public members. |
| Use `List<T>` for every `OCCURS` | Agent prefers arrays for fixed-count record layouts. |
| Agent mixes handwritten edits into generated files | Agent isolates generated output and keeps custom behavior in partial types. |

## Outputs

| Output | Contents |
|---|---|
| Generated models | Types, properties, XML docs, and layout metadata |
| Generation path | Roslyn generator, CLI generator, or build task choice |
| Mapping contract | PIC-to-C# map with offsets, lengths, and scale |
| Test suite | Generator or model tests that lock deterministic output |