SuperAPI AI Directory

fix-atx-datapath-errors

Coding & development

View repository

Updated 11-12 00:43

About this skill

Fix AWS Transform for Mainframe (ATX) Codebase Issues

When to use

The AWS Transform job's "Discover data paths" step reports extraction Errors/Warnings on COBOL/copybook/BMS/JCL artifacts, and you need to find the root cause, fix what's safe to fix, remove what isn't, and report on it.

Required inputs (ask for both if missing)

Expected in the user's current workspace under input/. If input/ or output/ don't exist yet, create them and ask the user to place the files below in input/:

  1. bre_transform_debug_*.zip — AWS Transform console: job → Artifacts tab → 1 → artifact-slicing (numbering may vary). Download as-is, do not re-zip or rename internal paths.
  2. The original source zip submitted to the AWS Transform job (same COBOL/copybook/BMS/JCL/PROC tree). Required for full context and to write the fixed target zip — do not proceed with only the debug bundle.

Workflow

Scripts are in this skill's scripts/ folder (Python 3 stdlib only). Run them from the user's workspace root and write outputs to output/. Set SKILL to the absolute path of the directory containing this SKILL.md — it differs per tool and install method (plugin cache, ~/.kiro/skills/, .claude/skills/, .agents/skills/, ...). Run in order:

SKILL=/absolute/path/to/fix-atx-datapath-errors   # dir containing this SKILL.md

# 1. Parse the debug bundle
python3 $SKILL/scripts/parse_debug_bundle.py \
  --bundle input/bre_transform_debug_*.zip --out output/findings.json

# 2. Correlate against source (resolves COPY-expanded line numbers to real
#    file/line, then classifies each finding via an extensible pattern
#    library — see references/error_taxonomy.md)
python3 $SKILL/scripts/correlate_with_source.py --findings output/findings.json \
  --source-zip input/full_source.zip --out output/annotated_findings.json

# 3. Apply safe, mechanical-only fixes; write a new target zip
python3 $SKILL/scripts/apply_fixes.py --annotated output/annotated_findings.json \
  --source-zip input/full_source.zip --out-zip output/target_fixed.zip \
  --changelog output/changelog.json --remove-unfixable

# 4. Generate the report
python3 $SKILL/scripts/generate_report.py --annotated output/annotated_findings.json \
  --changelog output/changelog.json --out output/report.md

# 5. After any manual/LLM triage, capture what was learned for reuse
python3 $SKILL/scripts/capture_learnings.py --annotated output/annotated_findings.json \
  --changelog output/changelog.json --list --skeleton-out output/resolutions.skeleton.json
#   ...fill in output/resolutions.json from the skeleton, then:
python3 $SKILL/scripts/capture_learnings.py --annotated output/annotated_findings.json \
  --changelog output/changelog.json --resolutions output/resolutions.json \
  --learnings-log output/learnings.jsonl --out output/learnings_summary.md

The learnings log is written to the workspace, not the skill folder: installed plugin/skill folders may be read-only and are replaced on update. To share a learning, contribute it back to the source repository (references/learnings.jsonl or a new PATTERN_LIBRARY matcher) via pull request.

Deliverables: output/report.md + output/target_fixed.zip (+ output/changelog.json for machine-readable detail). Step 5 is optional but should be run before closing out an engagement whenever manual triage happened.

Read before extending or fixing by hand

references/error_taxonomy.md — worked examples of known patterns, the COPY-expansion line-number gotcha, and how to add new pattern matchers. Read it before writing a new matcher or hand-editing a finding.

Guardrails

  • AWS Transform line numbers refer to the COPY-expanded source, not the raw file — never edit at the raw line number (step 2 resolves this).
  • Never "fix" a cascading false positive (e.g. a label that already exists, or a note that says "no functional impact"). Fix the real upstream issue instead.
  • Never guess at business logic. Automated fixes are pure reformats only (moving existing characters); anything requiring judgment goes to manual review.
  • Prefer removing an unfixable file over a risky guess.
  • Do not embed customer source, program names, or business data in this skill's own files or in captured learnings logs — describe root causes/fixes in plain, non-identifying language.
  • Root causes are open-ended — a large "needs manual review" count is normal, not a bug. Don't force-fit findings into existing categories.
  • Promoting a learning into PATTERN_LIBRARY/AUTO_FIX_CATEGORIES is a deliberate, reviewed code change, never automatic — and never for a fix that changed business logic.