---
name: cobol-to-springboot
description: Migrate mainframe COBOL business capabilities to Java 25 and Spring Boot APIs, or audit and repair previously migrated Java for JABOL patterns. Use for copybooks, working-storage state, paragraph-shaped services, decimal arithmetic, CICS/Db2 transactions, batch restart, API contracts, and legacy equivalence evidence.
---

# COBOL migration and review

Use this skill in **migration** or **audit-and-repair** mode. Establish behavioral evidence and Java design quality separately. “JABOL” is an informal label for mechanical translation: loops, switches, and sequential orchestration alone are not defects.

## Shared discovery

1. Read the affected module's [project context](../java-spring-updates/references/project-context.md), architecture documents, and ArchUnit rules. Resolve the target versions. Follow existing placement and dependency directions; migration does not require microservices or a new folder structure.
2. Inventory COBOL programs, copybooks, called programs, compiler options/dialect, CICS/IMS/Db2/MQ/file dependencies, JCL, and existing recordings. Map the requested business slice and list unavailable artifacts. Use the [migration contract](references/migration-contract.md) to record source-to-target decisions and evidence.
3. Select only relevant rules below. Reuse [Java/Spring rules](../springboot-best-practices/SKILL.md) for records, domain validation, streams, sealed variants, and ordinary framework behavior.

| Trigger | Rule |
| --- | --- |
| Choosing a migration slice or missing source behavior | [Characterize before changing semantics](rules/migration-characterization.md) |
| One class per program, numbered paragraph methods, mutable context bags | [Assign domain responsibilities](rules/migration-domain-model.md) |
| WORKING-STORAGE fields, singleton services, repeated calls | [Preserve explicit state lifetimes](rules/migration-state-lifetime.md) |
| PIC/COMP-3, money, rounding, truncation, ON SIZE ERROR | [Preserve numeric semantics](rules/migration-decimal-semantics.md) |
| Copybook layouts, encoding, REDEFINES, OCCURS, level-88 conditions | [Isolate record translation](rules/migration-record-boundary.md) |
| SYNCPOINT, commits, status codes, API retries, external effects | [Map transactions and outcomes](rules/migration-transactions-errors.md) |
| JCL, file loops, checkpoints, restart, long API requests | [Preserve batch execution contracts](rules/migration-batch-restart.md) |
| Claims of equivalence, golden files, migration acceptance | [Require behavioral evidence](rules/migration-equivalence-evidence.md) |

## Migration mode

1. Define one bounded use case, its inputs/outcomes/effects, source references, and original unit of work. Capture a reproducible legacy baseline where available. Complete discovery when each required semantic decision is known or recorded as unresolved.
2. Map transport and storage representations at the existing integration boundary. Design domain values, behavior owners, and application orchestration from business responsibilities. Preserve observable behavior; stronger validation or different consistency requires a documented intended change.
3. Implement a vertical slice through the Spring API and existing persistence/integration boundaries. Keep generated compatibility code behind reviewed adapters when still needed. Define JSON/error contracts and retry behavior explicitly.
4. Run characterization/parity, API, transaction, concurrency/restart, architecture, and configured quality checks as applicable. Use [spring-verify](../spring-verify/SKILL.md). Unavailable mainframe execution does not prevent drafting or structural improvements, but leaves legacy parity unverified.

## Audit-and-repair mode

1. Record baseline test results and select the migrated paths. Run `node <plugin-root>/dist/cli.mjs migration-audit --root <repo> --path <migrated-path>`; repeat `--path` for another module. The command is read-only and reports candidates, including when no Maven POM exists yet.
2. Follow [review and repair](references/review-and-repair.md). For each candidate, inspect its callers, state lifetime, source traceability, generated-code ownership, and rule exceptions. Also review arithmetic, transactions, and restart contracts the scanner cannot infer.
3. Classify each finding as a confirmed behavioral defect, design/policy issue, legitimate compatibility exception, or unresolved evidence gap. Give a file/line, rule ID, observable consequence, and required proof. No candidate count or empty scan establishes acceptance.
4. Repair one responsibility or semantic defect at a time with a regression case. Re-run relevant comparisons and the complete configured gate after the final edit. Stop after three unsuccessful repairs of the same failure, or when the next change needs an unresolved semantic decision.

## Completion

Report the migrated/reviewed scope, source-to-target mapping, confirmed findings and exceptions, checks executed, comparisons performed, approved behavior differences, and unresolved gaps. Keep pre-existing failures visible. Report behavioral evidence and structural review separately. Claim legacy equivalence only within the exercised scenarios and known contract; compilation or Java-only examples cannot prove it.