agentleFS
MicrosoftKnown publishermicrosoft/cobol-docs-pipeline-sample/.github/skills/technical-analysis-writer/SKILL.md

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.

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
  1. Distinctive:

    Do not use this skill for:

    line 51
  2. Very specific:

    After the Markdown editions are authored, the phase driver dot-sources scripts/lib/Convert-MdToDocx.ps1 and converts each …

    line 153
  3. Very specific:

    If pandoc is not on PATH, the DOCX step is skipped with a warning and the Markdown editions remain the deliverable.

    line 159

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

ScopeReadsWrites
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 at docs/_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/:

SourceResolved profile
.cpy / copybook, .bms / BMS mapsetSKIP (tombstoned, no ATE)
.jcl / .prcate-org-interfaccia
.cbl / .cob with CICS/BMS usageate-org-applicazione
.cbl / .cob (batch)ate-org-interfaccia
otherwisedefault

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_sections block, in profile order, rewriting the embedded complete.md narrative into the template shape — never copying complete.md verbatim 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 the optional_marker verbatim.
  • Populate every declared table column from the embedded narrative. Empty cells use _None._ (markdown italic) — never N/A, TBD, or ???.
  • Cite via Pandoc footnote form [^src-N] and consolidate into ONE ## Sources block 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.yaml order 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

PhaseScopeRuns inDepends onDriver
Lper-fileper-file-loopEscripts/phases/phase-L-technical-analysis.ps1
Mper-groupworkspaceI, Lscripts/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 en

Per-group (phase M)

pwsh -File scripts/phases/phase-M-group-technical-analysis.ps1 `
     -Manifest config/grouping.yaml -Languages en

DOCX 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 requires docs/<lang>/_groups/<gid>/complete.md (phase I), where <lang> is bundle.languages[0]. English is not a prerequisite unless requested. The stager exits 4 and the dispatch records missing-bundle.
  • Copybook / BMS. The stager writes _skipped.json and no ATE is produced.
  • pandoc absent. DOCX step is skipped; Markdown is complete.
  • Empty grouping.yaml. Phase M is a no-op (exit 0).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.