legacy-spec-writer

name

legacy-spec-writer

description

Produce evidence-backed `spec.yaml` and `spec.md` artifacts from approved module + flow + program analyses plus an approved legacy-system BRD Package after stakeholders explicitly promote a capability beyond legacy discovery. One spec per business capability (CAP-*). Layer 2 (platform-agnostic) skill — sits after BRD review and any separate post-BRD comparison / gap-analysis decision, producing the contract that downstream SDLC can consume. Implements `schemas/spec.schema.yaml`.

Legacy Spec Writer

Skill Card

Field	Notes
Problem solved	Promotes approved discovery into an evidence-backed, platform-agnostic capability spec for downstream SDLC.
Input	Approved BRD Package, module/flow/program analyses, approved decisions, traceability, and explicit stakeholder promotion.
Output	spec.yaml, spec.md, and traceability.md for one CAP-* capability.
Core prompt strategy	Encode only approved behavior, preserve evidence links, separate rules from decisions, and conform to schemas/spec.schema.yaml.
Upstream skill	legacy-brd-writer after BRD review and post-BRD disposition.
Downstream consumer	Golden-master planning, traceability packaging, SDD handoff, and forward SDLC agents.
Validation standard	Schema validation passes, capability scope is singular, evidence/SME approval is explicit, and target design is not invented.
Known risk	Letting speculative BRD gaps or target architecture preferences enter the spec as approved requirements.
Practical example	Convert an approved order-release BRD into CAP-ORDER-RELEASE spec artifacts with trace links to flows and SME decisions.

Purpose

Synthesize one business capability spec from approved upstream analyses, an approved legacy BRD Package, and an explicit stakeholder decision to promote the capability beyond legacy discovery. The output is a structured, evidence-backed spec.yaml (plus a human-readable spec.md) that the forward SDLC can consume when delivery work is actually intended.

This skill is the first platform-agnostic layer. It does not look at IBM i source code directly — only at the analyses produced by legacy-ibmi-module-analyzer, legacy-ibmi-flow-analyzer, and legacy-ibmi-program-analyzer, plus the SME-reviewed BRD Package produced by legacy-brd-writer. It must not treat every approved BRD as an automatic implementation mandate.

One capability = one spec.yaml. A module typically produces multiple specs (one per capability identified in the module overview's "Capability Seeds" section).

Inputs

Accept:

• Approved module analysis (04_modules/<MODULE-SLUG>/ with all four views at approved or approved_with_non_blocking_tbd)
  • Prefer module-analyzer v0.2.2 or later outputs that include Module Program-Chain Readiness with edge-resolution coverage, Module Persistence & Critical Field Summary with source identifier + business meaning fields, routine-local evidence carry-forward, Module Exception & Recovery Summary, View 3 Replay Coverage Summary, and View 4 Module Persistence Matrix / Critical Field Lineage / Exception-Aware Data Risks.
• All approved flow analyses referenced by that module
  • Prefer flow-analyzer v0.2.2 or later outputs that include Flow Replay Path, edge Evidence Source / Resolution, Cross-Program Field Lineage, Flow Persistence Matrix with File I/O Purpose, and Exception Propagation Chain consuming routine-local exception closure where available.
• All approved program analyses referenced by those flows
  • Prefer program-analyzer v0.2.7 or later outputs that include Call Evidence, Routine Logic Details with conditioned calculation blocks, routine-local field lineage / carriers and routine-local exception closure, Logic Decomposition Ledger, Key File & Field Logic with source identifiers plus business meanings, File I/O Purpose, Field Mutation Matrix, dynamic-call resolution status, front-loaded Calculation Logic, Validation Logic, Exception Handling, Message Inventory, and Exception Closure Ledger.
• All approved inventory (01_inventory/inventory.yaml)
• Capability seed — one specific CAP-* from the module overview; the SME has confirmed this is a distinct capability worth specifying
• Approved legacy BRD Package (required before standard spec-writing) — 05_brds/<CAPABILITY-SLUG>/brd.md, brd-review.md, validation-scenarios.md, traceability.md, and approval / review decision evidence. Use it as reviewed business context for SME-required areas such as channels, user touchpoints, system interfaces, process flow, validation rules, error handling, dependencies, and source-document gaps; do not treat it as a substitute for approved module / flow / program evidence.
• Promotion / disposition decision (required) — named stakeholder decision outside the BRD Package showing that this capability should move beyond legacy discovery into spec-writing. When old-vs-new comparison has already happened, valid triggers include approved gap-analysis intake, risk-owner approval to proceed, or explicit product/SME approval to specify. No-gap, Gap1, and follow-new-system decisions normally do not enter this skill because the new system remains the source of truth.
• Target platform hint (optional) — Java/Spring, Java/Quarkus, serverless, etc. Used to inform target_platform and modernization_decisions
• SME availability — capability owner who will approve business_rules, acceptance_criteria, and resolve open TBD-*
• Conditionally required from inventory triggers:
  • When inventory.yaml.sme_review.downstream_required.data_model_analyzer.required: true → approved 04_modules/<MODULE-SLUG>/data-model/dictionary.md. spec.yaml.data_model.entities MUST be populated by reading this dictionary verbatim (entities, fields, types, relationships). Do NOT re-derive entities by recomputing across program-analysis.md File I/O rows — cross-program invariants get lost that way.
  • When inventory.yaml.sme_review.downstream_required.screen_report_analyzer.required: true → the approved screen-report-analysis.md artifacts contribute to the UI-driven behaviors and business_rules of the spec (surfaced via the module overview / BRD crosswalk, but spec-writer should cite them as evidence_ids in the spec's UI-facing rules).

Trigger rules: skills/legacy-ibmi-inventory/references/downstream-triggers.md.

Stop and require clarification if:

• Module status is not approved or approved_with_non_blocking_tbd → route to legacy-ibmi-module-analyzer
• The chosen capability seed has unresolved blocking TBDs in the module analysis
• No approved BRD Package exists for the chosen capability → route to legacy-brd-writer / legacy-sme-review-facilitator, unless the requester explicitly records a technical-spec-only bypass with approver and risk acceptance
• Approved BRD exists but the only post-BRD decision is No-gap, Gap1, follow new system, or pending decision → do not write a spec; route to the separate migration disposition, risk assessment, or gap-analysis process as appropriate
• No SME owns the capability (without SME, business_rules cannot move beyond draft)
• Target platform is completely unspecified and decisions cannot be framed → request platform hint

Output Contract

Produce a directory 05_specs/<CAPABILITY-SLUG>/:

05_specs/<CAPABILITY-SLUG>/
├── spec.yaml              ← canonical machine-readable contract (schemas/spec.schema.yaml)
├── spec.md                ← human-readable rendering of the same content
├── spec-review.md         ← SME review checklist and sign-off page
└── traceability.md        ← cross-reference report (BR→EV→AC→TC)

Use:

• ../../schemas/spec.schema.yaml as the authoritative format
• templates/spec.yaml, templates/spec.md, templates/spec-review.md, templates/traceability.md as starting structure
• references/synthesis-rules.md for how to derive each field
• references/rule-extraction-protocol.md for promoting capability seeds to approved BR-* (the most delicate step)
• references/anti-hallucination.md for what the writer must refuse to invent

Follow:

• ../../docs/id-conventions.md for stable IDs (CAP-*, BR-*, BEH-*, DEC-*, IN-*, OUT-*, EX-*, STEP-*, AC-*, TC-*, TBD-*)
• ../../docs/evidence-and-knowledge-taxonomy.md for the knowledge-type / evidence-strength model
• ../../docs/forward-sdlc-contract.md for the later handoff contract to downstream SDLC
• ../../docs/input-readiness-rubric.md for input readiness scoring

Examples:

• examples/spec-positive/ — one approved capability spec (Credit Limit Enforcement, derived from CARD-AUTH module)

Step Contract

This skill is one step in the Legacy Spec Factory reverse chain. It conforms to the canonical Step Contract shape — see ../legacy-step-contract/SKILL.md and ../legacy-step-contract/references/step-contract.md for the full field-level rules. The summary below is normative for this skill.

Input

• Required: approved 04_modules/<MODULE-SLUG>/ (module-overview.md, 03-program-flow.md, 04-data-flow.md, and module-review-checklist.md at approved or approved_with_non_blocking_tbd); approved flow-<FLOW-SLUG>.md for every flow the module references; approved program-analysis-<OBJ-ID>.md for every program in those flows; approved 01_inventory/inventory.yaml; one CAP-* capability seed from the module overview; approved BRD Package for that capability; named capability-owner SME; post-BRD promotion / disposition decision showing that this is not merely a legacy-discovery item.
• Optional: target platform hint (Java/Spring, Java/Quarkus, serverless, etc.) — informs target_platform and modernization_decisions.
• Input readiness scoring:
  • 0-5 blocked: approved module missing, capability seed unresolved, blocking TBDs remain, no capability-owner SME, required triggered artifact missing, approved BRD Package missing, post-BRD promotion / disposition decision missing, or evidence authorization unresolved.
  • 6 minimum_pass: approved module/upstream analyses, one SME-confirmed CAP-*, approved BRD Package, named SME owner, explicit post-BRD promotion / disposition decision, and required triggered data/screen/report outputs are present.
  • 7-8 usable: target platform hint, BAU notes, and BRD review decisions / coverage notes are supplied.
  • 9-10 strong: acceptance examples, negative cases, runtime observations, platform constraints, and modernization decision context are also supplied.
  • Missing target platform hint does not block observed-behavior/spec drafting unless modernization decisions must be framed in the same run.
• Readiness checks: Inventory Completeness Gate and Evidence Approval Gate passing; no sensitivity: unknown evidence in scope; SME owner available to approve BR-* and AC-*.
• Stop conditions: module status below approved_with_non_blocking_tbd (route back to legacy-ibmi-module-analyzer); selected CAP-* has unresolved blocking TBDs in the module; approved BRD Package is missing or not approved; no SME owns the capability; post-BRD promotion / disposition decision is missing or says to follow the new system; target platform completely unspecified when decisions are required.

Execution

• Procedure: see the Workflow section below (11 ordered steps).
• Allowed inference: lifting BEH-* from flow replay paths, branch points, persistence outcomes, and exception chains; aggregating evidence from upstream artifacts; mapping legacy data objects and critical fields to target entities; sketching modernization decisions whose rationale ties back to BR-*, BEH-*, or platform constraints.
• Forbidden assumptions: inventing business rules beyond upstream seeds + SME confirmation; promoting a "weak" BR-* to approved without explicit SME approval; generating AC-* for unapproved BR-*; promoting No-gap, Gap1, or follow-new-system post-BRD decisions into requirements; filling data-model field meanings from field names alone; reading raw IBM i source (this skill consumes upstream analyses only); specifying target architecture without rationale.
• TBD handling: unconfirmed business rule → BR-* with review_status: needs_sme_review (no AC-* generated); platform unspecified → DEC-* in draft with rationale noting uncertainty; unclear field semantics → entity field carries a TBD on semantics.

Output

• Canonical directory: 05_specs/<CAPABILITY-SLUG>/ containing spec.yaml, spec.md, spec-review.md, traceability.md.
• Required sections/fields: spec_id, capability.{id,name,slug,owner}, scope, evidence[], behaviors[] (BEH-*), business_rules[] (BR-*), modernization_decisions[] (DEC-*), data_model, process_flow.steps[] (STEP-*), inputs[] (IN-*), outputs[] (OUT-*), exceptions[] (EX-*), acceptance_criteria[] (AC-*), optional test_cases[] (TC-*), tbds[] (TBD-*).
• Required IDs: mints final BR-*, DEC-*, IN-*, OUT-*, STEP-*, AC-*, TC-*, TBD-*. Reuses CAP-*, OBJ-*, EV-*, BEH-* from upstream. spec.yaml must validate against ../../schemas/spec.schema.yaml.
• Spec status: status: draft → in_review → approved (capability-owner SME sign-off). Forward Handoff Gate consumes approved; rejected or retired halt forward SDLC.

Validation

• Mechanical: spec.yaml validates against ../../schemas/spec.schema.yaml; every BEH-*, BR-*, DEC-* links to ≥1 EV-*; every BR-* links to ≥1 BEH-*; every approved BR-* has ≥1 AC-*; every AC-* carries validates: [BR-*]; every TBD has a category and resolver; no sensitivity: unknown in evidence[].
• AI semantic: each BR-* is supported by its linked BEH-* and EV-* content (not just ID reference); modernization_decisions are explicitly separated from observed_behavior; no invented Java target details; data-model field semantics never come from field names alone; tier 3/4 backing (comments, wikis, prior specs) does not raise a BR-* past needs_sme_review.
• SME / human approval: capability-owner SME approves every BR-* reaching approved, every AC-*, every DEC-* rationale, the data model, and the transition in_review → approved. Modernization decisions also need architecture / product authority where target platform is concerned.
• Blocking conditions: any business-critical BR-* unapproved; any approved BR-* missing AC-*; any AC-* missing validates: [BR-*]; any evidence[] row with sensitivity: unknown; any blocking TBD; missing post-BRD promotion / disposition decision; spec arrives at downstream SDLC with silent gaps.

Emit a Step Validation Report (see ../legacy-step-contract/templates/step-validation-report.md) with status pass, pass_with_warnings, or blocked when reporting upward to the orchestrator. The Forward Handoff Gate (../../docs/forward-sdlc-contract.md) is the next gate after pass.

Workflow

1. Confirm Capability Scope

   • Take one CAP-* from the module overview's Capability Seeds
   • Validate with SME: is this a distinct capability worth its own spec?
   • Confirm the approved BRD is not merely a legacy discovery baseline: a separate post-BRD decision promotes the capability to spec-writing via gap analysis, risk-owner approval, or explicit product/SME decision
   • If the post-BRD decision is No-gap, Gap1, follow-new-system, or pending, stop and route back to migration disposition / risk assessment / gap analysis
   • Assign spec_id and confirm capability.{id,name,slug,owner}
   • Define scope.in_scope and scope.out_of_scope from SME

2. Collect Evidence Bundle

   • Gather every EV-* referenced by any flow / program analysis that touches this capability
   • Populate evidence[] array — every EV-* becomes one row
   • Confirm sensitivity is set; if any sensitivity: unknown exists, stop and request evidence authorization review

3. Lift Observed Behaviors (BEH-*)

   • From flow analyses' Flow Replay Path, control flow, branch points, edge Evidence Source / Resolution, Flow Persistence Matrix, and Exception Propagation Chain (factual statements about what the legacy system does)
   • Cross-check with program analyses' Logic Decomposition Ledger, Routine Logic Details, routine-local field lineage / carriers, routine-local exception closure, Key File & Field Logic, File I/O Purpose, Field Mutation Matrix, Validation Logic, and Exception Closure Ledger where the behavior depends on program-level detail
   • Each BEH must trace to ≥1 EV-*
   • These are factual — what the system does, not why

4. Lift Business Rules (BR-*)

   • From module analysis's BR-* seeds in module-overview.md / BRD crosswalk
     • cross-checked against flow analyses' SEED-* + SME confirmation
   • This is the most delicate step — see references/rule-extraction-protocol.md
   • Each BR must:
     • Be confirmed by SME (or explicitly marked needs_sme_review)
     • Reference ≥1 BEH it abstracts
     • Reference ≥1 EV that supports it
   • A BR with no SME confirmation cannot be approved — only draft

5. Record Modernization Decisions (DEC-*)

   • For each significant choice the target system must make (e.g., "store transaction log in append-only table vs event store"), record a DEC-*
   • Decisions must have a rationale tied to BR or BEH or to target_platform constraints
   • Decisions are forward-looking — they tell downstream SDLC how to implement, not what the legacy does

6. Define Data Model

   • For each target entity, map to legacy OBJ-* (the originating PF/LF)
   • For each entity field, map to legacy field name + target type
   • Use the module's View 4 (Data Flow), Module Persistence Matrix, and Critical Field Lineage Across Module as primary input
   • Capture lifecycle hints (immutable / mutable / append-only)
   • Preserve critical legacy field lineage and persistence constraints as evidence-backed notes or TBD-*; do not reduce field-level behavior to a file-level dependency
   • When program-analyzer v0.2.5 evidence is available, preserve conditioned calculation blocks and routine-local carrier/lineage rows that explain how a field was calculated, moved through work variables, handed off, or persisted.

7. Define Process Flow, Inputs, Outputs, Exceptions

   • process_flow.steps[] from the relevant flow's business-visible phases and major outcomes, using Flow Replay Path and the Transaction Call Map as evidence
   • Use the approved BRD Package's section 6 as the business-readable process-flow framing and cross-check it against module / flow evidence
   • inputs[] from flow analysis Trigger Context, UI surfaces' input fields, and BRD sections 3-5 (channels, user touchpoints, system interfaces)
   • outputs[] from flow analysis exit nodes, Flow Persistence Matrix rows (including Purpose), Cross-Program Data Flow carriers with external handoff, creates, or updates state impact, and BRD sections 4-5 where a business-visible response, report, message, or interface result is SME-reviewed
   • exceptions[] from BRD section 8, module Exception & Recovery Summary / Exception-Aware Data Risks, flow Exception Propagation Chain, and program Validation Logic / Exception Closure Ledger / routine-local exception closure
   • open_questions[] carries any BRD section 1-9 coverage gaps or accepted-with-TBD review decisions that remain unresolved
   • Do not copy program nodes or call-chain order directly into process_flow.steps[]; each step should describe the capability behavior the target system must preserve or implement

8. Write Acceptance Criteria (AC-*)

   • For each approved BR, produce at least one AC
   • Prefer Gherkin (given/when/then) when behavior is procedural
   • Use checklist when behavior is declarative
   • validates: [BR-*] is mandatory
   • SME must approve each AC

9. Optional: Sketch Test Cases (TC-*)

   • Only if the spec is moving toward field pilot
   • Golden-master and equivalence tests defer to future skills; the spec writer may sketch identifiers and intent only

10. Build Traceability

    • Generate traceability.md with the full chain: BR-* → EV-* → AC-* (→ TC-* if defined)
    • Verify every approved BR has at least one supporting EV and one AC
    • Verify every AC traces to an approved BR

11. Prepare for SME Approval

    • Mark status: in_review
    • Capture open TBD-* with blocking status
    • Generate spec-review.md checklist
    • The capability owner SME approves; the spec is then status: approved

Workflow State Write-Back

At the end of a spec-writing run, update <project-root>/workflow-state.yaml per docs/workflow-state-contract.md. Template: skills/legacy-modernization-orchestrator/references/state-writeback-snippet.md.

Stage this skill produces (mirrors spec.yaml.status):

• 8c Spec Approved when spec.yaml.status: approved AND every rule has acceptance_criteria AND no rule with knowledge_type: inferred_business_rule is at review_status: needs_sme_review AND no blocking TBD-* remains
• 8b Spec In Review when spec.yaml.status: in_review
• 8a Spec Drafted when spec.yaml.status: draft

Last artifact path pattern: 05_specs/<CAP-*>/spec.yaml (sibling: spec.md, traceability.md, optional review-report.md)

Writes per run:

1. Overwrite capabilities[<CAP-* from current_focus>] with stage id (matching spec.yaml.status), spec.yaml path, last_skill: legacy-spec-writer, and blocking IDs (tbds, sme_pending for any inferred_business_rule not yet confirmed, gates: ["evidence_approval"] if any rule still has unlinked evidence).
2. Append one history[] entry with note summarizing the spec event (e.g. "draft saved", "promoted to in_review", "SME approved").
3. Overwrite project.last_updated_at / project.last_updated_by.

Never touch current_focus, other capabilities' entries, or past history[] rows. The 8c → 8b transition (e.g. SME later rescinds approval) is a rollback — surface to the orchestrator and request the Rollback Protocol rather than silently lowering stage_id.

Anti-Hallucination Rules

This is the layer where business rules become formal — the temptation to "smooth out" gaps is highest. The discipline is the strictest.

Code is ground truth. See ../../docs/code-as-ground-truth.md. A BR can only be approved when it is grounded in:

• Tier 1 (currently-deployed source code) — for what the system does, or
• Tier 2 (named, date-stamped SME confirmation) — for why the system does it / what business policy applies

Tier 3 (comments, flow headers, prior specs) and tier 4 (wikis, vendor docs) are hypotheses, never evidence. If a candidate BR has only tier 3/4 backing, it stays in needs_sme_review. The rule-extraction protocol (references/rule-extraction-protocol.md) enforces this through the A/B/C/D classification.

Do NOT:

• Invent business rules beyond what is suggested by upstream BR seeds and confirmed by SME
• Promote a "weak" BR to approved without explicit SME approval
• Generate ACs for unapproved BRs — every AC must validate an approved BR
• Include in the spec any fact that doesn't trace to an EV-* in evidence[]
• Promote No-gap, Gap1, or follow-new-system post-BRD decisions into requirements; those stay with the new system as source of truth
• Specify target architecture details that have no rationale tied to BRs, BEHs, or platform constraints
• Fill data-model field meanings from field names alone (e.g., a field called STATUS does not imply the spec should say "status is one of ACTIVE, INACTIVE, CLOSED" without evidence)
• Pretend ambiguity is resolved by picking one interpretation when SME hasn't confirmed → mark as TBD

Instead:

• If a BR seed seems important but SME hasn't confirmed → BR with review_status: needs_sme_review, do not generate AC for it
• If target_platform is hinted but not committed → DEC entries are draft; rationale acknowledges uncertainty
• If a field's meaning is unclear → entity field carries a TBD on semantics; type is best-effort with needs_sme_review evidence

The contract with downstream SDLC:

• Every approved BR has ≥1 AC → testable
• Every approved AC has explicit validates: [BR] → traceable
• Every approved DEC has explicit rationale → reviewable
• Every TBD is explicit → no silent gaps

If a spec arrives downstream with silent gaps or without an explicit post-BRD promotion decision, the modernization will encode the gaps as defects. The whole skill family exists to prevent this.

SME Review Questions

The capability owner SME must validate:

• Capability name, slug, scope reflect business reality
• All BR-* are accurate; no invented rules
• All BEH-* match observed legacy behavior
• All DEC-* rationale make sense to business + tech
• Data model fields map correctly to legacy
• Process flow matches actual legacy sequence
• Inputs / Outputs / Exceptions are complete
• Acceptance criteria are testable and meaningful
• Open TBDs are tracked with named owners
• Post-BRD promotion / disposition decision is explicit
• No silent gap — spec can be implemented without re-interrogating SME

Runtime Portability

Canonical: skills/legacy-spec-writer/SKILL.md

Synced to all four runtime adapters.

Version History

• v0.1.5 (2026-06-02): Aligned spec synthesis inputs with analyzer v0.2.1. Observed behaviors, outputs, data model fields, and exceptions now preserve edge Evidence Source / Resolution, source identifier + business meaning fields, File I/O Purpose, Validation Logic, and exception-chain evidence from module / flow / program analysis before producing downstream spec content.

• v0.1.6 (2026-06-02): Aligned spec synthesis inputs with program-analyzer v0.2.5 routine-local evidence. Observed behaviors, data model fields, outputs, and exceptions now preserve Routine Logic Details, conditioned calculation blocks, routine-local carrier/lineage rows, and routine-local exception closure when those details explain field calculations, handoffs, persistence, skipped work, rollback, or visible error outcomes.

• v0.1.4 (2026-06-01): Aligned spec synthesis inputs with analyzer v0.2.0. Observed behaviors, outputs, data model fields, and exceptions now prefer replay, field-lineage, persistence, and exception-chain evidence from module / flow / program analysis before producing downstream spec content.

• v0.1.3 (2026-05-30): Added migration-discovery promotion gate. Approved BRD no longer automatically implies spec-writing; No-gap, Gap1, and follow-new-system outcomes from the separate post-BRD comparison process remain governed by the new system, while promoted legacy behaviors require explicit risk/gap-analysis/product decision before spec.

• v0.1.2 (2026-05-29): Enforced the BRD-first review gate. Standard spec writing now requires an approved BRD Package for the selected capability; direct module-to-spec generation is only an explicit technical-spec-only bypass with recorded risk acceptance.

• v0.1.1 (2026-05-28): Added approved BRD Package consumption rules. Spec synthesis may use SME-reviewed BRD sections 3-6, 8, and 9 for inputs/outputs/process/exceptions/open questions, while blocked or evidence-seeking BRD coverage prevents spec approval.

• v0.1.0 (2026-05-14): Initial release

  • 11-step workflow producing spec.yaml + spec.md + spec-review.md + traceability.md
  • Strict anti-hallucination at the rule-promotion step
  • Forward-handoff gate with build-agent-skill
  • Example: Credit Limit Enforcement capability from CARD-AUTH module