Validation & Errors
Before any output is generated, Trace runs every workbook through XLSX parsing, schema ingest, semantic validation, and optionally profile-aware chain checks. This page explains what blocks output, what only warns, and how profile-aware validation changes the result.
Errors — block output
A fatal problem Trace cannot work around. The workbook is rejected and no report is generated. The CLI exits with code 1. Native apps show a failure message and do not advance to the generation state.
Warnings — report still generated
A condition worth knowing about that doesn't prevent Trace from producing output. Warnings appear in the CLI output, in the native app's load summary, and in the gaps JSON file.
Stage 1: XLSX parsing
The first stage validates the workbook as a file before any traceability logic runs.
| Check | Fatal? | Cause |
|---|---|---|
| File exists and is readable | Error | Path does not exist, or process lacks read permission |
| Valid ZIP/OOXML container | Error | File is not a valid .xlsx — may be .xls, corrupted, or misidentified |
| Required workbook parts present | Error | Missing [Content_Types].xml or workbook XML — broken container |
| Workbook XML readable | Error | Malformed XML in the workbook structure |
| Shared strings file present | Warning + empty string table | Workbook has no shared strings. Cells that rely on it will appear empty. |
| Worksheet XML readable | Warning + skip sheet | A single broken sheet doesn't fail the whole parse — the sheet is skipped |
Stage 2: Schema ingest
Once the file is parsed, the schema layer maps workbook content to the RTMify traceability model. This involves three sub-stages.
Tab discovery
Trace locates the four expected tabs using a four-tier matching strategy:
- Exact name match
- Synonym match (e.g. "User Requirements" → Requirements tab)
- Substring match
- Fuzzy match with Levenshtein distance ≤ 2
| Tab | Required? | If missing |
|---|---|---|
| Requirements | Required | Fatal error — no requirements, no RTM |
| User Needs | Optional | INFO diagnostic; all requirements will be orphaned |
| Tests | Optional | INFO diagnostic; all requirements will be untested |
| Risks | Optional | INFO diagnostic; Risk Register section will be empty |
Ambiguous matches (two tabs that both score equally) produce a WARN diagnostic and use the first match.
Column matching
Within each discovered tab, columns are matched using a four-tier strategy identical to tab discovery, plus an ID-pattern heuristic for ID-type columns. Headers are matched case-insensitively. Extra columns are ignored.
| Column failure | Severity | Effect |
|---|---|---|
| Required column not found | Error | Cannot ingest the tab; treated as missing |
| Ambiguous column match | Warning | Leftmost matching column wins; WARN emitted |
| Optional column not found | Silent | Field treated as empty for all rows |
Semantic validation
After rows are ingested, Trace performs semantic checks on requirement text and structure:
- —Requirements missing the word "shall" — flagged as potentially non-normative
- —Requirements containing vague terms (e.g. "appropriate", "adequate") — flagged as potentially ambiguous
- —High-risk items with no associated mitigation requirement — flagged as unmitigated
These are warnings, not errors. They appear in the warning count and the gaps JSON, but they don't block report generation.
Profile-aware validation
When you run the CLI with --profile medical, aerospace, or automotive — or select those profiles in the macOS or Windows apps — Trace enables additional tabs during ingest and then runs profile-specific chain checks over the graph.
| Profile | Additional ingest surface | Examples of added checks |
|---|---|---|
| medical | Product, Design Inputs, Design Outputs, Configuration Items | Design input/output continuity, implementation evidence, configuration control |
| aerospace | Product, Decomposition, Configuration Items | HLR → LLR decomposition, source/configuration-item continuity |
| automotive | Product, Configuration Items | ASIL inheritance, hazard/safety-goal requirement chains, automotive evidence checks |
Missing expected profile tabs do not block output. Trace emits a warning diagnostic and continues, allowing the downstream profile gap analysis to show what chain evidence is missing.
Failure reference
A summary of all failure categories, their severity, and the user-visible effect:
| Category | Severity | CLI exit | Native app effect |
|---|---|---|---|
| File not found / unreadable | Fatal | 1 | Load failure; stays in drop zone |
| Invalid XLSX container | Fatal | 1 | Load failure; stays in drop zone |
| Requirements tab missing | Fatal | 1 | Load failure; file rejected |
| Required column not found | Fatal | 1 | Load failure; file rejected |
| Traceability gaps | Warning | 0 (or N hard gaps in --strict) | Hard and advisory gaps shown; report generated unless strict mode returns the hard-gap count |
| Semantic warnings | Warning | 0 | Warning count shown; report generated |
| Output path not writable | Fatal | 5 | Generation failure; no done state |
| License required / free run exhausted | Fatal | 2 | Remains on license gate |
| License expired | Fatal | 3 | Remains on license gate |
| License invalid / tampered / wrong product | Fatal | 4 | Remains on license gate |
Trace treats diagnostics and gaps separately. Diagnostics describe workbook/container/header/reference problems. Gaps describe traceability structure and audit readiness. In --strict mode, generic hard gaps and profile error findings affect the exit code.