source-traceability

name	source-traceability
description	Use when asking about "traceability", "source", "citation", "doc comment", "SOURCE_INDEX", "where did this come from", "reference", "traceability matrix", "DI-XXX", "PR-XXX", "source type", "confidence", "authority source", "durable chain", or when deciding how to cite sources, write doc comments, or record traceability. Provides the durable traceability chain, citation patterns, and traceability matrix schema.
allowed-tools	Read, Grep, Glob
user-invocable	false

Source Traceability

The durable traceability chain, citation patterns, SOURCE_INDEX format, and traceability matrix schema.

Core Principle

Every model element traces to an authority source. Traceability is recorded during implementation as a byproduct of work, not as a separate phase. The chain uses only durable artifacts — per-work-item specs are where traceability is discovered, but durable project files are where it lives.

When to Reference

• /implement-model — recording source citations in doc comments and traceability matrix
• /design-model — parameter extraction with source attribution
• /spec-model — defining traceability requirements for success criteria
• /audit-models — verifying traceability completeness and baseline comparison
• /research — domain source investigation and citation patterns
• /manage-sources — configuring authority sources in SOURCE_INDEX.md

The Durable Traceability Chain

DI-XXX (domain insight, in KNOWLEDGE.md)
   |
   | Source column in REQUIREMENTS.md
   v
PR-XXX (promoted requirement, in REQUIREMENTS.md)
   |
   | Requirement column in traceability_matrix.csv
   v
Model element (part def, calc def, constraint)
   |
   | Source/Reference fields in doc comment
   v
Authority source (file:line in codebase, section in spec doc)

Each node is a durable artifact. Per-work-item spec.md files may reference these IDs but are not part of the durable chain — they are ephemeral and archived when work completes.

SOURCE_INDEX.md Format

Location: knowledge/SOURCE_INDEX.md

Each source entry follows this format:

### [Source Name]
- **Type**: codebase | documentation | database | reference
- **Location**: path or URL
- **Use For**: what questions this source answers
- **Validation**: how to verify against this source, or "N/A"

Source types:

Type	Description	How Commands Use It
codebase	Code repository	Launch Explore agents to analyze
documentation	PDF, markdown, text files	Read/search for relevant sections
database	API or database endpoint	Query for data
reference	Books, papers, standards	Note for citations, don't deep-analyze

Doc Comment Content Requirements

Every part def, calc def, and constraint def requires a doc comment with three fields:

Field	What It Must Contain	Example
Source	The authority document or codebase that justifies this element	Reference codebase power balance module
Reference	Specific locator within the source	power_balance.py:94-102
Last Updated	Date when the citation was last verified	2026-01-28

For doc comment syntax and format, see the sysml-conventions skill.

Citation Patterns

Source Type	Citation Pattern	Example
Codebase	file.py:line X-Y or module/file.py:function_name	DefineInputs.py:45-48
Documentation	Document Name, Section X.Y	ITER Physics Basis, Section 4.2
Online	URL (accessed YYYY-MM-DD)	https://example.com (accessed 2026-01-15)
Standard	Standard ID, Section/Clause	ISO 19514:2017, Clause 7.3
Research	knowledge/research/approved/YYYYMMDD_topic.md	knowledge/research/approved/20260115_thermal.md

Codebase citations must include line numbers for parameters extracted from code. This enables automated verification during audits.

Traceability Matrix Schema

Location: data/traceability_matrix.csv

Column	Description	Example
Element	Model element name	ThermalSystemCostCalc
File	SysML file path	models/library/analyses/thermal_cost.sysml
Type	Element kind	calc def
Knowledge	DI-XXX IDs this traces to	DI-003, DI-012
Requirement	PR-XXX IDs this satisfies	PR-005
Source_Type	Authority source kind	codebase
Source_Document	Authority source name	ReferenceImpl
Source_Location	Specific location	thermal_cost.py:94
Confidence	Assessment level	High
Assumptions	Known approximations	Uses 2024 material costs
Last_Verified	Date of last audit	2026-01-28

Both Knowledge (DI-XXX) and Requirement (PR-XXX) columns may be populated. The Knowledge column enables direct impact queries when a domain insight is superseded. The Requirement column enables coverage checking.

When to Record Traceability

Traceability is recorded during implementation, not after:

When	What to Record	Where
Writing a definition	Source and Reference in doc comment	Doc comment fields
Completing a model element	Element → PR-XXX and DI-XXX links	data/traceability_matrix.csv
Promoting a requirement	MR-XXX → PR-XXX with source	modeling_project/REQUIREMENTS.md

The trace-element AP-7 script handles mechanical recording. The agent supplies content; the script enforces schema, prevents duplicates, and validates that PR-XXX and DI-XXX IDs exist.

Confidence Assessment

Level	Criteria
High	Direct extraction from authority source with exact values; verified by audit
Medium	Derived from authority source with interpretation or unit conversion; consistent with source
Low	Estimated, interpolated, or from secondary sources; needs verification

Anti-Patterns

Instead of	Do
Recording traceability as a separate phase after implementation	Record during implementation — it's a byproduct of work
Citing "the codebase" without specifics	Cite file.py:line X-Y with exact locations
Skipping doc comments on definitions	Every def needs Source, Reference, Last Updated
Relying on per-work-item specs for traceability	Use durable artifacts: REQUIREMENTS.md, traceability_matrix.csv
Leaving Confidence blank	Assess as High/Medium/Low — enables prioritized verification
Omitting Last_Verified date	Always record when citation was last checked

Related Skills

• For doc comment syntax and format, see the sysml-conventions skill.
• For PR-XXX entity format and promotion path, see the requirements-tracking skill.