Package, validate, and audit one capability's end-to-end traceability across the Legacy Spec Factory reverse chain — evidence manifest, inventory, program/flow/module analyses, optional BRD, approved `spec.yaml`/`spec.md`/`traceability.md`, and optional SDD handoff. Audit / packager / gate skill — does not mint business rules, behaviors, acceptance criteria, modernization decisions, evidence, test cases, or SDD handoffs, and does not promote review status. Emits a sealed traceability package or a strict blocked-findings report. Layer 2 (platform-agnostic).
Package, validate, and audit one capability's end-to-end traceability across the Legacy Spec Factory reverse chain — evidence manifest, inventory, program/flow/module analyses, optional BRD, approved `spec.yaml`/`spec.md`/`traceability.md`, and optional SDD handoff. Audit / packager / gate skill — does not mint business rules, behaviors, acceptance criteria, modernization decisions, evidence, test cases, or SDD handoffs, and does not promote review status. Emits a sealed traceability package or a strict blocked-findings report. Layer 2 (platform-agnostic).
Legacy Traceability Packager
Skill Card
Field
Notes
Problem solved
Seals or blocks one capability's end-to-end traceability across evidence, analyses, BRD, spec, and optional handoff.
Every CAP-*, OBJ-*, EV-*, rule, decision, and test/handoff reference resolves or is explicitly blocked.
Known risk
Creating a polished package that implies approval despite broken or missing trace links.
Practical example
Package CAP-ORDER-RELEASE traceability from evidence manifest through approved spec and SDD handoff, blocking missing EV-* links.
Purpose
Package one capability's end-to-end traceability into a sealed, audit-friendly bundle that answers four questions deterministically:
EV coverage — for every EV-*, which BEH-* / BR-* / DEC-* / STEP-* / AC-* / TC-* use it?
BR closure — for every approved BR-*, is there evidence, behavior, acceptance criteria, and test coverage?
Mechanical integrity — are there dangling IDs, orphan evidence, orphan AC, missing evidence, sensitivity: unknown items, authorization gaps, or blocking TBDs?
Routing — which downstream handoff blockers remain, and which upstream skill owns each one?
This skill is an audit and governance packager. It is notlegacy-brd-to-sdd-handoff — it neither produces nor replaces the Atlas-bound SDD handoff. It consumes the same upstream artefacts and emits a parallel, traceability-focused package that auditors, SMEs, compliance, and the modernization orchestrator can consume without re-deriving cross-references.
The package is a carrier, not a creator. Every row in the output is a value already present (or already absent and therefore a finding) in the upstream artefacts.
When to Use
Trigger when all of the following hold:
An approved 05_specs/<CAPABILITY-SLUG>/spec.yaml (and spec.md) exists for the capability, or a blocked audit of an unapproved spec is explicitly requested for routing.
The upstream chain (01_inventory/, 02_programs/, 03_flows/, 04_modules/) is at or above approved_with_non_blocking_tbd for every artefact the spec references.
An evidence manifest from legacy-ibmi-evidence-intake is available for every EV-* referenced by the BRD or spec.
A reviewer (audit, compliance, capability owner SME) needs a sealed traceability report — for example before forward SDLC handoff, before an external audit, or as part of an internal field pilot review.
Also use when the orchestrator wants a fast, deterministic answer to "is this capability internally consistent?" before invoking legacy-brd-to-sdd-handoff.
When NOT to Use
Block and route elsewhere when any of the following hold:
spec.yaml is missing entirely → route to legacy-spec-writer. Never fabricate a spec.
Caller wants new BR-*, BEH-*, AC-*, DEC-*, EV-*, TC-*, or TBD-* → route to the owning skill (legacy-spec-writer, legacy-brd-writer, legacy-ibmi-program-analyzer, etc.).
Caller wants an Atlas-consumable SDD handoff package → route to legacy-brd-to-sdd-handoff.
Caller wants architecture, design, user stories, code, or tests → that is the Atlas SDD chain.
The evidence manifest has any item with sensitivity: unknown, missing
source-path authorization, or required redaction without approval → route to
legacy-ibmi-evidence-intake.
Module / flow / program analyses are below approved_with_non_blocking_tbd → route to the relevant analyzer.
This skill is an audit gate and packager. If you find yourself writing new business content, you are in the wrong skill.
Role
You are the traceability auditor and packager for one capability.
You must:
carry every EV-*, BEH-*, BR-*, DEC-*, AC-*, TC-*, TBD-*, IN-*, OUT-*, EX-*, STEP-* ID forward unchanged from the upstream artefacts;
resolve every cross-reference mechanically — every claim of "linked" must point to an ID that actually exists in the upstream artefacts;
promote any review status or downgrade severity to make the package green;
silently demote a sensitivity: unknown evidence item;
treat a missing spec as recoverable by reading the BRD or the analyses directly;
mint a competing SDD handoff package — legacy-brd-to-sdd-handoff owns that artefact.
The only IDs this skill may mint are:
FIND-<CAPABILITY-SLUG>-<NNN> — findings raised by this run; and
a package identifier PKG-<CAPABILITY-SLUG>-<NNN> for the package itself (one per run).
Inputs
Required:
approved 05_specs/<CAPABILITY-SLUG>/spec.yaml and spec.md (or, for an explicit blocked-audit run, a draft/in_review spec accompanied by an explicit status_override: blocked_audit from the caller — the package is still produced as blocked);
05_specs/<CAPABILITY-SLUG>/traceability.md if present (read for cross-check, not for content);
approved upstream analyses referenced by the spec (04_modules/..., 03_flows/..., 02_programs/..., 01_inventory/inventory.yaml);
evidence manifest produced by legacy-ibmi-evidence-intake for every EV-* referenced by the BRD or spec, using the canonical manifest fields evidence_id, sensitivity, redaction_status, redacted_filename, source_path_verified, redaction_required, sme_required, and sme_approval;
a named capability-owner SME (for sign-off on the resulting package).
Optional:
approved 05_brds/<CAPABILITY-SLUG>/brd.md and brd-review.md (if a BRD step was executed);
approved 06_sdd_handoffs/<CAPABILITY-SLUG>/ package (if the SDD handoff has already been packaged — the traceability package then cross-checks the handoff for consistency);
approved legacy-golden-master-test-planner output, if present, for TC-* cross-check.
Input readiness scoring:
0-5 blocked: required spec/upstream analysis missing or below status,
evidence manifest incomplete or unauthorized, referenced IDs unresolved,
blocking TBDs unresolved, or required SME sign-off missing.
6 minimum_pass: approved spec, approved upstream analyses, canonical
evidence manifest, named capability-owner SME, and resolvable ID graph are
present.
7-8 usable: approved BRD, handoff package, and existing traceability view
are supplied for cross-checking.
9-10 strong: approved golden-master test outputs, runtime coverage notes,
audit/compliance review context, and downstream package expectations are also
supplied.
Missing BRD, handoff, or golden-master outputs does not block when the run is
explicitly spec-centered; it limits cross-check coverage and should be listed
as optional missing.
Stop conditions are listed under When NOT to Use; each one is blocking by default and the gate does not advance unless explicitly cleared by an SME-recorded waiver in the upstream artefact.
Output Contract
Produce exactly one directory 06_traceability_packages/<CAPABILITY-SLUG>/. This path sits alongside06_sdd_handoffs/<CAPABILITY-SLUG>/, not inside it; the two packages are produced by different skills, serve different consumers, and must not overwrite each other.
For pass and pass_with_warnings outcomes, write exactly these four files:
06_traceability_packages/<CAPABILITY-SLUG>/
├── traceability-package.yaml ← machine-readable, sealed traceability contract
├── traceability-package.md ← human-readable rendering of the same content
├── coverage-audit.md ← EV / BR / AC / TC / DEC coverage tables
└── traceability-review.md ← gate checklist, findings, sign-offs
A blocked package is a normal outcome, not an error. The gate's job is to fail loudly and early so the upstream skill can fix the artefact before forward SDLC consumes it.
traceability-package.yaml is a carrier, not a creator. Every field traces back to a value in the BRD, spec, evidence manifest, upstream analyses, or to a FIND-* generated during this run.
Why this directory and not 06_sdd_handoffs/?
06_sdd_handoffs/<CAP>/ is the Atlas-bound sealed handoff produced by legacy-brd-to-sdd-handoff. Mixing a traceability audit into that directory would (a) confuse downstream Atlas consumers about what the directory contains, (b) collide with that skill's blocked-path discipline (it writes only handoff-review.md and blocking-finding.yaml), and (c) imply that this skill produces handoffs, which it does not. Numbering both directories 06_ keeps the audit and the handoff at the same governance tier (post-spec, pre-Atlas) while keeping owners and consumers distinct.
capability (id, name, slug, owner — copied unchanged from the spec)
status — pass | pass_with_warnings | blocked
source_artifacts — paths, IDs, and statuses for spec, BRD (optional), module, flows, programs, inventory, evidence manifest, and any pre-existing SDD handoff package
brd_functional_coverage — when a BRD is supplied, section 1-9 coverage
copied from BRD review decisions and audited for blocked / missing required
areas
id_inventory — counts and ID lists per prefix (EV, BEH, BR, AC, DEC, TC, TBD, IN, OUT, EX, STEP, DATA, OBJ, FLOW, MODULE, CAP)
evidence_coverage — for every EV-*, the IDs that reference it and whether it is orphan
behavior_coverage — for every BEH-*, supporting EV-* and the BR-* it backs
business_rule_coverage — for every BR-*, linked BEH-*, EV-*, and AC-*, plus review status
acceptance_criteria_coverage — for every AC-*, validated BR-* and any TC-* that exercises it
test_coverage — for every TC-*, the AC-* or BR-* it validates and any EV-* sample-data reference
decision_coverage — for every DEC-*, the BR-* / BEH-* / constraint cited in its rationale
open_questions — every TBD-* carried forward verbatim with blocking, resolution, resolver, planned_resolution_date, and deferral_recorded_in
findings — { blocking[], warnings[], info[] }, each entry minted as FIND-*
review_sign_offs (alias: sme_sign_offs) — spec approver, BRD approver (if present), packager validator, packager SME approver, each with name, role, ISO date, and approval_scope
next_routing — for each finding, the upstream skill and capability owner who must act, plus whether a re-run is expected
A package is sealed: every ID present in traceability-package.yaml must already exist in the upstream artefacts. The skill must not append any ID that is not derivable from upstream content.
See Inputs and When NOT to Use above. The skill must not start if any required upstream artefact is missing or below its required status.
Execution
Procedure: see references/workflow.md — eight ordered steps (intake → ID inventory → cross-reference walk → evidence-sensitivity check → BR closure check → AC / TC coverage → TBD carry-forward → package assembly or blocked-route).
Allowed inference: copying fields verbatim from spec / BRD / evidence manifest / upstream analyses; counting and indexing IDs; computing pass/warn/fail on the gate checklist; minting FIND-* for findings and PKG-* for the package; routing each finding to its owning upstream skill.
Forbidden inference: see references/anti-hallucination.md. In particular: no new BR-*, BEH-*, AC-*, DEC-*, EV-*, TC-*, or TBD-*; no rewriting of upstream content; no architecture, framework, or platform recommendations.
TBD handling: blocking unresolved TBD → block package, write finding; SME-deferred blocking TBD with named resolver + planned date + deferral_recorded_in pointer → carry forward as warning; non-blocking TBD → carry forward as info.
Output
Canonical directory: 06_traceability_packages/<CAPABILITY-SLUG>/ with the four files above (or two on blocked).
ID minting policy: this skill may mint only FIND-* and PKG-*. Every other ID (EV-*, BEH-*, BR-*, DEC-*, AC-*, TC-*, TBD-*, IN-*, OUT-*, EX-*, STEP-*, OBJ-*, FLOW-*, MODULE-*, CAP-*, DATA-*, NODE-*, EDGE-*, VIEW-*, ACTOR-*, SYS-*, SEED-*, BRD-*) must be reused unchanged from upstream artefacts. Using a prefix outside this minting list is a mechanical failure.
Immutable guarantees:
every upstream ID appears in the package exactly as in its source artefact; no renumbering, no rewording;
no evidence is dropped; sensitivity is recorded, never hidden;
traceability is bidirectional (every approved BR-* links forward to AC-* and backward to EV-*);
finding categorisation is conservative: ambiguous cases default to blocked, never silently pass_with_warnings.
Validation
Mechanical: gate checklist booleans evaluated against the spec / BRD / evidence manifest; no null values left in traceability-package.yaml; every referenced ID resolves; only FIND-* and PKG-* are minted; status field matches the findings actually present.
AI semantic: every blocking finding cites a rule from references/output-contract.md and names the responsible upstream skill; every warning carries enough context for a reviewer to decide whether to waive.
SME approval: the package sign-off block records name + role + ISO date for the capability-owner SME plus any audit / compliance reviewer required by the host project.
Use legacy-step-validator to validate the produced package against this Step Contract before forwarding it to the orchestrator or to forward SDLC.
Workflow State Write-Back (history only)
This is a governance / packager skill. It does NOT mutate
capabilities[].stage_id or current_focus. After a packaging run,
append one history[] entry to <project-root>/workflow-state.yaml per
docs/workflow-state-contract.md.
history:-at:<ISO8601>
skill: legacy-traceability-packager
capability_id: <CAP-* from current_focus>
stage_after: <the capability's current stage_id — UNCHANGED>
artifact: <path to the sealed package or findings report>
note: "traceability sealed for <CAP-*>" | "blocked: <findings count>"
Also overwrite project.last_updated_at / project.last_updated_by.
Permitted side-effect: if any blocking finding emerges, you MAY
append items to capabilities[<CAP-*>].blocking.gates (e.g.
"forward_handoff") and to blocking.tbds. You MUST NOT change
stage_id, last_artifact, or last_skill.
If workflow-state.yaml does not exist, this skill does NOT create it.
every gate passed; no blocking, warning, or info findings were raised
pass_with_warnings
pass_with_warnings
every blocking gate passed, but at least one warning or info finding is present (deferred blocking TBD, non-blocking TBD, SME-waived orphan evidence, or SME-waived AC)
blocked
blocked
at least one blocking finding; only traceability-review.md and blocking-findings.yaml are written
There is no fourth status. Ambiguous cases default to blocked.
Examples
Three adversarial examples exercise the gate end-to-end. Each ships with the expected status and the rule that fires; full inputs are referenced rather than duplicated.
Credit Limit Enforcement: every EV-* reaches a BR-* or BEH-*; every approved BR-* has EV-*, BEH-*, and AC-*; every AC-* validates an approved BR-*; no sensitivity: unknown; no open TBD.
Returns Processing: every blocking gate clears, but one TBD-* with blocking: true carries a named SME deferral and a planned 2026-07-31 resolution date recorded in spec-review.md.
pass_with_warnings
All three examples reuse stable IDs from real or representative capabilities and ship a minimal expected-output snippet so a reviewer can diff the rule against the run.
Review Gate Checklist
Before writing a non-blocked traceability package, every box below must be true. A clean pass also requires zero warning and info findings; otherwise the non-blocked result is pass_with_warnings.
spec.yamlstatus: approved (or explicit blocked_audit override for routing-only runs)
every referenced upstream artefact (01_inventory/, 02_programs/, 03_flows/, 04_modules/, optional 05_brds/) is at or above approved_with_non_blocking_tbd
every EV-* referenced in the spec / BRD resolves in the evidence manifest and has sensitivity ≠ unknown and an SME-approved redaction_status
every approved BR-* links to ≥1 EV-*, ≥1 BEH-*, and ≥1 AC-*
every AC-* validates at least one existing, approved BR-* (or carries an SME waiver)
every DEC-* rationale references at least one of BR-*, BEH-*, or an explicit platform / regulatory constraint
every TC-* validates ≥1 AC-* or BR-* and, when claiming a golden master, names an EV-* for sample data
for pass, no open TBD-* remains; for pass_with_warnings, every open TBD-* carries a category, resolver, and non-blocking or explicitly deferred status
for pass, no orphan EV-*; for pass_with_warnings, every orphan EV-* is explicitly SME-waived in spec-review.md
no dangling ID in any cross-reference field
traceability-package.yaml contains no values that are not derivable from upstream artefacts or this run's findings
handoff cross-check passes (if an 06_sdd_handoffs/<CAP>/ package exists, its IDs match the spec; the traceability package neither overwrites nor contradicts it)
package sign-off block present (packager + capability SME) with name, role, and ISO date
If even one box is unchecked, the package is blocked and the only files written are traceability-review.md and blocking-findings.yaml.
Runtime Portability
Canonical source: skills/legacy-traceability-packager/. Runtime adapters under .claude/skills/, .codex/skills/, .opencode/skills/, and .agents/skills/ are produced by scripts/sync-skills.sh and must not be edited directly.
Maintenance and Versioning
Current Version: 0.1.2
Last Updated: 2026-05-28
Author: Leo L Zhang
Status: field-pilot ready; three-runtime smoke passed in Codex, Claude Code, and OpenCode
Version history:
v0.1.2 (2026-05-28): Added brd_functional_coverage audit output when a
BRD is supplied. Required BRD sections 1-9 must appear exactly once, with
blocked or missing section coverage raised as traceability findings.
v0.1.1 (2026-05-16): Tightened status semantics so clean pass has no findings, aligned package IDs with shared ID conventions, corrected the positive example to remove open TBDs, clarified AC validation and blocked-run continuation rules, and passed three-runtime smoke in Codex CLI (gpt-5.4-mini), Claude Code (haiku), and OpenCode (minimax-m2.5-free).
