Skip to content
Documentation

Legacy & Codebase Discovery — Archaeology Before Migration

FieldValue
TypeSkill Resource
Source~/.copilot/skills/architecture/references/discovery.md
DescriptionNot specified

Source Content

Legacy & Codebase Discovery — Archaeology Before Migration

A repeatable discovery playbook for any system that must be understood before it is changed — modern codebases and legacy platforms alike (IBM i/AS400 RPG, mainframe COBOL/JCL/VSAM, CICS, and “modern legacy” such as .NET Web Forms, end-of-life Java/J2EE, VB6, Oracle Forms, and classic PHP). AI is an archaeology tool here, not a migration engine — the wager is that the expensive, risky part of modernizing a system is understanding it, not converting its syntax.

The core principle: inventory → data model (ERD) → business rules → dependencies & batch schedule → golden-master tests → plain-English onboarding doc → scored retire/rehost/refactor/replace/rebuild disposition. The decision comes after the system is understood, never before. Validate the resulting docs/onboard.md with python3 ~/.copilot/skills/technical-writing/scripts/lint.py docs/onboard.md.

The 7-phase playbook (summary)

  1. Inventory — classify every artifact deterministically first. Run scripts/inventory.py <repo> for counts and a classified file table before spending context on any single program.
  2. Data model — decode DDS / DB2 / VSAM / copybooks into a logical ERD and a field dictionary. Extract the data before the logic; the record layout tells you what a program is about.
  3. Business rules — mine calculations, validations, and state transitions into a rule catalog, each entry citing the program and line range it came from.
  4. Dependencies & schedule — build the call graph, the file-usage (CRUD) matrix, the batch-job DAG, and the integration inventory.
  5. Tests — turn the mined rules and real record layouts into golden-master and edge-case scenarios that let a rewrite prove equivalence.
  6. Document — assemble everything into docs/onboard.md for a reader who has never seen the platform.
  7. Decide — score each subsystem on the disposition rubric (data gravity, rule volatility, coupling, latency/SLA, COTS fit) and recommend per subsystem, never per system.

Phases 1–4 are the load-bearing archaeology; phase 6 is the deliverable; phase 7 is the payoff. Never let a disposition get scored before phases 1–4 exist.

How to route within this subfolder

Identify the platform family first, then read the matching file in references/discovery/:

PlatformRead
RPG / DDS / CL (IBM i, AS400)references/discovery/ibm-i-as400.md
COBOL / JCL / VSAM (mainframe batch)references/discovery/mainframe-cobol.md
CICS / BMS online transactionsreferences/discovery/cics-online.md
.NET Web Forms, Java EE, VB6, Oracle Forms, classic PHPreferences/discovery/modern-legacy-platforms.md
Any platform — the full 7-phase methodreferences/discovery/discovery-playbook.md
Data model / ERD extraction and decode gotchasreferences/discovery/data-model-extraction.md
Business-rule miningreferences/discovery/business-rule-mining.md
Call graphs, CRUD matrix, batch DAG, integrationsreferences/discovery/dependency-mapping.md
Retire/rehost/refactor/replace/rebuild scoringreferences/discovery/modernization-strategy.md
Diagram skeletons (ERD, call graph, batch DAG, journeys)references/discovery/mermaid-legacy-patterns.md
Onboarding doc section structurereferences/discovery/onboard-template.md
Plain-English term decoderreferences/discovery/glossary.md
Public repos to practice onreferences/discovery/sample-corpora.md

House rules

  • Keep raw code reads out of the top thread. Delegate per-program reads to subagents that return a filled-in finding — a decoded layout, a rule entry, a dependency edge — not the source.
  • Cite the program and line range for every claim. An uncited rule, edge, or field decode is a hypothesis, not a finding.
  • Mark confidence. High for “the code plainly says this,” low for “inferred from a field name.” Low-confidence findings go on a validate-this list, not into the doc as fact.
  • Every diagram gets a “what to notice” line, and every explanatory section opens with a two-person story — both per the technical-writing skill, which owns diagram and Markdown rules.
  • Score dispositions per subsystem, never per system. One monolith usually contains a retire candidate, a COTS-replaceable module, and a genuinely custom rules engine that deserves a careful rebuild.

Pair with these skills

  • technical-writing — owns the Diátaxis mode, readability gate, two-person-story openers, Markdown mechanics, and the diagram rules for every Mermaid block in the onboarding doc.
  • database-designer — hand it the extracted ERD when designing the target schema.
  • ato-readiness — for public-sector targets, run the FedRAMP/800-53 control story in parallel with the rebuild.

Don’t use this for

  • Writing the migration itself — hand the artifacts to the relevant build skill (frontend, backend, platform) once discovery is done.
  • Greenfield schema design — that’s database-designer.
  • Generic prose docs with no legacy code to read — that’s technical-writing.