trace-check
Validate and update bidirectional traceability across SDD artifacts (project)
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: trace-check
description: Validate and update bidirectional traceability across SDD artifacts (project)
---
# trace-check
## Purpose
Automated traceability validation across all SDD artifacts.
**Core Functions**:
- Validates bidirectional link consistency (upstream/downstream symmetry)
- Verifies ID format compliance (TYPE-XXX or TYPE-XXX-YY)
- Tests markdown link resolution (file paths and anchors)
- **NEW**: Validates cumulative tagging hierarchy (each layer includes ALL upstream tags)
- **NEW**: Layer-specific tag count validation (artifacts at layer N must have tags from layers 1 through N-1)
- Calculates coverage metrics (% artifacts with complete traceability)
- Detects orphaned artifacts (no upstream or downstream links)
- Auto-fixes broken links with backup creation
**SDD Workflow** (v2.0 - Functional Layer Groupings):
```
Business Layer: BRD → PRD → EARS →
Testing Layer: BDD →
Architecture Layer: ADR → SYS →
Requirements Layer: REQ →
Implementation Strategy Layer: IMPL (optional) →
Interface Layer: CTR (optional) →
Technical Specs Layer: SPEC →
Execution Planning Layer: TASKS → IPLAN →
Code & Validation Layer: Code → Tests → Validation → Review → Production
```
**Reference**: [TRACEABILITY.md v2.0]({project_root}/ai_dev_flow/TRACEABILITY.md) (updated 2025-10-31)
**Complexity**: Medium (requires parsing multiple file formats)
**Resource Requirements**:
- CPU: Moderate (file parsing, regex matching)
- Memory: 100-500MB for 100-200 artifacts
- Disk: 1-10MB for backup archives
- Network: None (local file operations only)
**Failure Modes**:
- Invalid ID format: Reports non-compliant document IDs
- Broken links: Reports file paths that do not resolve
- Missing anchors: Reports markdown anchors not found in target files
- Bidirectional gaps: Reports asymmetric traceability links
- Orphaned artifacts: Reports documents with no upstream or downstream references
## When to Use This Skill
**Use trace-check when**:
- Before committing changes to documentation
- After creating new artifacts (BRD, PRD, SPEC, etc.)
- After updating existing artifacts
- During periodic audits (weekly/sprint/release)
- Validating traceability matrix completeness
- Detecting orphaned artifacts
- Verifying ID format compliance
- Establishing baseline quality metrics
**Do NOT use trace-check when**:
- Working on code implementation (use code review tools)
- Validating code traceability (use docstring validators)
- For non-SDD documentation projects
- During active editing sessions (wait until stable state)
## Skill Inputs
| Input | Type | Description | Example/Default |
|-------|------|-------------|-----------------|
| project_root_path | Required | Path to project documentation root | `{project_root}/docs/` |
| artifact_types | Optional | Specific artifact types to validate | `["BRD", "SPEC"]` or `["all"]` (default) |
| strictness_level | Optional | Validation strictness | `"strict"` (default), `"permissive"`, `"pedantic"` |
| validate_cumulative | Optional | **NEW**: Validate cumulative tagging hierarchy | `true` or `false` (default) |
| auto_fix | Optional | Auto-fix broken links | `true` or `false` (default) |
| report_format | Optional | Output report format | `"markdown"` (default), `"json"`, `"text"` |
**Strictness Levels**:
- `permissive`: Warnings only, no failures for missing reverse links
- `strict`: Fails on broken links and missing bidirectional consistency
- `pedantic`: Fails on any traceability gaps including "To Be Created" sections
## Skill Workflow
### Step 1: Discover All Artifacts
**Actions**:
- Scan `docs/` directory for all artifact types
- Parse filenames to extract document IDs (BRD-001, SPEC-001, etc.)
- Build artifact inventory with file paths
- Filter by artifact_types parameter if specified
**Expected Results**:
- 50-200 artifacts per project
- Inventory mapping: ID → file path
- Coverage: All .md, .yaml, .feature files
**Validation**:
- Verify directory structure: `docs/{TYPE}/` exists
- Confirm file naming: `{TYPE}-{XXX}_{description}.{ext}`
- Check for duplicate IDs within same type
### Step 2: Parse Traceability Sections
**Actions**:
- Read each artifact's Section 7 "Traceability"
- Extract upstream sources (documents this derives from)
- Extract downstream artifacts (documents derived from this)
- Parse markdown links: `[ID](path#anchor)` format
- Store bidirectional relationship map
**Markdown Pattern Recognition**:
```
**Upstream Sources:**
- [BRD-001](../BRD/BRD-001_file.md#BRD-001) - Title (Status, Date)
**Downstream Artifacts:**
**In Progress:**
- [SPEC-001](../SPEC/SPEC-001_file.yaml#anchor) - Title (Status, Date)
**To Be Created:**
- SPEC-002+: Description (TBD)
```
**Data Structure**:
- Upstream map: {artifact_id: [upstream_ids]}
- Downstream map: {artifact_id: [downstream_ids]}
- Link details: {source_id, target_id, file_path, line_number, anchor}
### Step 2.5: Extract Traceability Tags from Code
**Actions**:
1. Scan all source files (.py, .md, .yaml, .feature) for tag patterns
2. Parse @brd:, @sys:, @spec:, @test:, @impl-status: tags
3. Validate format: DOCUMENT-ID:REQUIREMENT-ID
4. Build tag-to-document mapping
5. Cross-reference with actual document existence
**Tag Extraction Regex**:
```python
import re
TAG_PATTERN = r'@(\w+(?:-\w+)?):\s*([\w\-]+(?::[\w\-]+)?(?:\s*,\s*[\w\-]+(?::[\w\-]+)?)*)'
# Example matches:
# @brd: BRD-001:FR-030, BRD-001:NFR-006
# @sys: SYS-008:PERF-001
# @spec: SPEC-003
# @test: BDD-003:scenario-1
```
**Validation Rules**:
1. **Format Check:** All @brd/@prd tags must use DOCUMENT-ID:REQUIREMENT-ID format
2. **Document Exists:** DOCUMENT-ID must reference existing file in docs/{TYPE}/
3. **Requirement Exists:** REQUIREMENT-ID must exist within the document
4. **No Orphans:** All tags must resolve to actual requirements
5. **Implementation Status:** @impl-status must be one of: pending|in-progress|complete|deprecated
**Output**:
```json
{
"src/ibmcp/gateway/connection_service.py": {
"tags": {
"brd": [["BRD-001", "FR-001"], ["BRD-001", "FR-002"], ["BRD-001", "NFR-010"]],
"sys": [["SYS-001", null], ["SYS-002", null]],
"spec": [["SPEC-001", null]],
"test": [["BDD-001", "scenario-auth"], ["BDD-007", "scenario-reconnect"]],
"impl-status": ["complete"]
},
"line_numbers": {
"BRD-001:FR-001": 15,
"BRD-001:FR-002": 15
}
}
}
```
**Error Detection**:
- ❌ `@brd: FR-030` - Missing DOCUMENT-ID
- ❌ `@brd: BRD-999:FR-001` - Document BRD-999 doesn't exist
- ❌ `@brd: BRD-001:FR-999` - Requirement FR-999 not in BRD-001
- ✅ `@brd: BRD-001:FR-030` - Valid format and exists
**Scripts**:
```bash
# Extract tags
python scripts/extract_tags.py --source src/ docs/ tests/ --output docs/generated/tags.json
# Validate tags against documents
python scripts/validate_tags_against_docs.py --tags docs/generated/tags.json --strict
# Generate matrices
python scripts/generate_traceability_matrices.py --tags docs/generated/tags.json --output docs/generated/matrices/
```
### Step 2.6: Validate Cumulative Tagging Hierarchy
**Actions**:
1. For each artifact, determine its position in the artifact sequence (0-15+)
2. Verify artifact includes ALL required upstream tags for its artifact type
3. Check tag count matches expected range for artifact type
4. Validate optional artifacts (IMPL, CTR) handled correctly
5. Ensure tag chain completeness (if @adr exists, @brd through @bdd must exist)
**Expected Cumulative Tag Counts by Artifact Type**:
```
Business Layer:
Strategy: 0 tags (external business docs)
BRD: 0 tags (top level)
PRD: 1 tag (@brd)
EARS: 2 tags (@brd, @prd)
Testing Layer:
BDD: 3+ tags (@brd through @ears)
Architecture Layer:
ADR: 4 tags (@brd through @bdd)
SYS: 5 tags (@brd through @adr)
Requirements Layer:
REQ: 6 tags (@brd through @sys)
Implementation Strategy Layer:
IMPL: 7 tags (@brd through @req) [optional]
Interface Layer:
CTR: 8 tags (@brd through @impl) [optional]
Technical Specs Layer:
SPEC: 7-9 tags (@brd through @req + optional impl/ctr)
Execution Planning Layer:
TASKS: 8-10 tags (@brd through @spec)
IPLAN: 9-11 tags (@brd through @tasks)
Code & Validation Layer:
Code: 9-11 tags (@brd through @tasks)
Tests: 10-12 tags (@brd through @code)
Validation: ALL tags from all upstream artifacts
```
**Note**: Functional layers group artifacts by purpose in the workflow. Tag counts accumulate as artifacts progress through the layers. Numbers indicate artifact sequence position (0-15) in the 16-layer architecture.
**Validation Script**:
```bash
# Validate cumulative tagging hierarchy compliance
python scripts/validate_tags_against_docs.py \
--source src/ docs/ tests/ \
--docs docs/ \
--validate-cumulative \
--strict
```
**Validation Rules**:
1. **Complete Chain**: Each artifact must include ALL upstream tags
2. **Artifact Type Validation**: Artifacts must have all tags from previous functional layers
3. **Optional Layers**: IMPL and CTR are optional; downstream artifacts adjust tag count accordingly
4. **Tag Chain Completeness**: If higher layer tag exists (e.g., @adr), all lower layer tags must exist (@brd through @bdd)
5. **No Gaps**: No missing tags in the cumulative chain
**Error Detection**:
- ❌ `SPEC missing @brd tag` - Incomplete upstream chain
- ❌ `REQ has @adr but missing @bdd` - Gap in cumulative chain
- ❌ `Code has 8 tags but should have 9-11` - Incorrect tag count for artifact type
- ✅ `SPEC has all 9 required tags (@brd through @spec)` - Valid cumulative tagging
**Benefits**:
- Regulatory compliance (SEC, FINRA, FDA, ISO audit trails)
- Complete impact analysis (upstream → downstream traceability)
- Automated validation prevents gaps in traceability chain
- CI/CD enforcement ensures 100% compliance
### Step 3: Validate ID Format Compliance
**Checks**:
- ID format: `TYPE-XXX` or `TYPE-XXX-YY`
- H1 header contains full ID: `# BRD-001`
- Zero-padding: `001` not `1`
- No ID collisions (each XXX unique per type)
- Valid TYPE: BRD, PRD, EARS, BDD, ADR, SYS, REQ, IMPL, CTR, SPEC, TASKS, IPLAN
- **CTR dual-file validation**: For each CTR, both .md and .yaml must exist with matching slugs (see below)
**Reference**: `{project_root}/ai_dev_flow/ID_NAMING_STANDARDS.md`
**Failure Examples**:
- `BRD-9` → Should be `BRD-009`
- `SPEC-1` → Should be `SPEC-001`
- `REQ-42` → Should be `REQ-042`
### Step 3.5: Validate CTR Dual-File Format (MANDATORY)
**Purpose**: Ensure all CTR artifacts comply with dual-file format requirement (.md + .yaml)
**Actions**:
1. Scan `docs/CTR/` for all CTR files
2. Group by CTR-ID (extract from filename)
3. For each CTR-ID, verify:
- Both `CTR-XXX_{slug}.md` and `CTR-XXX_{slug}.yaml` exist
- Slug portion matches exactly in both filenames
- YAML file contains valid schema (JSON Schema, OpenAPI, or AsyncAPI)
4. Report missing files, slug mismatches, or invalid schemas
**Validation Logic**:
```python
def validate_ctr_dual_files(contracts_dir):
"""Validate CTR dual-file format compliance."""
errors = []
ctr_files = glob(f"{contracts_dir}/CTR-*.{{md,yaml}}")
# Group files by CTR-ID
ctr_groups = {}
for filepath in ctr_files:
filename = os.path.basename(filepath)
# Extract: CTR-XXX_{slug}.ext → (CTR-XXX, slug, ext)
match = re.match(r'(CTR-\d{3}(?:-\d{2})?)_(.+)\.(md|yaml)#39;, filename)
if match:
ctr_id, slug, ext = match.groups()
if ctr_id not in ctr_groups:
ctr_groups[ctr_id] = {}
ctr_groups[ctr_id][ext] = (filepath, slug)
# Validate each CTR group
for ctr_id, files in ctr_groups.items():
# Check both files exist
if 'md' not in files:
errors.append(f"{ctr_id}: Missing .md file (MANDATORY)")
if 'yaml' not in files:
errors.append(f"{ctr_id}: Missing .yaml file (MANDATORY)")
# Check slug matches
if 'md' in files and 'yaml' in files:
md_slug = files['md'][1]
yaml_slug = files['yaml'][1]
if md_slug != yaml_slug:
errors.append(
f"{ctr_id}: Slug mismatch - "
f"MD: '{md_slug}' vs YAML: '{yaml_slug}'"
)
# Validate YAML schema (basic check)
if 'yaml' in files:
yaml_path = files['yaml'][0]
try:
with open(yaml_path) as f:
schema = yaml.safe_load(f)
# Check for required schema fields
if not isinstance(schema, dict):
errors.append(f"{ctr_id}: YAML must be a dictionary/object")
elif 'openapi' not in schema and 'asyncapi' not in schema:
# Warn if not OpenAPI/AsyncAPI (may be custom JSON Schema)
errors.append(
f"{ctr_id}: YAML missing 'openapi' or 'asyncapi' field "
"(expected standard schema format)"
)
except Exception as e:
errors.append(f"{ctr_id}: Invalid YAML - {str(e)}")
return errors
```
**Error Examples**:
- `CTR-001: Missing .yaml file (MANDATORY)` → Only .md exists
- `CTR-002: Missing .md file (MANDATORY)` → Only .yaml exists
- `CTR-003: Slug mismatch - MD: 'api_contract' vs YAML: 'api_spec'` → Slugs don't match
- `CTR-004: YAML missing 'openapi' or 'asyncapi' field` → Schema format unclear
- `CTR-005: Invalid YAML - parsing error at line 42` → Malformed YAML
**Success Criteria**:
- ✅ All CTR artifacts have both .md and .yaml files
- ✅ All slug portions match exactly
- ✅ All YAML files parse successfully
- ✅ All YAML files contain valid schema structure (OpenAPI, AsyncAPI, or JSON Schema)
### Step 4: Check Link Resolution
**Tests**:
- File exists: All markdown link paths resolve
- Relative paths: Correct from source file location
- Anchors exist: All `#anchor` references valid
- YAML files: Check `id:` field matches anchor
- Feature files: Verify `Scenario:` lines create anchors
**Relative Path Calculation**:
- From: `/docs/SPEC/SPEC-001.yaml`
- To: `/docs/BRD/BRD-001.md`
- Link: `[BRD-001](../BRD/BRD-001.md#BRD-001)`
**Anchor Validation**:
- Markdown: `# BRD-001` → anchor `#BRD-001`
- YAML: `id: ib_gateway_connection_service` → anchor `#ib_gateway_connection_service`
- Feature: `Scenario: User connects to IB Gateway` → anchor varies
**Failure Examples**:
- Link: `[SPEC-001](../SPEC/SPEC-001.yaml)` → File not found
- Link: `[BRD-001](../BRD/BRD-001.md#BRD-002)` → Anchor mismatch
### Step 5: Generate Bidirectional Consistency from Tags
**Logic - Tag-Based Approach**:
- Extract tags from code and documentation
- Build forward matrix: Requirements → Implementing files
- Build reverse matrix: Files → Requirements
- Auto-generate bidirectional traceability matrices
- Validate tag references against actual documents
**Forward Matrix (BRD → Code)**:
```markdown
| Requirement | Implementing Files | Status |
|-------------|-------------------|--------|
| BRD-001:FR-001 | src/ibmcp/gateway/connection_service.py:15 | ✓ Complete |
| BRD-001:FR-002 | src/ibmcp/gateway/connection_service.py:15 | ✓ Complete |
| BRD-001:FR-030 | src/ibmcp/services/account_service.py:12 | ⚠️ In Progress |
```
**Reverse Matrix (Code → BRD)**:
```markdown
| Source File | BRD Requirements | Implementation Status |
|-------------|------------------|---------------------|
| src/ibmcp/gateway/connection_service.py | FR-001, FR-002, NFR-010 | Complete |
| src/ibmcp/services/account_service.py | FR-030, FR-031, NFR-006 | In Progress |
```
**Traditional Section 7 Validation** (Optional):
- For each A→B link in document A, verify B→A exists in document B
- Check upstream/downstream symmetry
- Detect missing reverse references
- Calculate consistency score: (matched pairs / total links) × 100%
**Scoring**:
- Target: ≥95% consistency
- Warning: 90-94% consistency
- Failure: <90% consistency
**Note:** Matrices are auto-generated from tags. Manual Section 7 is optional when using tag-based approach.
### Step 6: Calculate Coverage Metrics
**Metrics**:
- Count artifacts with complete traceability sections
- Calculate: (artifacts with Section 7 / total artifacts) × 100%
- Identify orphaned artifacts (no upstream/downstream links)
- Report coverage by artifact type
**Coverage Requirements**:
- Section 7 exists
- At least one upstream source listed (except BRD)
- Downstream artifacts identified or "To Be Created" noted
**Orphan Detection**:
- Root artifacts: BRD can have no upstream (business-driven)
- Leaf artifacts: IMPL can have no downstream (code is endpoint)
- Warning: REQ with no upstream (should link to BRD/PRD/EARS)
- Warning: SPEC with no downstream (should generate IMPL)
### Step 7: Generate Validation Report
**Report Sections**:
1. **Summary**: Pass/fail, coverage %, consistency score
2. **Broken Links**: File:line references with error details
3. **Missing Traceability**: Artifacts without Section 7
4. **Bidirectional Gaps**: A→B exists but B→A missing
5. **Orphaned Artifacts**: No upstream or downstream links
6. **Suggested Fixes**: Auto-fix commands or manual steps
7. **Coverage by Type**: Table with metrics per artifact type
**Report Format**:
- Markdown: Human-readable with tables and emojis
- JSON: Machine-readable for CI/CD integration
- Text: Plain text for console output
### Step 8: Auto-Fix Broken Links (if auto_fix=true)
**Actions**:
1. Create backup before modifications: `docs_backup_YYYYMMDD_HHMMSS.tar.gz`
2. Update document revision history (version bump, changelog)
3. Add missing downstream references to upstream documents
4. Fix relative path errors (../../ corrections)
5. Suggest new traceability entries based on filename patterns
**Safety Measures**:
- Backup creation mandatory before any changes
- Dry-run mode available for preview
- Rollback command provided in report
- Modification log generated
**Backup Command**:
```bash
cd {project_root}/docs
tar -czf ../backups/docs_backup_$(date +%Y%m%d_%H%M%S).tar.gz .
```
## Validation Checks
### ID Format Check
**Compliance**:
- Format: `TYPE-XXX` or `TYPE-XXX-YY`
- H1 header: Contains full document ID
- Zero-padding: 3 digits minimum (001, not 1)
- No collisions: Each XXX unique per type
**Regex Pattern**: `^(BRD|PRD|EARS|BDD|ADR|SYS|REQ|IMPL|CTR|SPEC|TASKS)-\d{3}(-\d{2})?
trace-check | AY CLAUDE
**Failure Examples**:
- `BRD-9` → Should be `BRD-009`
- `SPEC-1` → Should be `SPEC-001`
- `REQ-042-1` → Should be `REQ-042-01`
### Link Resolution Check
**Tests**:
- File exists: Path resolves to valid file
- Extension correct: .md, .yaml, .feature as expected
- Relative path: Correct from source file location
- Anchor exists: `#anchor` found in target file
**Failure Examples**:
- `[SPEC-001](../SPEC/SPEC-001.yaml)` → File not found
- `[BRD-001](../../BRD/BRD-001.md#BRD-001)` → Wrong path depth
- `[REQ-015](../REQ/REQ-015.md#REQ-015)` → File exists but anchor missing
### Anchor Validation Check
**Anchor Creation Rules**:
- Markdown: `# {ID}` → anchor `#{ID}`
- YAML: `id: {snake_case_name}` → anchor `#{snake_case_name}`
- Feature: `Scenario: {title}` → anchor varies by parser
**Validation**:
- Extract anchor from link: `[ID](path#anchor)`
- Parse target file for anchor existence
- Verify anchor format matches file type
**Failure Examples**:
- Link: `[SPEC-001](../SPEC/SPEC-001.yaml#SPEC-001)` → YAML has `id:` field, not H1
- Link: `[BDD-001](../BDD/BDD-001.feature#ib-gateway-connection)` → Scenario title mismatch
### Bidirectional Consistency Check
**Logic**:
- Forward exists: A→B link in document A Section 7.2
- Reverse exists: B→A link in document B Section 7.1
- Symmetry: Both directions present
**Scoring**: (matched pairs / total links) × 100%
**Failure Examples**:
- SPEC-001→BRD-001 exists, but BRD-001→SPEC-001 missing (50% consistency for this pair)
- BRD-001→PRD-001 exists, PRD-001→BRD-001 exists (100% consistency)
### Coverage Check
**Requirements**:
- Section 7 "Traceability"