requirements-writer
Skill1 starsChanged 55 days agoMITView on GitHub
Author phase-F technical requirements for ONE mainframe or IBM i (AS400) COBOL source against the configured requirements profile. Reads one prepared bundle and writes per-language section drafts or final requirements.md. USE FOR: COBOL or ILE COBOL requirements, IBM i requirements, REQ/NFR blocks, phase F section authoring and finalization. DO NOT USE FOR: functional analysis, 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
- functional-analysis-writerSkill
- group-doc-finalizerSkill
- qa-reviewerSkill
- requirements-finalizerSkill
- requirements-group-finalizerSkill
- requirements-group-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 requirements from IBM i ILE, library-list, activation-group, commitment-control, and DB2 for …
- Distinctive: line 44
Do not use this skill for:
- Very specific: line 111
Start with the H1 banner built from profile.front_matter.title_pattern (or the header section spec) with placeholders substituted from …
- Very specific: line 133
Tombstone check: If docs/_shared/<file>/_req-bundles/_skipped.json exists (copybook / BMS), the file is opted out of phase F.
- Distinctive: line 183
MUST emit a byte-identical bundle.
- Very specific: line 185
Never re-derive output paths — use bundle.output_paths verbatim.
- Very specific: line 186
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 188
Never invent table rows, citations, requirements, or diagram nodes that have no anchor in facts_slice / chunk_excerpt / diagrams.
- Very specific: line 212
Requirement-id fabrication: Every REQ-NNN / NFR-NNN MUST be sourced from facts_slice.business_rules (or the equivalent NFR slice).
- Very specific: line 215
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 217
Table fabrication: Every row MUST cite a fact / line range.
- Very specific: line 219
Co-authoring drift: When multiple languages are requested, drafts MUST share heading count, requirement ids, table row count, and [^src-N] …
≈ “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
Requirements Writer (per-section + per-file finalizer, phase F)
Use bundle source_platform to distinguish z/OS requirements from IBM i ILE,
library-list, activation-group, commitment-control, and DB2 for i requirements.
LLM-driven phase-F authoring skill. For ONE source file, produces a complete
the organization's technical-requirements document (requirements.md) per
requested language. The skill mirrors functional-analysis-writer
1:1 in shape and contract; only the profile family and output filename differ.
Status: implemented. The skill metadata, output contract, bundle schema and determinism rules are pinned, and the requirements-specific packagers under scripts/ (
stage-bundles.py,assemble-inputs.py) plus the sharedscripts/lib/req_profile_resolver.pyare implemented.
| Scope | Reads | Writes |
per-section (LLM) | docs/_shared/<file>/_req-bundles/<section_id>.bundle.md | docs/_shared/<file>/_req-sections/<lang>/<section_id>.md per lang |
per-file (LLM) | docs/_shared/<file>/_req-bundles/_finalize.bundle.md + drafts | docs/<lang>/<file>/requirements.md per language |
Bundles are produced deterministically by scripts/stage-bundles.py
(per-section) and requirements-finalizer/scripts/assemble-inputs.py
(per-file). The LLM call that fills the template is invoked by the
requirements-writer agent. Mechanical compliance is verified by
qa-reviewer (kind: "requirements") immediately
after each authoring call.
When to Use
- The user asks to "write the technical requirements", "produce the ATE document", "draft REQ-007", "co-author EN + IT requirements for DEMO100", "regenerate requirements.md".
- A per-section requirements bundle exists at
docs/_shared/<file>/_req-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 G functional-analysis (
functional-analysis-writer), - phase C per-section docs (
section-doc-writer), - chunking (
cobol-chunking), - facts extraction (
cobol-facts-extraction), - QA review of the produced requirements (
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>/_req-sections/<lang>/<section_id>.mdThis is an INTERMEDIATE artifact — never user-facing. The finalizer concatenates
these per-language drafts into the final requirements.md.
The draft MUST:
- Begin with the section's H2 heading line built from
profile.section.number(when present) andprofile.section.title(e.g.## Functional requirements). Subsections use H3, with one H3 per requirement (### REQ-NNN — <title>) whenprofile.section.per_requirement_subsectionis true. - 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. - Respect
profile.section.min_paragraphs,min_count, and anymin_sentences/min_wordsthresholds declared on the section. - For requirement sub-sections (REQ-NNN / NFR-NNN), render the fields declared
in the profile (
Statement,Rationale,Source citations,Dependencies,Acceptance criteria,Confidence). After the per-requirement narrative, emit a roll-up table for traceability whenrender_mode: narrative-then-table. - Populate every 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. - 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 ofrequirements.md. - Identifier styling: COBOL/JCL identifiers MUST match
profile.identifier_lock_regexand be wrapped in backticks. Requirement ids followprofile.functional_id_prefix/profile.non_functional_id_prefixwithprofile.id_padding(e.g.REQ-001,NFR-007). - 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, requirement ids).
Per-file finalizer scope
For each language <lang>:
docs/<lang>/<file>/requirements.mdThe document MUST:
- Start with the H1 banner built 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 in profile order. 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. - Append the footer block from
profile.footerverbatim when present.
Procedure
- Resolve bundle input. Locate
docs/_shared/<file>/_req-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: exit4. - Validate bundle schema. Required
## Metadatakeys per-section:bundle_version,source_path,profile_name,section.id,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>/_req-bundles/_skipped.jsonexists (copybook / BMS), the file is opted out of phase F. 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 requirementsimmediately. Fail-fast: do not start the next section while findings remain. - Report. Print one summary line per language:
OK: wrote docs/_shared/<file>/_req-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": "ate-org-applicazione",
"profile_path": "config/templates/docs/requirements/ate-org-applicazione/profile.yaml",
"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/requirements/ate-org-applicazione/template.md",
"template_snippet": "…the matching `## N. Title` block from template.<lang>.md…",
"template_paths_per_language": {
"en": "config/templates/docs/requirements/ate-org-applicazione/template.md",
"it": "config/templates/docs/requirements/ate-org-applicazione/template.it.md"
},
"template_sha": "<64-hex>",
"diagrams": [ /* see functional-analysis-writer SKILL */ ],
"front_matter_values": { /* see functional-analysis-writer SKILL */ },
"languages": ["en", "it"],
"output_paths": {
"en": "docs/_shared/DEMO100.CBL/_req-sections/en/functional-requirements.md",
"it": "docs/_shared/DEMO100.CBL/_req-sections/it/functional-requirements.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, requirements, or diagram nodes that
have no anchor in
facts_slice/chunk_excerpt/diagrams.
- Never re-derive output paths — use
- Drafts for all requested languages are co-authored in the SAME LLM call.
Resources
- scripts/assemble-inputs.py — deterministic per-section bundle packager.
- scripts/stage-bundles.py — bulk per-section bundle runner for ONE source file.
- scripts/req_stage_batch.ps1 — PowerShell batch wrapper.
requirements-finalizer— sibling skill that produces_finalize.bundle.json/.mdand (after authoring) the per-languagerequirements.md.scripts/lib/req_profile_resolver.py— shared profile auto-detection (planned; mirror offa_profile_resolver.py).
Pipeline Wiring
config/pipeline-dag.yaml phase F lists requirements-writer twice: first at
per-section scope, then at per-file scope (finalizer). Each call is followed
by a qa-reviewer step with kind: "requirements". The phase depends on
phase C so the writer can reuse bundle.languages[0]'s complete.md narrative when building
per-section excerpts. Phase G (functional-analysis) depends on phase F.
Common Pitfalls
- Missing bundle. Author requires the bundle. Never read
facts.json,complete.md, orprofile.yamldirectly at runtime. - Requirement-id fabrication. Every
REQ-NNN/NFR-NNNMUST be sourced fromfacts_slice.business_rules(or the equivalent NFR slice). The qa-reviewer flags fabricated ids. - Profile drift. If
profile.yamlis edited mid-flight, re-runstage-bundles.py --forceso the cached bundleprofile_shamatches. - Table fabrication. Every row MUST cite a fact / line range. Empty cells
use
_None._italic; the qa-reviewer flagsN/A,TBD,???aserror. - Co-authoring drift. When multiple languages are requested, drafts MUST share heading count, requirement
ids, table row count, and
[^src-N]ids.
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.

