section-doc-writer
Skill1 starsChanged 55 days agoMITView on GitHub
Author phase-C markdown for ONE mainframe or IBM i (AS400) source chunk (COBOL, CBLLE, SQLCBLLE, CL, CLP, CLLE, JCL, PROC, copybook, BMS). USE FOR: document IBM i CL programs/commands, ILE COBOL, JCL steps, data records, and EXEC blocks. DO NOT USE FOR: chunking, facts extraction, slicing, QA, finalization, or file-level diagrams.
In this repository17 other files it gives its agents.
- chunk-text-extractionSkill
- cobol-chunkingSkill
- cobol-facts-extractionSkill
- diagram-rendererSkill
- facts-slicingSkill
- functional-analysis-finalizerSkill
- functional-analysis-group-finalizerSkill
- functional-analysis-group-writerSkill
- functional-analysis-writerSkill
- group-doc-finalizerSkill
- qa-reviewerSkill
- requirements-finalizerSkill
- requirements-group-finalizerSkill
- requirements-group-writerSkill
- requirements-writerSkill
- section-doc-finalizerSkill
- technical-analysis-writerSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 2 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Read source_platform from bundle metadata.
- Distinctive: line 29
Do not use this skill for:
- Distinctive: line 47
Never require or create an unrequested English edition or intermediate.
- Very specific: line 54
Follow the kind-specific template exactly (headings, sentence/paragraph minima, FORBIDDEN openers).
- Very specific: line 75
Validate bundle schema: Ensure the MD view contains every required block referenced in the Bundle Schema section below: ## Metadata (with …
- Very specific: line 84
If a subsection is genuinely empty after exhausting the bundle, write _None._ explicitly.
- Very specific: line 121
All sha256 fields are over the canonical byte form (template/source bytes UTF-8, facts_slice as json.dumps(..., sort_keys=True, …
- Very specific: line 128
Never re-derive output filenames from the chunk id.
- Very specific: line 129
Never load runtime inputs from facts.json, facts-slices, chunks, chunk-manifest.json, or chunks/index.json directly.
- Very specific: line 148
Output-path drift: If a downstream consumer derives the filename from the chunk id with its own ad-hoc regex instead of …
- Very specific: line 150
Co-authoring drift: When multiple languages are requested, factual and structural differences between their editions are flagged by …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Section Doc Writer (per-section, phase C)
Platform Contract
Read source_platform from bundle metadata. For ibmi, use IBM i/ILE,
library/object/member, native database file, DB2 for i, commitment-control, and
activation-group terminology only when evidenced. Never invent z/OS artifacts.
LLM-driven phase-C authoring skill. For ONE chunk, produces a single section markdown document per requested language by:
- Reading exactly one prepared bundle: the rendered Markdown view at
docs/_shared/<file>/_bundles/<chunk_id>.bundle.md. The.bundle.jsonsibling is the authoritative artifact (referenced by SHAs and consumed by the mechanicalqa-reviewerchecker); the.mdis a deterministic, regenerated projection optimized for LLM consumption — same data, headed sections + tables instead of nested JSON. - Using the bundle payload (
## Metadata,## Chunk,## Source text,## Facts slice,## Profile,## Template,## Output paths) as the complete authoring context. The## Templateblock only links to the template file attemplate_path(pinned bytemplate_sha); read that file to get the authoring rules — the body is not inlined in the MD view. - Emitting
docs/<lang>/<basename-with-ext>/sections/<chunk_id_sanitized>.mdper language plus the per-section Mermaid diagram.
The skill consumes an already-built deterministic bundle and defines the authoring contract; the LLM call that fills the template is invoked by the section-doc-writer agent. Mechanical compliance is verified by qa-reviewer immediately after.
When to Use
- The user asks to "write a section doc", "document chunk X", "author the markdown for paragraph A000-MAIN", "co-author EN + IT sections", or "regenerate the section docs for DEMO100".
- A bundle exists for the target chunk under
docs/_shared/<file>/_bundles/. - A single chunk needs to be re-authored on demand (
--chunk-id <id>).
Do not use this skill for:
- chunking (
cobol-chunking), - facts extraction (
cobol-facts-extraction), - per-chunk facts/source preparation (
facts-slicing,chunk-text-extraction), - QA review of the produced markdown (
qa-reviewer), - file-level
index.md/complete.md/ overview diagrams — those are owned by the per-filesection-doc-writerfinalizer step and thediagram-rendereragent (seeconfig/pipeline-dag.yamlphase C).
Output Contract
For chunk <chunk_id> of file <basename-with-ext>, for exactly each language
<lang> in bundle.languages, preserving its declared order:
docs/<lang>/<basename-with-ext>/sections/<chunk_id_sanitized>.mdThe authoritative output paths for the markdown(s) and Mermaid diagram come from bundle.output_paths — write to those exact paths. Do not re-derive filenames from the chunk id or from any chunks/index.json.
Never require or create an unrequested English edition or intermediate. English defaults only when no language is provided. Shared language-neutral diagrams remain shared, regardless of the requested documentation languages. English template headings do not add an English output; apply existing localization rules.
The markdown MUST:
- Follow the kind-specific template exactly (headings, sentence/paragraph minima, FORBIDDEN openers). Templates live under
config/templates/:Chunk kind Template paragraph,sectionprocedure-section-doc.template.mddivision(PROCEDURE)procedure-division.template.mddivision(DATA)data-division.template.mddivision(IDENTIFICATION)identification-division.template.mddivision(ENVIRONMENT)environment-division.template.mddata-record,copybook-recorddata-division.template.md(single-record mode)exec-sql,exec-cicsprocedure-section-doc.template.mdjcl-job,jcl-step,jcl-procjcl-job.template.md - Cite source ranges via Pandoc footnote form
[^src-N]defined in a trailing## Sourcesblock. Inline[FILE:Lx-Ly]tags are forbidden (seecitations-and-confidence.instructions.md). - Identifier styling: COBOL/JCL identifiers (program names, paragraphs, DD names, copybooks) MUST match the regex in the active
profile.yaml::identifier_lock_regex(default[A-Z][A-Z0-9-]*(\.[A-Z0-9-]+)?) and be wrapped in backticks. - Per-section overview diagram. The same authoring pass produces
docs/_shared/<basename-with-ext>/diagrams/section-<chunk_id_sanitized>.mmdusing the diagram-kind heuristic frompipeline-dag.yamlphase C (defaultflowchart TD;sequenceDiagramfor CICS;stateDiagram-v2for cursor lifecycles;erDiagramfor record-centric data chunks;flowchart LRfor copybook chunks — the sidecar carries the inclusion graph, NOT the structure / ER fragment which is owned bydiagram-rendereratdocs/_shared/<copybook>/diagrams/er-fragment.mmdand embedded verbatim by the copybook markdown; seeconfig/templates/copybook.template.md"DIAGRAM OWNERSHIP"). When a chunk's diagram gate fails (e.g. copybook with < 2 includers and noREPLACINGdivergence), the sidecar.mmdis NOT written and any stale file from a previous run is removed. No.svgrendering here — that is owned by phase D. - Be written in the requested language. When multiple languages are requested, align heading structure and citation footnotes 1:1 across those editions so
qa-reviewercan compare them.
A companion language-neutral JSON sidecar is emitted once per chunk, independent of the requested languages, at docs/_reviews/section-doc/<file>__<chunk_id>__inputs.json capturing the exact bundle the LLM received (template hash, slice hash, chunk-text hash, language list). This sidecar is the deterministic record needed to reproduce the authoring call.
Procedure
- Resolve bundle input. Locate
docs/_shared/<basename-with-ext>/_bundles/<chunk_id_sanitized>.bundle.md(LLM input). If only the.bundle.jsonexists, re-runassemble-inputs.py(orrender-bundle-md.py --in <bundle.json> --out <bundle.md>) to regenerate the MD view. On miss: exit4and report the exact missing path. - Validate bundle schema. Ensure the MD view contains every required block referenced in the Bundle Schema section below:
## Metadata(withbundle_version,source_path,source_kind,chunk.id,chunk.kind,diagram_kind,template_path,languages,chunk_text_sha,facts_slice_sha,template_sha),## Output paths,## Chunk,## Source text,## Facts slice,## Profile,## Template. On miss: exit4. - Author. The
section-doc-writeragent reads the bundle and writes one.mdper language plus the per-section.mmd. The skill does NOT shell out to an LLM CLI — authoring is an agent responsibility. - Populate Cross-references from the bundle. The
## Cross-referencesblock is NOT optional filler — it is the deterministic xref view for the chunk and MUST be filled from the bundle's## Facts sliceblock, not guessed:### Calls / uses (outgoing)— enumerate every entry in theperforms,calls,go_tos,copybooks,exec_sql(call/cursor targets) andexec_cics(LINK/XCTL/READ/WRITE targets) sub-sections of## Facts slicewhosechunk_idequals the current chunk. Each entry MUST include the target identifier, theviakind (PERFORM,CALL,GO TO,COPY,cics-link,cics-xctl,exec-sql, …) and the source line.### Called / used by (incoming)— copy every entry from theincoming_xreftable under## Facts slice(file-level: external programs / JCL steps / copybook consumers that reach THIS source file). For paragraph/section chunks, ALSO list intra-file PERFORM callers if they are discoverable from the bundle (e.g. thesiblingstable plus the parent chunk record under## Chunk). Each row MUST cite the caller source path and line.### Data touched (records read / written by this section)— REQUIRED on procedure paragraphs / sections / divisions, onexec-sqlandexec-cicschunks, and ondata-record/copybook-recordchunks. For each01-level (or elementary field) the chunk reads or writes, list: data name, mode (R/W/R/W/INIT), verb (READ,WRITE,MOVE,EXEC SQL FETCH,EXEC CICS RECEIVE MAP,CALL … USING, …), the source file that DECLARES the record (the current source for in-line records; the copybook member forCOPY-included records), and every OTHER workspace source that also touches the same record. Cross-source partners are derived from the file-levelincoming_xref[]rows whosevia == "copy"(programs that include the same copybook layout) and from thedata_records[]/copybooks[]projections under## Facts slice. Use_None._when the record is private to this program; never silently omit the table.### File / dataset bindings— REQUIRED on every chunk that opens, reads or writes an external file (procedure sections issuingOPEN/READ/WRITE,data-divisionchunks declaringFD/SELECT,jcl-stepchunks declaringDDstatements). Build by joining the file-levelfiles[]slice (logical SELECT/FD ↔ external DDNAME ↔ DSN) with every JCL step recorded in the bundle'sincoming_xref[](rows withvia == "jcl-step") — those rows pin the JCL source file and step that schedules this program. For JCL chunks, the dual table (### DDNAME ↔ program data bindings) joins eachDDto the FD/SELECT and01-level inside the invoked program; when the invoked program'sfiles[]/data_records[]are NOT embedded in this bundle, mark the partner cells as—and surface a_Warnings_bullet explaining the missing cross-source data — never guess.### External dependencies— datasets / DD names / SQL tables / CICS maps / external programs referenced by the chunk (from thefiles,jcl_steps,exec_sql,exec_cics,bms_mapssub-sections under## Facts slice).- For data chunks (
data-record,copybook-record,data-division), additionally fill### Producers (write the record),### Consumers (read the record)and### Shared layout/### Workspace data lineagefromincoming_xref[](via == "copy"rows andvia == "jcl-step"rows when the dataset bound to an FD is also referenced by a JCL DD) — workspace scope, not just the current source file. - If a subsection is genuinely empty after exhausting the bundle, write
_None._explicitly. Never silently omit a subsection. NEVER guess aDSN, an FD binding or a caller that is not present in the bundle; surface the gap as a_Warnings_bullet instead.
- Validate mechanically. Immediately invoke
qa-revieweron the produced markdown. Fail-fast: do not move on to the next chunk while findings remain. - Report. Print one summary line per requested language:
OK: wrote docs/<lang>/<file>/sections/<chunk_id>.md (words=…, sources=…, diagram=…)and the qa-reviewer verdict.
Bundle Schema
Two sibling artifacts live next to each other under docs/_shared/<file>/_bundles/<chunk_id>.bundle.{json,md}:
.bundle.json— authoritative; consumed by the mechanicalqa-reviewerchecker (check-section-doc.py), tracked byscripts/dispatchers/run-docs-copilot-batch.ps1's SHA/state map, and referenced by all three SHA fields. Schema below..bundle.md— LLM input; deterministic Markdown projection rendered by scripts/render-bundle-md.py and emitted automatically byassemble-inputs.py --out. Same data, headed sections + tables for easier reading. Never edit by hand.
The authoritative JSON MUST contain (top-level keys, in this order):
{
"bundle_version": "1.0",
"source_path": "repos/sample1/COBOL/DEMO100.CBL",
"source_kind": "cobol|cl|jcl|proc|copybook|bms",
"chunk": { /* embedded chunk record */ },
"chunk_text": "…raw source bytes of the chunk, LF-normalized…",
"chunk_text_sha": "<64-hex>",
"facts_slice": { /* embedded per-chunk facts subset */ },
"facts_slice_sha": "<64-hex>",
"template_path": "config/templates/procedure-section-doc.template.md",
"template_text": "…full template…",
"template_sha": "<64-hex>",
"profile": { /* loaded profile.yaml (thresholds, identifier regex, citation policy) */ },
"languages": ["en", "it"],
"diagram_kind": "flowchart TD | flowchart LR | sequenceDiagram | stateDiagram-v2 | erDiagram",
"output_paths": {
"en": "docs/en/DEMO100.CBL/sections/DEMO100__procedure-division__MAIN-PROCESSING__A000-MAIN.md",
"it": "docs/it/DEMO100.CBL/sections/DEMO100__procedure-division__MAIN-PROCESSING__A000-MAIN.md",
"diagram":"docs/_shared/DEMO100.CBL/diagrams/section-DEMO100__procedure-division__MAIN-PROCESSING__A000-MAIN.mmd"
}
}All sha256 fields are over the canonical byte form (template/source bytes UTF-8, facts_slice as json.dumps(..., sort_keys=True, separators=(",",":")) to keep the hash stable).
Determinism Rules
- The bundle packager is fully deterministic: re-running on unchanged inputs MUST emit a byte-identical bundle.
- The LLM authoring step is NOT deterministic — that is expected. What IS deterministic is the shape: same template, same citation footnotes, same identifier styling, same diagram-kind heuristic, same thresholds.
- Forbidden re-derivations:
- Never re-derive output filenames from the chunk id; always use
bundle.output_pathsverbatim. - Never load runtime inputs from
facts.json,facts-slices,chunks,chunk-manifest.json, orchunks/index.jsondirectly. Use the prepared bundle only.
- Never re-derive output filenames from the chunk id; always use
- Requested editions are authored in the same LLM call. With multiple requested languages,
translatormay repair a missing or drifted requested sibling; it must never create an unrequested English intermediate.
Resources
- Runtime input (LLM): the rendered Markdown view at
docs/_shared/<file>/_bundles/<chunk_id>.bundle.mdis the canonical runtime input for the authoring step. - Runtime input (mechanical tooling): the sibling
.bundle.jsonis the authoritative artifact for SHAs, output_paths parsing, and theqa-reviewerchecker. - Bundle producers (out-of-band):
- scripts/assemble-inputs.py — packages one bundle from
chunk-manifest.json+chunks/index.json+facts-slices/<chunk>.json+ template + profile; writes both the.bundle.jsonand the.bundle.mdview (suppress the MD via--no-md-view). Run upfront; never invoked from the authoring path. - scripts/render-bundle-md.py — standalone renderer (
--in <bundle.json> --out <bundle.md>); used to backfill the MD view if it is missing. - scripts/stage-bundles.py — bulk runner for
assemble-inputs.pyacross every chunk of one source.
- scripts/assemble-inputs.py — packages one bundle from
Pipeline Wiring
config/pipeline-dag.yaml phase C lists section-doc-writer as the per-section LLM step with the per-chunk bundle JSON as its single input. The deterministic bundle-producer half lives in scripts/stage-bundles.py (which invokes scripts/assemble-inputs.py per chunk). The LLM authoring half is owned by .github/agents/section-doc-writer.agent.md and orchestrated by .github/agents/section-agent.agent.md (writer + reviewer loop).
Common Pitfalls
- Missing bundle. This skill requires a prepared bundle per chunk. Do not bypass the bundle by reading
facts.json,facts-slices, orchunksdirectly in runtime authoring. - Output-path drift. If a downstream consumer derives the filename from the chunk id with its own ad-hoc regex instead of
bundle.output_paths, it will mis-bind in the presence of phase-A renames. Always usebundle.output_pathsverbatim. - Authoring without QA. Skipping the immediate
qa-reviewercall lets mechanical violations (forbidden openers, missing citations, line-count mentions in prose) accumulate silently. Run it after every authoring call, not as a batch sweep. - Co-authoring drift. When multiple languages are requested, factual and structural differences between their editions are flagged by
qa-reviewer. Co-author those requested languages in the same LLM call; do not create an unrequested translation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

