Tracegen matrix

Tracegen — Traceability Matrix

Generate / update <app_folder>/context/TRACEABILITY.md — a per-application matrix linking every PRD requirement ID (and bug code) to the source code that implements it. Two layers per module: module-level (every ID of a module → that module's implementing code, complete coverage) and symbol-level (specific ID → the specific file/symbol that implements it, where derivable).

This skill is codebase-memory-OPTIONAL. It resolves links from in-source traceability comments and source scanning, and only uses the codebase-memory MCP for extra precision when present. It must NEVER fail or produce an empty file just because codebase-memory is not installed.

When to Use This Skill

• Automatically, as the final traceability step of conductor-feature-develop (after all modules for a version are implemented) and conductor-defect (after all bugs for a version are fixed).
• Manually, when a user asks to (re)generate or refresh the traceability matrix for an application.

Prerequisites

• <app_folder>/context/PRD.md — tagged requirement IDs (run util-ustagger first if untagged).
• <app_folder>/context/specification/<module>/SPEC.md — per-module specs with a Traceability section listing the module's requirement IDs (and, for backends, the implementing package).
• Application source code under <app_folder>/ (or the resolved source: path). If no source code exists yet, the skill still produces a forward-traceability stub (see Workflow step 6c).

Version Gate

Before starting any work, resolve the application folder first (see Input Resolution), then check CHANGELOG.md in the application folder (<app_folder>/CHANGELOG.md):

1. If <app_folder>/CHANGELOG.md does not exist, skip this check (first-ever execution).
2. If it exists, scan all ## vX.Y.Z headings and determine the highest version via semantic version comparison.
3. If a version: argument was provided and the requested version < highest version → STOP immediately. Print: "Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."
4. If no version: argument was provided (regenerating against the current state), skip the gate.

Input Resolution

/tracegen-matrix <application> [version:<version>] [module:<module>] [source:<source-code-path>]

Argument	Required	Description
<application>	Yes	Application name OR an already-resolved <app_folder> path. Matched against root-level application folders.
version:<version>	No	Single version (e.g. version:v1.2.0). Used for the Version Gate and to label the changelog row and the file header. Does NOT filter which IDs are linked — the matrix always reflects the full current PRD + code.
module:<module>	No	If provided, (re)generate ONLY that module's section in TRACEABILITY.md, preserving all other sections. If omitted, regenerate the whole file.
source:<path>	No	Path where source code resides. Defaults to <app_folder> (same convention as the conductors).

Application Folder Resolution

1. If <application> is already a path to an existing folder containing a context/ subfolder, use it directly as <app_folder> (this is how the conductors pass it).
2. Otherwise, list root-level application folders; strip any leading <number>_ prefix; match the provided name case-insensitively (accept snake_case, kebab-case, or title-case).
3. If no match is found, list available applications and stop.

Auto-Resolved Paths

Item	Resolved Path
PRD.md	<app_folder>/context/PRD.md
Specifications	<app_folder>/context/specification/<module>/SPEC.md
Develop tracking	<app_folder>/context/develop/<module>/IMPLEMENTATION_MODULE.md
Source code	<source-code-path>/ (defaults to <app_folder>/)
Output	<app_folder>/context/TRACEABILITY.md

Resolution Strategy (codebase-memory is OPTIONAL)

Pick code references for each requirement ID using the following cascade. Combine the layers — do not stop at the first that yields a hit.

1. In-source traceability comments (PRIMARY — no MCP, deterministic). conductor-feature-develop stamps every source file it creates with a top-of-file comment listing the requirement codes it implements, and conductor-defect appends bug codes:

   Implements: USHM00003, USHM00006
   NFR: NFRHM0003
   Constraints: CONSHM003
   Bug fixes: [BUG-024]
   

   For each requirement / bug code, scan the source tree for that exact code. Every file whose top-of-file comment contains the code is an implementer of it. Map file → symbol using the primary declared type/function in that file (class/interface/component name, usually = filename).

   • Recommended scan: ripgrep over source files, excluding context/, build output, dependencies, and tests — e.g. search the codes within the first ~20 lines / comment blocks of each file.

2. Name-based source scan (FALLBACK — no MCP). When a module's IDs produce NO comment hits (e.g. legacy code authored before the traceability- comment rule, as in pre-existing applications), resolve at module granularity instead:

   • Backend: read the module's SPEC.md Package (e.g. my.app.module.foo) and locate the matching source directory; collect its controller / service / repository / entity / mapper / DTO files.
   • Frontend: read the module's SPEC.md named pages/components/hooks/api and Mockup Screens, then locate the matching source files by name under the app's src/. Every ID of the module links to this resolved set (module-level layer).

3. codebase-memory enrichment (OPTIONAL — only if the MCP is installed). If the codebase-memory MCP tools (search_graph, search_code) are available in this session, resolve each matched file to its exact graph qualified_name for precise, navigable anchors, and use the graph to discover additional same-module symbols. If the MCP is NOT available, skip this step entirely and use file-path references instead (see Reference Format). The matrix content and structure are identical either way; only the anchor precision differs.

Hard rule: never invent a reference. A reference must come from a real comment hit, a real source file located on disk, or (when present) a real codebase-memory node. If a specific symbol cannot be resolved, leave the symbol-level cell as —; the module-level layer still covers it.

Reference Format

• codebase-memory present → use the full graph qualified_name (exact node anchor).
• codebase-memory absent → use a repo-relative path with optional symbol suffix: path/to/File.java#ClassName (or src/features/foo/pages/FooPage.tsx#FooPage).

Record which mode was used in the file header so readers know how to interpret the anchors.

Workflow

1. Resolve inputs — application folder, source path, optional version/module (Input Resolution). Apply the Version Gate.
2. Detect capabilities — record: (a) is the codebase-memory MCP available? (b) do source files carry in-source traceability comments? (sample a few known IDs). These two booleans select the active resolution layers and the Reference Format.
3. Enumerate modules — glob <app_folder>/context/specification/*/SPEC.md. If module: was provided, restrict to that module.
4. Extract requirement IDs per module — from each SPEC.md Traceability section: User Story, NFR, and Constraint IDs with their version tags. Also collect the module's Package (backend) or named components (frontend), and any [BUG-XXX] codes recorded for the module in PRD.md's ### Bug section. Cross-check <app_folder>/context/develop/<module>/IMPLEMENTATION_MODULE.md when present for explicit ID→symbol hints.
5. Resolve code references — apply the Resolution Strategy cascade to build, per module:
   • the module-level set (the module's implementing files/symbols), and
   • symbol-level links for the specific IDs where a comment hit or SPEC/IMPLEMENTATION naming pins a specific file/symbol. Mark symbol-level links inferred when derived from naming rather than an explicit comment hit.
6. Write TRACEABILITY.md using the Output structure below.
   • a. Whole-file regeneration when no module: filter.
   • b. Single-module update when module: is given — replace only that module's ## <Module> section, preserving every other section and the file header/summary (recompute the summary).
   • c. If NO source code exists for the app yet, still write the file: list every module's full ID inventory with all symbol cells —, plus the module's intended SPEC-named symbols as plain (non-anchor) references, and a prominent NOT-YET-IMPLEMENTED banner. This preserves forward traceability and is regenerated to real anchors once code exists.
7. Changelog Append — see below.
8. Print a summary — modules processed, total IDs linked (US/NFR/CON counts), symbol-level link count, resolution mode used (comments / name-based / graph-enriched), and any unresolved IDs.

Output

A single file: <app_folder>/context/TRACEABILITY.md.

# Traceability — <Application Display Name>

> **Purpose**: links every PRD requirement ID (User Stories, NFRs, Constraints) and bug code from
> `context/PRD.md` + `context/specification/*/SPEC.md` to the source code that implements it.
> **Resolution mode**: <in-source comments | name-based scan | graph-enriched> — anchors are
> <codebase-memory qualified_names | repo-relative file paths>.
> **Two layers**: _module-level_ — every ID of a module maps to that module's implementing code
> (complete); _symbol-level_ — specific ID → the specific file/symbol where derivable (partial,
> `(inferred)` when from naming rather than an in-source comment).
> **Maintenance**: regenerated by `tracegen-matrix` at the end of `conductor-feature-develop` and
> `conductor-defect`; re-run manually after significant code moves.

---

## <Module Name>  ·  prefix `<PFX>`  ·  package `<package or n/a>`

**Module-level code** (every ID below maps to these):
- `<reference>` — <role e.g. Controller / Page>
- `<reference>` — <role e.g. ServiceImpl / Hook>
- …

**Requirement links:**

| ID | Type | Ver | Symbol-level implementation |
|----|------|-----|-----------------------------|
| USHM00003 | US | v1.0.0 | `<reference>` |
| NFRHM0003 | NFR | v1.0.0 | — |
| CONSHM003 | CON | v1.0.0 | `<reference>` (inferred) |
| BUG-024 | BUG | v1.0.1 | `<reference>` |

---

(repeat per module)

## Summary
- Modules: <N>
- IDs linked: <N> (US <a>, NFR <b>, CON <c>, BUG <d>)
- Symbol-level links: <N>
- Resolution mode: <comments | name-based | graph-enriched>
- Unresolved: <short list or "none">

Type abbreviations: US = User Story, NFR = Non-Functional Requirement, CON = Constraint, BUG = bug fix code.

Changelog Append

After the matrix is successfully written, append an entry to <app_folder>/CHANGELOG.md:

1. If <app_folder>/CHANGELOG.md does not exist, create it with the standard CO2 changelog header.
2. Determine the version label: the version: argument if provided, else the highest version in the changelog, else v1.0.0.
3. Search for a ## {version} heading. If it exists, append a new row; if not, insert a new section after the --- below the header and before any existing ## vX.Y.Z section (newest-first).
4. Row format: | {YYYY-MM-DD} | {application_name} | tracegen-matrix | {module or "All"} | Regenerated TRACEABILITY.md — {N} IDs linked ({fine} symbol-level), mode: {resolution-mode} |
5. Never modify or delete existing rows.

Constraints

• codebase-memory is OPTIONAL. The skill MUST complete and produce a useful TRACEABILITY.md when the codebase-memory MCP is absent, using in-source comments and source scanning. Treat the graph purely as an enrichment for anchor precision.
• Never fabricate a reference. Every anchor must trace to a real in-source comment, a real file on disk, or a real graph node. Unresolved symbol-level cells are —.
• Preserve unrelated sections. With a module: filter, only that module's section may change.
• Do not modify source code, PRD.md, SPEC.md, or any other artifact. This skill only writes TRACEABILITY.md and appends one CHANGELOG.md row.
• Preserve requirement tags verbatim. Use the 9-character util-ustagger codes and [BUG-XXX] codes exactly as they appear; never reformat or invent codes.
• Idempotent. Re-running with the same inputs reproduces the same matrix (modulo newly added code or requirements).