End-to-end examples¶
These recipes start with deterministic extraction and progress to Copilot-authored deliverables. Run commands from the repository root. Replace sample paths only after the bundled examples pass.
Choose a workflow¶
| Goal | Phases | Model calls | Start with |
|---|---|---|---|
| Verify installation | A-C | No | One bundled COBOL program |
| Verify IBM i support | A-C | No | The five-member IBM i manifest |
| Inspect authoring work | D dry run | No | Existing A-C artifacts |
| Document one program | A-H, L | Yes | Skip group and portal phases |
| Document a workspace | A-N | Yes | Globs or a source manifest |
Example 1: extract one mainframe program¶
This is the fastest meaningful pipeline run. It parses ORDR100.CBL, extracts facts, performs
workspace cross-reference resolution, and writes one raw text file per chunk.
A successful run reports one successful source in each phase:
PHASE-DONE phase=A ok=1 failed=0 ... state=success
PHASE-DONE phase=B ok=1 failed=0 ... state=success
PHASE-DONE phase=C ok=1 failed=0 ... state=success
Inspect these checkpoints before using an LLM phase:
| Checkpoint | What to verify |
|---|---|
docs/_shared/ORDR100.CBL/chunk-manifest.json |
Platform, source kind, encoding, and chunk boundaries |
docs/_shared/ORDR100.CBL/facts.json |
Program ID, paragraphs, calls, copybooks, SQL, CICS, and data records |
docs/_shared/ORDR100.CBL/chunks/index.json |
One raw source slice for every documented chunk |
temp/example-mainframe/*.xml |
Per-file status and failure details for automation |
Example 2: extract the IBM i workspace¶
The manifest selects a CLLE controller, three ILE COBOL programs, and one copybook. Processing the members together allows phase B to resolve library-qualified calls into incoming references.
Expected result: phases A-C each report ok=5 failed=0. In the generated facts, confirm these
relationships:
ORDRJOB --CL CALL/SBMJOB--> ORDRINQ and ORDRUPD
ORDRUPD --COBOL CALL------> ORDRAUD
ORDRAUD --COPY------------> ORDAUDR
See IBM i sample repository for the source layout and DB2 for i behavior.
Example 3: stage section authoring without model calls¶
Run A-C first, then use the phase-D dry-run switch. This creates prepared bundles and a dispatch plan without submitting prompts to Copilot.
Review docs/_shared/ORDR100.CBL/_bundles/ and the dispatch plan under temp/. A bundle should
contain one chunk's source text, its fact slice, the selected profile, and authoritative output
paths. Fix configuration or stale deterministic artifacts before enabling model calls.
Example 4: document one program¶
After authenticating the GitHub Copilot CLI, run the per-file phases and omit workspace group
phases. -SkipDocx avoids a Pandoc dependency during the first authored run.
pwsh -NoProfile -File scripts/run-pipeline.ps1 `
-Files repos/sample/COBOL/ORDR100.CBL `
-SourceRoot repos/sample `
-Skip I,J,K,M,N `
-SectionFinalizerLanguages en,it `
-RequirementsLanguages en,it `
-FunctionalAnalysisLanguages en,it `
-TechnicalAnalysisLanguages en,it `
-SkipDocx `
-TechnicalAnalysisSkipDocx `
-MaxPhaseRetries 3
bash scripts/run-pipeline.sh \
-Files repos/sample/COBOL/ORDR100.CBL \
-SourceRoot repos/sample \
-Skip I,J,K,M,N \
-SectionFinalizerLanguages en,it \
-RequirementsLanguages en,it \
-FunctionalAnalysisLanguages en,it \
-TechnicalAnalysisLanguages en,it \
-SkipDocx \
-TechnicalAnalysisSkipDocx \
-MaxPhaseRetries 3
The principal English outputs are:
docs/en/ORDR100.CBL/index.md
docs/en/ORDR100.CBL/complete.md
docs/en/ORDR100.CBL/requirements.md
docs/en/ORDR100.CBL/functional-analysis.md
docs/en/ORDR100.CBL/technical-analysis.md
The same paths are produced under docs/it/. Reviews and language-neutral diagrams remain under
docs/_reviews/ and docs/_shared/ORDR100.CBL/.
Example 5: process a mainframe workspace¶
Use globs when the source tree follows predictable folders. In PowerShell, invoke the script in
the current process when passing an array; pwsh -File does not preserve an array argument.
Group phases are no-ops until config/grouping.yaml declares at least one group. Phase N builds
the generated-documentation portal under docs/_portal/; it is separate from this GitHub Pages
site.
Example 6: rerun a failed slice¶
Start with retries disabled while diagnosing a repeatable failure:
pwsh -NoProfile -File scripts/run-pipeline.ps1 `
-Phases D `
-Files repos/sample/COBOL/ORDR100.CBL `
-SourceRoot repos/sample `
-CopilotDocsDryRun `
-MaxPhaseRetries 0
After correcting the cause, rerun the same selection. Dispatch state allows completed work to be resumed; use a phase-specific force switch only when an otherwise current output must be rebuilt. See Run the pipeline for retry and force guidance.
Next steps¶
- Configure sources for your repository and encoding rules.
- Inspect generated artifacts before authoring documentation.
- Run the pipeline with deliberate phase, retry, and language choices.