# X12 Writer Tool Notes

Use these notes after loading `x12-writer/SKILL.md` when you need deeper `write_x12` request-shape or recovery guidance.

## Tool Contract

- Tool name: `write_x12`
- Required parameter: `content` as a structured X12 JSON object.
- Required top-level content fields: `ISA` and `Groups`.
- Required group fields for the first group: `GS` and `Transactions`.
- Tool result: structured content and serialized JSON text with `success`, `ediContent`, and `errors`.

## Shape Rules

- `Groups` must be an array with at least one group.
- `Groups[0].GS.VersionAndRelease_8` supplies the X12 version for generation.
- `Groups[0].Transactions[0].ST.TransactionSetIdentifierCode_01` supplies the transaction set ID.
- ISA fixed-width fields should keep their expected spacing.
- Use the property names expected by Neutron's X12 JSON model, such as `InterchangeSenderID_6`, `VersionAndRelease_8`, and `TransactionSetIdentifierCode_01`.

## Response Fields

- `success`: `true` when X12 generation completed.
- `ediContent`: generated raw X12 text.
- `errors`: write or request-shape errors.
- `requestId` and `timestamp`: diagnostic metadata.

## Recovery Patterns

- "Content must contain a Groups array with at least one group." Add `Groups: [{ ... }]`.
- "Content must contain an ISA segment." Add top-level `ISA` under `content`.
- "First group must contain a GS segment." Add `Groups[0].GS`.
- "First group must contain at least one transaction." Add `Groups[0].Transactions` with an `ST` segment.
- If generation fails after the required shape is present, inspect the transaction-set fields and version.

## Safe Generation Pattern

1. Build the JSON.
2. Call `write_x12`.
3. If generation succeeds, optionally call `validate_x12` with `ediContent`.
4. If validation fails, report validation errors separately from write errors.
5. Only change business values when the user approves the correction.