Onboarding Document Template (`docs/onboard.md`)
| Field | Value |
|---|---|
| Type | Skill Resource |
| Source | ~/.copilot/skills/architecture/references/discovery/onboard-template.md |
| Description | Not specified |
Source Content
Onboarding Document Template (docs/onboard.md)
The fixed section structure for the discovery deliverable — the plain-English docs/onboard.md that phase 6 of the playbook produces. It exists so that any future run against any legacy system yields a document a reader who has never seen a green screen can finish and act on. Follow the section order below exactly; a consistent shape is what lets a reader who has read one onboard doc read the next one in half the time.
This is a reference and template, not a finished doc — so it does not itself open with a two-person story. The document you produce from it must. Section 2 below is where that story lives.
Contents
- How to use this template
- Section 1 — TL;DR
- Section 2 — The business, in two people
- Before you begin — orientation for newcomers
- Section 3 — Platform and tech snapshot
- Section 4 — Inventory summary
- Section 5 — Domain model
- Section 6 — Core workflows
- Section 7 — User journeys
- Section 8 — Business-rule catalog
- Section 9 — Batch schedule and job DAG
- Section 10 — Integration points and system context
- Section 11 — Data quality and decode gotchas
- Section 12 — Open questions and unknowns
- Section 13 — Modernization candidates
- Section 14 — Appendix and glossary
How to use this template
Copy the fourteen ## sections in order into docs/onboard.md and fill each one. Keep the numbering and the titles — the number is how a reviewer and a future run cross-reference a section. Delete nothing: if a section has no findings, keep the heading and write one line saying so, because a silent gap reads as “fully understood” when it isn’t (see section 12).
Three rules bind every section:
- Decode every platform term on first use. The first time the doc says DDS, COMMAREA, VSAM, subfile, or COMP-3, gloss it in one clause and link to glossary.md. Assume the reader has never seen the platform.
- Every diagram earns a “what to notice” line directly beneath it — one sentence naming the boundary or takeaway the diagram teaches (per the
technical-writingskill, which owns the diagram rules). A diagram without that line is unfinished. - Every diagram follows mermaid-legacy-patterns.md, which holds the canonical skeleton for each diagram this template calls for. Do not hand-roll a diagram type that reference already defines.
- Open with the newcomer primer. Include the “Before you begin” orientation block (spec below) between the TL;DR and section 3. It is what lets a reader who has never seen a mainframe or IBM i get through the rest — decoding terms only on first use is not enough when the same acronym reappears 40 times.
Run the gates before handoff: technical-writing’s scripts/readability.py, the markdown linter, and the mermaid linter on the finished file.
Section 1 — TL;DR
Purpose: one paragraph a non-technical executive reads and understands. What does this system do for the organization, and why does it exist? Name the business it runs — claims, benefits, licensing, payroll — not the technology. A reader of only this paragraph must come away with both the claim (what it does) and the consequence (why it still matters).
Content: two to four sentences. No platform jargon at all in this section — it is the one place the reader should never meet an undecoded term. State the mission, the population it serves, and the stakes if it stopped.
Diagram: none. Prose only.
Section 2 — The business, in two people
Purpose: frame the business domain through a short two-person story, and open the whole document with it (per the technical-writing skill’s house rule). The story sits at the very top of the rendered doc — picture first, explanation after. One person hits the problem the system solves and its consequence; the other takes the path the system provides and its outcome.
Content: one short story, cast from the persona roster in the technical-writing skill’s style guide — never default names. Make the two people real roles in this domain: a claimant and a caseworker, an employer and an auditor, an applicant and a licensing clerk. The story teaches what the system is for before any section explains how it works.
Diagram: none — the story carries this section. Keep it under a few sentences per person.
Before you begin — orientation for newcomers
Purpose: a 60-second on-ramp for a reader who has never touched a mainframe, IBM i, RPG, or COBOL. It renders right after the TL;DR (section 1) and before the platform snapshot (section 3), so a newcomer meets the vocabulary once, plainly, before the technical sections start using it. Without it, a reader who has only seen modern stacks stalls on the first COMP-3 or CICS and never reaches the findings that matter.
Content: two short parts.
- What you’ll see in this doc, one line each. A compact list of ONLY the terms that actually appear in this document — not the whole glossary — grouped as: the machine and OS, the language(s), the data stores, the screens, and the “gotcha” data formats. One term per line, plainest possible English, with no second piece of jargon hiding inside a definition. Aim for 8–15 terms and link glossary.md for the rest.
- If you know modern systems, here’s the rough analogy. A short table mapping each legacy concept the doc uses to the closest thing a modern developer already knows, drawn from the legacy → modern analogy quick-map. Label the analogies as approximate — they orient a newcomer, they do not make them an expert.
Tailor both parts to the sample: an IBM i doc orients on RPG / DDS / 5250 / data area; a CICS doc on transaction / BMS / COMMAREA / VSAM; a COBOL batch doc on JCL / copybook / COMP-3 / VSAM. Never define a term the document does not use — this block is a map of this doc, not of the platform.
Diagram: none. A tight list and a two-column analogy table are the whole section.
Section 3 — Platform and tech snapshot
Purpose: tell the reader, in one glance, what they are looking at technically. This is the orientation section — languages, database, screen technology, and the batch-versus-online split, sized from the inventory.
Content: a key: value list, one pair per line (never chained inline). Decode each platform term on first use against glossary.md. Cover at least:
- Platform family: IBM i / AS400, mainframe COBOL, CICS, or a mix
- Languages: RPG (III / IV / free), COBOL, CL, JCL — with rough proportions
- Database / data stores: DB2 for i, VSAM (KSDS / ESDS / RRDS), flat files
- Screen technology: 5250 display files (DDS/DSPF) or CICS BMS 3270 maps
- Batch vs. online split: how much runs unattended vs. interactive
- Size: total programs, files, and lines, from section 4
Diagram: optional. If the system spans more than one platform family, a small flowchart grouping the families by subgraph helps; otherwise the list is enough. If drawn, follow the call-graph or context skeleton in mermaid-legacy-patterns.md.
Section 4 — Inventory summary
Purpose: report the deterministic count of what is in the repo, so no later section can silently drop an artifact. This is the ground truth the rest of the doc is measured against.
Content: the output of scripts/inventory.py, summarized. Lead with a counts table (artifact type × count), then call out the notable programs and files — the largest, the most-called, the ones whose names map to the business (a CLMMAST claims master, a BENCALC benefit calculator). Note anything the classifier could not type, and why. When this doc corrects a classification the deterministic inventory.py got wrong (a CICS-online program the script tagged batch), say so explicitly — name the file, the wrong tag, and the right one — so the tool’s limits stay visible rather than silently patched. Do not paste the full per-file list here; link to the generated inventory table or CSV and keep this section to the summary.
Diagram: none. A counts table does the work.
Section 5 — Domain model
Purpose: show the data the system is about, reverse-engineered into a logical entity-relationship diagram (ERD) plus a field-dictionary highlight reel. The record layout is what the system means; read it before the logic.
Content: the logical ERD, then a short field dictionary for the highest-value fields — keys, status codes, amounts, dates — with their decoded types (packed decimal scaled, zoned decimal, EBCDIC, implied decimal), not the raw PIC or DDS. Cross-reference data-model-extraction.md for the full field dictionary and the decode-gotcha catalog; keep this section to the highlights. Flag any entity whose layout was inferred rather than read, and carry that flag to section 12.
Diagram: a Mermaid erDiagram — the Logical ERD skeleton in mermaid-legacy-patterns.md. Add the “what to notice” line beneath it.
Section 6 — Core workflows
Purpose: show how the system’s main processes move — the two or three flows that carry most of the business (submit a claim, calculate a benefit, run the nightly close). A workflow is a sequence with decisions; draw it, don’t narrate it.
Content: one flowchart per core workflow, each with a short prose lead and a “what to notice” line. Group each flowchart by the most meaningful boundary — what people do vs. automation when both are present, or phase otherwise. Keep each to five to seven nodes; split a big flow into two diagrams rather than crowd one.
Diagram: Mermaid flowchart per workflow — the Program Call Graph or workflow skeleton in mermaid-legacy-patterns.md. Each diagram gets its own “what to notice” line.
Section 7 — User journeys
Purpose: show what a person at a green screen actually experiences — the 5250 or CICS journey through the panels. Because a CICS transaction is pseudo-conversational, it is a state machine; a linear flowchart would lie about it (see cics-online.md).
Content: one state diagram per significant journey, keyed to the screens (DDS display files or BMS maps) and their function-key branches. Name each state for the panel the user sees; label transitions with the key pressed (Enter, PF3, PF7/PF8). Decode 5250, subfile, BMS, and COMMAREA on first use against glossary.md.
Diagram: Mermaid stateDiagram-v2 — the Green-Screen User Journey skeleton in mermaid-legacy-patterns.md. Add the “what to notice” line.
Section 8 — Business-rule catalog
Purpose: surface the top business rules the code enforces — the eligibility calculations, status transitions, validations, and edit routines that are the actual value of the system. These are what a rebuild must reproduce and what a golden-master test pins.
Content: the highest-value rules as a numbered catalog, each entry citing the program or procedure and line range it came from, plus its inputs, output, and trigger. Do not list every rule here — list the ones that drive money, eligibility, or a status change, and link to business-rule-mining.md for the full catalog and the mining method. A rule the reader cannot trace back to a line of code is a claim, not a finding.
Required element — golden-master & edge-case scenarios: a short table of concrete test cases, not a strategy paragraph. Seed it from the mined rules and from any reject or abend codes surfaced in discovery, so each row is a real record run against a named rule. This table is what phase 5 test generation turns into a golden master; without it, a reader gets the strategy but never the specific case a rebuild must pass.
| Scenario | Input (a real record/value) | Expected output | Rule it pins (cite catalog entry) |
|---|---|---|---|
| High-quarter wage benefit | WAGE.HQ_AMT = $9,100.00 | BENEFIT_AMT = $350.00 (÷26, floored) | BR-014 (CALCBEN.RPGLE:210-268) |
| Below-minimum earnings deny | Base-period wages = $1,400.00 | Status 'D', DENY_RSN = 100 | BR-021 (CHKELIG.RPGLE:88-141) |
| Weekly cap applied | WAGE.HQ_AMT = $20,000.00 | BENEFIT_AMT = state max, not $769.23 | BR-014 (CALCBEN.RPGLE:210-268) |
What to notice: every row names a specific input value and the catalog entry it exercises, so a reviewer can run the case and a rebuild can prove equivalence — a scenario that cites no rule is a test with nothing to pin.
Diagram: optional. If a rule set is really a decision table (a COBOL EVALUATE, an RPG select), a small flowchart with { } decision nodes can help; otherwise the catalog text is enough.
Section 9 — Batch schedule and job DAG
Purpose: make the nightly cycle explicit — which jobs run, in what order, with which dependencies and timing windows. The batch schedule is where “it breaks at 2 a.m.” lives; it must be drawn, not implied.
Content: the job dependency graph as a directed acyclic graph (DAG), grouped by schedule window (evening, overnight, morning). Name each job, what it reads and writes, and what must finish before it starts. Note the scheduler that holds the true order (Control-M, CA-7, TWS on the mainframe; a CL driver and job queue on IBM i). Cross-reference dependency-mapping.md for the method and the full job list.
Diagram: Mermaid flowchart LR — the Batch-Job DAG skeleton in mermaid-legacy-patterns.md, grouped by window via subgraph. Add the “what to notice” line.
Section 10 — Integration points and system context
Purpose: draw the system’s edges — every external feed, vendor, downstream consumer, and report that crosses the boundary. Modernization risk lives at the seams; a system with twelve undocumented feeds is a different project from one with two.
Content: a system-context diagram with the legacy system in the center and its integrations around it — inbound feeds, outbound files, vendor APIs, federal reports, downstream systems. For each edge, note the direction, the transport (file drop, data queue, MQ, batch report), and the cadence (real-time, nightly, monthly). Flag any integration inferred from a filename or JCL step rather than confirmed.
Diagram: a Mermaid flowchart — the Integration / System-Context skeleton in mermaid-legacy-patterns.md. This is a multi-layer diagram: every layer (the legacy core, inbound feeds, outbound consumers, vendors) gets its own shape and muted color per the technical-writing skill’s system-node palette. Add the “what to notice” line.
Section 11 — Data quality and decode gotchas
Purpose: record the traps found while decoding — the places where the stored data does not mean what a naive reader would assume. These are the landmines a migration steps on if this section is missing.
Content: a list of concrete gotchas discovered, each with where it was found and what it does. Typical entries: packed-decimal or zoned fields that need scaling, REDEFINES overlays where one field carries two meanings, dates stored as YYYYMMDD integers or worse, EBCDIC text that must be transcoded, OVRDBF in CL where the code says one file and production uses another, magic values in status codes. Cross-reference data-model-extraction.md, which holds the full decode-gotcha catalog.
Diagram: none. A list of concrete traps is clearer than a picture.
Section 12 — Open questions and unknowns
Purpose: bound the discovery honestly. State plainly what was not read, not decoded, or assumed — because a doc that hides its gaps reads as complete when it isn’t, and that false confidence is what burns a migration.
Content: three explicit lists, each item traceable to the section it affects:
- Not read: programs, copybooks, or JCL that were inventoried but never opened, with why (out of scope, no source, time)
- Not decoded: layouts or fields whose meaning is still unknown, or entities inferred rather than confirmed
- Assumed: anything the doc treats as fact but is a reasonable guess — mark these in-text as
[VERIFY]and collect them here
Diagram: none. Honesty is a list, not a picture.
Section 13 — Modernization candidates
Purpose: turn the discovery into a per-subsystem disposition, so the reader sees where the migration decision is heading — without pretending the decision is final. This is the payoff, and it is scored per subsystem, never per system.
Content: a disposition table — one row per subsystem, scored on the rubric and ending in a recommended R (retain, retire, rehost, re-platform, refactor, rebuild, replace). One monolith usually holds a retire candidate, a COTS-replaceable module, and a genuinely custom rules engine that deserves a careful rebuild. Cross-reference modernization-strategy.md for the rubric and the scoring method; each recommendation must cite the factors that drove it.
The table earns a discriminating column — one that turns each row into a testable condition, so a reviewer can check the call rather than trust it:
| Subsystem | Data gravity | Rule volatility | Coupling | COTS fit | Recommended R | How you’d confirm the call |
|---|---|---|---|---|---|---|
| Claims intake | High | Low | Medium | Poor | Rebuild | Golden-master tests still pass on the rebuilt intake |
| Employer registry | Medium | Low | Low | Strong | Replace | A COTS registry covers every field in the current layout |
| Report generator | Low | Low | Low | - | Retire | No downstream consumer reads its output anymore |
What to notice: the last column converts each disposition from an opinion into something a reviewer can test — a recommendation you can’t confirm is a guess.
Diagram: the table is the deliverable. A small flowchart mapping subsystems to their R can supplement it, but the scored table is required.
Section 14 — Appendix and glossary
Purpose: give the reader the reference shelf — every term decoded, every companion artifact linked. This is where a reader who got lost mid-document goes to catch up.
Content: a link to glossary.md for the full term decoder, plus links to the companion artifacts this run produced — the inventory table/CSV, the full field dictionary in data-model-extraction.md, the full rule catalog in business-rule-mining.md, the dependency map in dependency-mapping.md, and the disposition scoring in modernization-strategy.md. List any per-term glosses this doc introduced that are not yet in the glossary.
Diagram: none.