functional-analysis-finalizer
Skill1 starsChanged 55 days agoMITView on GitHub
Author phase-G per-file `functional-analysis.md` for ONE mainframe or IBM i (AS400) source from its prepared section drafts. LLM-driven. USE FOR: assemble IBM i or mainframe functional analysis, stitch FA sections, and phase-G finalization. DO NOT USE FOR: per-section authoring, index/complete, QA, 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-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
- section-doc-writerSkill
- technical-analysis-writerSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Never require or create an unrequested English edition or intermediate.
- Very specific: line 23
Every per-section FA draft for the file has been authored and passed qa-reviewer (kind: "functional-analysis").
- Distinctive: line 28
Do not use this skill for:
- Distinctive: line 60
When multiple languages are requested, align heading structure, table row count, and consolidated footnote ids 1:1 across those languages …
- Very specific: line 70
Tombstone check: If _fa-bundles/_skipped.json exists, the file is opted out of phase G entirely.
- Very specific: line 143
Never re-derive output paths — use bundle.output_paths verbatim.
- Very specific: line 144
Never load facts.json / profile.yaml / per-section drafts directly at runtime — every byte lives in the bundle.
- Very specific: line 170
Front-matter fabrication: Every {{PLACEHOLDER}} MUST resolve from bundle.front_matter_values.
≈ “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 Finalizer (per-file, phase G)
LLM-driven phase-G finalizer. For ONE source file, stitches the per-FA-section
drafts written by functional-analysis-writer
into a single, complete functional-analysis.md for exactly bundle.languages,
in declared order at bundle.output_paths, co-finalised in the same LLM call.
Never require or create an unrequested English edition or intermediate.
This is the per-file scope of the FA family. The per-section
functional-analysis-writer skill explicitly forbids authoring the final
stitched document; that scope lives here. The same agent
(functional-analysis-writer.agent.md) handles both scopes — only the bundle
input differs.
When to Use
- Every per-section FA draft for the file has been authored and passed
qa-reviewer(kind: "functional-analysis"). - The user asks to "build functional-analysis.md", "finalize the AFU", "stitch the FA sections", "produce the per-language AFU document for DEMO100".
Do not use this skill for:
- Per-FA-section drafts (
_fa-sections/<lang>/*.md) — owned byfunctional-analysis-writerper-section. - Phase C
index.md/complete.md— owned bysection-doc-finalizer. - File-level overview
.mmddiagrams — owned bydiagram-renderer. - Per-file QA review — owned by
qa-reviewer. - Portal aggregation across files — owned by phase N.
Output Contract
For file <basename-with-ext> and each language <lang>:
docs/<lang>/<basename-with-ext>/functional-analysis.mdThe document MUST:
- Open with the H1 banner from
profile.front_matter.title_pattern(or theheadersection spec) with placeholders substituted frombundle.front_matter_values. - Render the classification + metadata tables from
profile.front_matterwhenshow_classification/show_metadata_tableare true. - Concatenate every per-section draft from
bundle.section_drafts.<lang>in profile order (the order fromfa_profile_resolver.flatten_sections). - Replace missing optional sections with the section heading followed by a
single paragraph containing exactly
profile.section.optional_marker. - Renumber per-section
[^src-N]footnotes into ONE consolidated## Sourcesblock at the end of the document. Definitions are kept verbatim, ids re-sequenced starting at 1 in document order. - Append the footer from
profile.footerverbatim when present (V5.0.0+<!-- kpi-functional-analysis -->for `default - When multiple languages are requested, align heading structure, table row count, and consolidated footnote ids 1:1 across those languages only.
Procedure
- Resolve inputs. Required under
docs/_shared/<basename-with-ext>/:_fa-bundles/_finalize.bundle.json(+.mdview)._fa-sections/<lang>/<section_id>.mdfor every required section inprofile.sections× every requested language. On any miss: exit4and report exactly which drafts are missing.
- Tombstone check. If
_fa-bundles/_skipped.jsonexists, the file is opted out of phase G entirely. Exit0without writing. - Stale-input check. Re-hash
_fa-bundles/_finalize.bundle.json::manifest_shaagainst the on-disk source sha. Mismatch → exit5and prompt the user to re-run phase A. - Assemble the bundle. Invoke scripts/assemble-inputs.py.
This deterministic packager:
- resolves the FA profile via
scripts/lib/fa_profile_resolver.py, - loads every per-section draft and embeds its body verbatim under
section_drafts.<lang>.<section_id>, - computes
front_matter_valuesfromfacts.json(program id, JCL job name, CICS transaction id, …), - emits
_finalize.bundle.json+.md.
- resolves the FA profile via
- Author. The
functional-analysis-writeragent reads the bundle and writesfunctional-analysis.mdper language at the exact path declared underbundle.output_paths. - Validate mechanically. Invoke
qa-reviewer--kind functional-analysisper language.
Bundle Schema
{
"bundle_version": "1.0",
"scope": "per-file",
"source_path": "repos/sample1/COBOL/DEMO100.CBL",
"source_kind": "cobol",
"manifest_sha": "<64-hex>",
"profile_name": "default
"profile_path": "config/templates/docs/functional-analysis/default
"profile": { /* full profile.yaml */ },
"profile_sha": "<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",
"SOURCE_PATH": "repos/sample1/COBOL/DEMO100.CBL", "SHA256": "<64-hex>",
"ENCODING": "auto", "LINE_COUNT": 1908, "GENERATED_AT": "2026-05-28T00:00:00Z"
},
"languages": ["en", "it"],
"ordered_sections": [
{ "id": "scopo-ambito", "number": "4", "title": "Scope & boundaries",
"required": true, "optional_marker": "Paragrafo non necessario" }
/* in profile.sections order, including subsections */
],
"section_drafts": {
"en": {
"scopo-ambito": "## 4. Scope & boundaries\n\n…draft body with [^src-1]…\n\n[^src-1]: …"
},
"it": {
"scopo-ambito": "## 4. Scopo e ambito\n\n…corpo della bozza con [^src-1]…\n\n[^src-1]: …"
}
},
"missing_sections": {
"en": ["interfacce-utente", "ui-standard"],
"it": ["interfacce-utente", "ui-standard"]
},
"output_paths": {
"en": "docs/en/DEMO100.CBL/functional-analysis.md",
"it": "docs/it/DEMO100.CBL/functional-analysis.md"
}
}Determinism Rules
- The bundle packager is fully deterministic: re-running on unchanged inputs emits a byte-identical bundle (per-section drafts hashed individually).
- The LLM finalisation step is NOT deterministic — that is expected. What IS
deterministic is the shape: same section order, same consolidated
footnote numbering, same
optional_markerfor missing sections, same front-matter substitutions. - Forbidden re-derivations from the finalisation path:
- Never re-derive output paths — use
bundle.output_pathsverbatim. - Never load
facts.json/profile.yaml/ per-section drafts directly at runtime — every byte lives in the bundle.
- Never re-derive output paths — use
Resources
- scripts/assemble-inputs.py — deterministic per-file finalizer bundle packager.
functional-analysis-writer— sibling per-section authoring skill.scripts/lib/fa_profile_resolver.py— shared profile resolution helper.
Pipeline Wiring
config/pipeline-dag.yaml phase G lists functional-analysis-writer at per-file
scope as the finalizer step, immediately after every per-FA-section authoring
call has completed and been QA'd. The qa-reviewer per-file step
(kind: "functional-analysis") closes phase G per language.
Common Pitfalls
- Out-of-order stitching. Section order MUST come from
bundle.ordered_sections, never from filesystem enumeration of_fa-sections/<lang>/*.md. - Footnote collision. Each per-section draft restarts
[^src-N]from 1; the finalizer MUST re-number across the consolidated document. Failing this, the qa-reviewer flags duplicate footnote ids. - Optional-section drift. A required section missing from
_fa-sections/is anerror— never silently fill it withoptional_marker. Only sections whoseprofile.section.requiredis false may be marker-only. - Front-matter fabrication. Every
{{PLACEHOLDER}}MUST resolve frombundle.front_matter_values. Unknown placeholders are left literal so the qa-reviewer can flag them.
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.

