functional-analysis-writer
Skill1 starsChanged 55 days agoMITView on GitHub
Author phase-G functional analysis for ONE mainframe or IBM i (AS400) COBOL source against the configured profile. Reads one prepared bundle and writes per-language section drafts or final functional-analysis.md. USE FOR: COBOL or ILE COBOL functional analysis, IBM i analysis, AFU sections, phase G authoring and finalization. DO NOT USE FOR: section docs, chunking, facts extraction, QA review, or portal build.
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
- group-doc-finalizerSkill
- qa-reviewerSkill
- requirements-finalizerSkill
- requirements-group-finalizerSkill
- requirements-group-writerSkill
- requirements-writerSkill
- section-doc-finalizerSkill
- section-doc-writerSkill
- technical-analysis-writerSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 2 are distinctive, and 10 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.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Use bundle source_platform to distinguish z/OS execution from IBM i jobs, native database files, DB2 for i, ILE calls, and commitment …
- Distinctive: line 34
Do not use this skill for:
- Very specific: line 99
Start with the H1 banner built from profile.front_matter.title_pattern (or the header section spec) with {{INTERFACE_NAME}} / {{ACRONYM}} …
- Very specific: line 125
Tombstone check: If docs/_shared/<file>/_fa-bundles/_skipped.json exists (copybook / BMS), the file is opted out of phase G.
- Distinctive: line 182
MUST emit a byte-identical bundle.
- Very specific: line 184
Never re-derive output paths — use bundle.output_paths verbatim.
- Very specific: line 185
Never load facts.json, complete.md, profile.yaml, or the full template.md at runtime — every bit of context lives in the bundle.
- Very specific: line 187
Never invent table rows, citations, or diagram nodes that have no anchor in facts_slice / chunk_excerpt / diagrams.
- Very specific: line 189
All requested drafts are co-authored in the SAME LLM call.
- Very specific: line 216
Profile drift: If profile.yaml is edited mid-flight, re-run stage-bundles.py --force so the cached bundle profile_sha matches.
- Very specific: line 219
Table fabrication: Every row in a profile-declared table MUST cite a fact / line range.
- Very specific: line 224
Co-authoring drift: When multiple languages are requested, drafts MUST share heading count, table row count, and [^src-N] ids.
≈ “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
Functional Analysis Writer (per-FA-section + per-file finalizer, phase G)
Use bundle source_platform to distinguish z/OS execution from IBM i jobs,
native database files, DB2 for i, ILE calls, and commitment control.
LLM-driven phase-G authoring skill. For ONE source file, produces a complete
the organization's functional-analysis document (functional-analysis.md) per
requested language. The skill operates in two scopes mirroring section-doc-writer:
| Scope | Reads | Writes |
per-section (LLM) | docs/_shared/<file>/_fa-bundles/<section_id>.bundle.md | docs/_shared/<file>/_fa-sections/<lang>/<section_id>.md per lang |
per-file (LLM) | docs/_shared/<file>/_fa-bundles/_finalize.bundle.md + drafts | docs/<lang>/<file>/functional-analysis.md per language |
Bundles are produced deterministically by scripts/stage-bundles.py
(per-section) and functional-analysis-finalizer/scripts/assemble-inputs.py
(per-file). The LLM call that fills the template is invoked by the
functional-analysis-writer agent. Mechanical compliance is verified by
qa-reviewer (kind: "functional-analysis")
immediately after each authoring call.
When to Use
- The user asks to "write the functional analysis", "produce the AFU document", "draft section 5.1 of the FA", "co-author EN + IT FA for DEMO100", "regenerate functional-analysis.md".
- A per-section FA bundle exists at
docs/_shared/<file>/_fa-bundles/<section_id>.bundle.md. - The per-file finalizer bundle
_finalize.bundle.mdexists and every per-section draft for the file has been authored.
Do not use this skill for:
- phase C per-section docs (
section-doc-writer), - chunking (
cobol-chunking), - facts extraction (
cobol-facts-extraction), - QA review of the produced FA (
qa-reviewer), - portal aggregation across files (phase N).
Output Contract
Per-section scope
For exactly each language <lang> in bundle.languages, in its declared order,
use bundle.output_paths verbatim. Never add an unrequested English edition or
intermediate; English is the default only when no language is provided.
docs/_shared/<file>/_fa-sections/<lang>/<section_id>.mdThis is an INTERMEDIATE artifact — never user-facing. The finalizer concatenates
these per-language drafts into the final functional-analysis.md.
The draft MUST:
- Begin with the section's H2 heading line built from
profile.section.numberandprofile.section.title(e.g.## 5.1 Business processes). Subsections use H3. - Honour
profile.section.required. If the section is optional and there is not enough evidence infacts_slice/chunk_excerptto write meaningful content, emit the heading followed by a single paragraph containing exactlyprofile.section.optional_marker(default"Paragrafo non necessario"in IT,"Section not applicable"in EN). - Respect
profile.section.min_paragraphsand anymin_sentences/min_wordsthresholds declared on the section. - Populate the table declared under
profile.section.table.columnsfrom the bundle'sfacts_slice— never invent rows. Use_None._(markdown italic) for genuinely empty cells, neverN/A. - Embed every diagram listed in
profile.section.embed_diagramsas an inline fenced```mermaidblock with the source taken VERBATIM from the bundle's## Diagramsblock. Do not re-author the diagram. - Cite source ranges via Pandoc footnote form
[^src-N]. Footnote definitions go at the BOTTOM of the per-section draft; the finalizer renumbers and consolidates them into a single## Sourcesblock at the end offunctional-analysis.md. - Identifier styling: COBOL/JCL identifiers MUST match
profile.identifier_lock_regex(default[A-Z][A-Z0-9-]*(\.[A-Z0-9-]+)?) and be wrapped in backticks. - For repeatable subsections (e.g.
profile.section.repeatable_subsections) emit one H3 per discovered item (fromfacts_slice.business_rules,facts_slice.trk_records, …) following thetemplate.required_paragraphsskeleton declared in the profile. - Author exactly the requested languages in the SAME LLM call. When multiple languages are requested, align heading structure, table row count, and citation footnote ids 1:1 so the qa-reviewer can compare them.
Per-file finalizer scope
For each language <lang>:
docs/<lang>/<file>/functional-analysis.mdThe document MUST:
- Start with the H1 banner built from
profile.front_matter.title_pattern(or theheadersection spec) with{{INTERFACE_NAME}}/{{ACRONYM}}substituted frombundle.front_matter_values. - Render the classification + metadata tables from
profile.front_matterwhenshow_classification/show_metadata_tableare true (default - Concatenate every per-section draft in profile order (the order produced
by
fa_profile_resolver.flatten_sections). Missing optional drafts are replaced by the heading +optional_markerparagraph. - Renumber the per-section
[^src-N]footnotes into one consolidated## Sourcesblock at the end of the document (each footnote definition kept verbatim, ids re-sequenced from 1). - Append the footer block from
profile.footerverbatim when present (e.g.V5.0.0+ the<!-- kpi-functional-analysis -->marker for the applicazione profile).
Procedure
- Resolve bundle input. Locate
docs/_shared/<file>/_fa-bundles/<section_id>.bundle.md(per-section) or_finalize.bundle.md(finalizer). If only the.bundle.jsonexists, re-runassemble-inputs.pyto regenerate the.mdview. On miss: exit4with the missing path. - Validate bundle schema. Required
## Metadatakeys per-section:bundle_version,source_path,profile_name,section.id,section.number,section.title,template_path,languages,facts_slice_sha,template_sha,profile_sha. Required## Output pathskeys: one per language. On miss: exit4. - Tombstone check. If
docs/_shared/<file>/_fa-bundles/_skipped.jsonexists (copybook / BMS), the file is opted out of phase G. PrintSKIP: <file> (<reason>)and exit0without writing anything. - Author. The agent reads the bundle and writes one
.mdper language at the exact path declared inbundle.output_paths.<lang>. The skill does NOT shell out to an LLM CLI — authoring is an agent responsibility. - Validate mechanically. Invoke
qa-reviewer--kind functional-analysisimmediately. Fail-fast: do not start the next section while findings remain. - Report. Print one summary line per language:
OK: wrote docs/_shared/<file>/_fa-sections/<lang>/<section_id>.md (words=…, sources=…)and the qa-reviewer verdict.
Bundle Schema (per-section)
{
"bundle_version": "1.0",
"scope": "per-section",
"source_path": "repos/sample1/COBOL/DEMO100.CBL",
"source_kind": "cobol",
"profile_name": "default
"profile_path": "config/templates/docs/functional-analysis/default
"profile": { /* full profile.yaml */ },
"profile_sha": "<64-hex>",
"section": { /* the profile.sections[] entry (with _id_path / _parent_id) */ },
"facts_slice": { /* section-scoped subset of facts.json */ },
"facts_slice_sha": "<64-hex>",
"chunk_excerpt": "…relevant heading-matched excerpt from bundle.languages[0]'s complete.md…",
"chunk_excerpt_sha":"<64-hex>",
"template_path": "config/templates/docs/functional-analysis/default
"template_snippet": "…the matching `## N. Title` block from template.<lang>.md…",
"template_paths_per_language": {
"en": "config/templates/docs/functional-analysis/default
"it": "config/templates/docs/functional-analysis/default
},
"template_sha": "<64-hex>",
"diagrams": [
{ "kind": "call-graph", "path": "docs/_shared/DEMO100.CBL/diagrams/call-graph.mmd",
"source": "flowchart TD\n…", "sha256": "<64-hex>" }
],
"front_matter_values": {
"ACRONYM": "DEMO100", "SSA": "AX", "INTERFACE_NAME": "DEMO100",
"CLASSIFICATION": "USO INTERNO", "AUTHORIZED_OFFICE": "Ufficio Sistemi Vigilanza",
"AUTHOR": "", "VERSION": "1.0", "CREATION_DATE": "", "STATE": "DRAFT"
},
"languages": ["en", "it"],
"output_paths": {
"en": "docs/_shared/DEMO100.CBL/_fa-sections/en/processi-business.md",
"it": "docs/_shared/DEMO100.CBL/_fa-sections/it/processi-business.md"
}
}Determinism Rules
- The bundle packagers are fully deterministic: re-running on unchanged inputs MUST emit a byte-identical bundle.
- Forbidden re-derivations from the authoring path:
- Never re-derive output paths — use
bundle.output_pathsverbatim. - Never load
facts.json,complete.md,profile.yaml, or the fulltemplate.mdat runtime — every bit of context lives in the bundle. - Never invent table rows, citations, or diagram nodes that have no anchor
in
facts_slice/chunk_excerpt/diagrams.
- Never re-derive output paths — use
- All requested drafts are co-authored in the SAME LLM call. Post-hoc translation
via a later
translatorfallback pass is permitted only to reconcile missing or drifted requested siblings when multiple languages are requested; never generate an unrequested language as an intermediate.
Resources
- scripts/assemble-inputs.py — deterministic per-section bundle packager.
- scripts/stage-bundles.py — bulk per-section bundle runner for ONE source file (also emits the
_finalize.bundle.jsonfor the finalizer scope). functional-analysis-finalizer— sibling skill that produces_finalize.bundle.json/.mdand (after authoring) the per-languagefunctional-analysis.md.scripts/lib/fa_profile_resolver.py— shared profile auto-detection (CPY/BMS skip, JCL/PRC → interfaccia, CBL+CICS → applicazione, else interfaccia).
Pipeline Wiring
config/pipeline-dag.yaml phase G lists functional-analysis-writer twice:
first at per-section scope (one LLM call per FA section), then at per-file
scope (finalizer). Each call is followed by a qa-reviewer step with
kind: "functional-analysis". Executable phase G requires F and the documentation
prerequisites A/B/C/D/E. The writer reuses bundle.languages[0]'s complete.md
narrative when building per-section excerpts. YAML selection of
output.generate.functional_analysis also selects group K and its I/J context;
disabling the requirements output does not remove these prerequisites.
Common Pitfalls
- Missing bundle. Author requires the bundle. Never read
facts.json,complete.md, orprofile.yamldirectly at runtime. - Profile drift. If
profile.yamlis edited mid-flight, re-runstage-bundles.py --forceso the cached bundleprofile_shamatches; the qa-reviewer fails fast on mismatched profile hashes. - Table fabrication. Every row in a profile-declared table MUST cite a
fact / line range. Empty cells use
_None._italic; the qa-reviewer flagsN/A,TBD,???aserror. - Diagram re-authoring. Diagrams are embedded VERBATIM from the bundle. The qa-reviewer compares the inlined fence with the bundle source byte-for-byte.
- Co-authoring drift. When multiple languages are requested, drafts MUST share heading count, table row
count, and
[^src-N]ids. The finalizer aborts on a structural diff.
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.

