technical-analysis-writer
Skill1 starsChanged 55 days agoMITView on GitHub
Author phase-L/M technical-analysis documents for mainframe or IBM i (AS400) sources and groups. LLM-driven, single-pass from the prepared finalize bundle, with deterministic DOCX export. USE FOR: IBM i or mainframe technical analysis, analisi tecnica, ATE, phase L per-file and phase M group finalization. DO NOT USE FOR: functional analysis, requirements, section docs, chunking, facts extraction, 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-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
- section-doc-writerSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 51
Do not use this skill for:
- Very specific: line 153
After the Markdown editions are authored, the phase driver dot-sources scripts/lib/Convert-MdToDocx.ps1 and converts each …
- Very specific: line 159
If pandoc is not on PATH, the DOCX step is skipped with a warning and the Markdown editions remain the deliverable.
≈ “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
Technical Analysis Writer (per-file phase L + per-group phase M)
LLM-driven authoring skill for the organization's ATE — Analisi Tecnica
deliverable. For ONE source file (phase L) or ONE group (phase M) it produces a
complete technical-analysis.md per requested language, then a deterministic
pandoc step renders a sibling technical-analysis.docx.
This is a single-pass finalizer: unlike the functional-analysis (phase F/G)
and requirements (phase F) families, there are no per-section drafts. The
consolidated narrative source is the already-authored complete.md, which the
LLM reorganizes and rewrites into the technical-analysis template structure.
complete.md is the only narrative input — the writer never reads
functional-analysis.md. The SISBA tracciato catalog needed for the
trk-gestiti section (§7 of the ate-org-interfaccia profile) is the
deterministic Record types (TRK) block that phase E appends to complete.md;
when that block is present the writer authors the per-TRK subsections from it
instead of stamping the not-applicable marker.
| Scope | Reads | Writes |
per-file (LLM) | docs/_shared/<file>/_ta-bundles/_finalize.bundle.md (embeds a requested language's docs/<lang>/<file>/complete.md) | docs/<lang>/<file>/technical-analysis.md per language |
per-group (LLM) | docs/_shared/_groups/<gid>/_ta-group-bundles/_finalize.bundle.md (embeds a requested language's docs/<lang>/_groups/<gid>/complete.md) | docs/<lang>/_groups/<gid>/technical-analysis.md per language |
Bundles are produced deterministically by
scripts/assemble-inputs.py (per-file) and
scripts/assemble-group-inputs.py
(per-group). The LLM call that fills the template is invoked by the
technical-analysis-writer agent. DOCX export is handled by the phase driver
via scripts/lib/Convert-MdToDocx.ps1
(pandoc, plain default styling).
For both scopes, the embedded source narrative comes from bundle.languages[0],
not from an implicit English edition. Author every requested output language
from that staged narrative without requiring additional language intermediates.
When to Use
- The user asks to "write the technical analysis", "produce the ATE document", "generate analisi tecnica for DEMO100", "co-author EN + IT ATE", "export the technical analysis to Word", "regenerate technical-analysis.md".
- A per-file finalize bundle exists at
docs/_shared/<file>/_ta-bundles/_finalize.bundle.md, or a per-group bundle atdocs/_shared/_groups/<gid>/_ta-group-bundles/_finalize.bundle.md.
Do not use this skill for:
- phase F functional analysis (
functional-analysis-writer), - phase F requirements (
requirements-writer), - phase C per-section docs (
section-doc-writer), - chunking (
cobol-chunking), - facts extraction (
cobol-facts-extraction), - QA review of the produced ATE (
qa-reviewer), - portal aggregation across files (phase N).
Profile resolution
The active profile is resolved deterministically by
scripts/lib/ta_profile_resolver.py
from config/templates/docs/technical-analysis/:
| Source | Resolved profile |
.cpy / copybook, .bms / BMS mapset | SKIP (tombstoned, no ATE) |
.jcl / .prc | ate-org-interfaccia |
.cbl / .cob with CICS/BMS usage | ate-org-applicazione |
.cbl / .cob (batch) | ate-org-interfaccia |
| otherwise | default |
Group rule (resolve_for_group): any BMS member → ate-org-applicazione;
any JCL/PRC member → ate-org-interfaccia; else → default. A workspace
override key technical_analysis_profile in pipeline.yaml takes precedence.
Output Contract
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/<lang>/<file>/technical-analysis.md # per-file (phase L)
docs/<lang>/_groups/<group_id>/technical-analysis.md # per-group (phase M)with a sibling technical-analysis.docx produced by the phase driver.
Each technical-analysis.md MUST:
- Begin with the YAML front-matter filled from the bundle's
front_matter_values. - Author every section declared under the bundle's
## Template/ordered_sectionsblock, in profile order, rewriting the embeddedcomplete.mdnarrative into the template shape — never copyingcomplete.mdverbatim and never inventing facts with no anchor in the narrative. - Honour
section.required/optional_marker: optional sections with insufficient evidence become the heading + a single paragraph containing theoptional_markerverbatim. - Populate every declared table column from the embedded narrative. Empty cells
use
_None._(markdown italic) — neverN/A,TBD, or???. - Cite via Pandoc footnote form
[^src-N]and consolidate into ONE## Sourcesblock at the bottom. Per-group docs cite per-file documents, not source lines. Inline[FILE:Lx-Ly]tags are forbidden. - Per-group: member order MUST match
grouping.yamlorder verbatim. - Style COBOL/JCL identifiers per
profile.identifier_lock_regex, wrapped in backticks. - Author exactly the requested languages in the SAME LLM call; when multiple
languages are requested, align structure 1:1 (heading count, table row count,
[^src-N]ids, front-matter keys).
Pipeline wiring
| Phase | Scope | Runs in | Depends on | Driver |
| L | per-file | per-file-loop | E | scripts/phases/phase-L-technical-analysis.ps1 |
| M | per-group | workspace | I, L | scripts/phases/phase-M-group-technical-analysis.ps1 |
Technical analysis requires the complete documentation narrative, not requirements
or functional analysis. YAML selection of output.generate.technical_analysis
includes A/B/C/D/E/I/L/M/N; H is added only when output.generate.docs is enabled.
Each phase runs three steps: stage (deterministic bundle packaging) → dispatch (Copilot CLI single-pass authoring) → docx (pandoc export).
Per-file (phase L)
# 1. stage the finalize bundle
pwsh -File .github/skills/technical-analysis-writer/scripts/ta_stage_batch.ps1 `
-Paths repos/sample1/COBOL/*.CBL -Languages en
# 2. dispatch the single-pass finalizer
pwsh -File scripts/dispatchers/run-docs-ta-finalize-batch.ps1 `
-Paths repos/sample1/COBOL/*.CBL -Languages en
# (3. DOCX export is run automatically by the phase driver)
pwsh -File scripts/phases/phase-L-technical-analysis.ps1 `
-Paths repos/sample1/COBOL/*.CBL -Languages enPer-group (phase M)
pwsh -File scripts/phases/phase-M-group-technical-analysis.ps1 `
-Manifest config/grouping.yaml -Languages enDOCX export
After the Markdown editions are authored, the phase driver dot-sources
scripts/lib/Convert-MdToDocx.ps1
and converts each technical-analysis.md to a sibling technical-analysis.docx
via pandoc --from markdown --to docx. No reference-doc is supplied, so pandoc
applies its built-in default Word styling. The conversion is idempotent and
skips files whose .docx is newer than the .md unless -Force is given.
If pandoc is not on PATH, the DOCX step is skipped with a warning and the
Markdown editions remain the deliverable.
Failure modes
- Missing prereq. Per-file requires the first requested language's
docs/<lang>/<file>/complete.md(phase E); per-group requiresdocs/<lang>/_groups/<gid>/complete.md(phase I), where<lang>isbundle.languages[0]. English is not a prerequisite unless requested. The stager exits 4 and the dispatch recordsmissing-bundle. - Copybook / BMS. The stager writes
_skipped.jsonand no ATE is produced. - pandoc absent. DOCX step is skipped; Markdown is complete.
- Empty grouping.yaml. Phase M is a no-op (exit 0).
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.

