spec-tracing

Specification Tracing

Specifications define WHAT the system does, not HOW. Every normative statement gets a unique ID that implementation and tests reference.

Paragraph ID Format

[SPEC-{section}.{paragraph}]

Examples:

• [SPEC-01.03] - Section 1, paragraph 3
• [SPEC-05.12] - Section 5, paragraph 12
• [SPEC-03.07a] - Section 3, paragraph 7, sub-item a

Specification Document Structure

# {Section Title}

## Overview

[SPEC-{NN}.01] This section defines {what this section covers}.

## {Subsection}

[SPEC-{NN}.02] {Normative statement using RFC 2119 language}.

[SPEC-{NN}.03] {Another normative statement}.

### {Sub-subsection}

[SPEC-{NN}.04] {Detailed requirement}.

> **Informative**: {Non-normative explanation or rationale}

RFC 2119 Keywords

Use precise requirement language:

Keyword	Meaning
MUST / SHALL	Absolute requirement
MUST NOT / SHALL NOT	Absolute prohibition
SHOULD / RECOMMENDED	Strong preference, exceptions allowed with justification
SHOULD NOT	Discouraged, exceptions allowed with justification
MAY / OPTIONAL	Truly optional

Implementation Traceability

In Source Code

Add trace comments linking implementation to spec:

// @trace SPEC-03.07 - Validates input length constraint
fn validate_length(input: &str) -> Result<(), Error> {
    // Implementation per SPEC-03.07
}

/**
 * @trace SPEC-05.12 - Handles authentication flow
 */
function authenticate(credentials: Credentials): Promise<Token> {
    // Implementation per SPEC-05.12
}

def process_request(req: Request) -> Response:
    """
    @trace SPEC-02.04 - Request processing pipeline
    """
    # Implementation per SPEC-02.04

In Tests

Reference spec paragraphs in test names and comments:

#[test]
// @trace SPEC-03.07
fn test_input_length_validation() {
    // Tests requirement from SPEC-03.07
}

describe('SPEC-05.12: Authentication', () => {
    it('should return token on valid credentials', () => {
        // @trace SPEC-05.12
    });
});

def test_request_processing_spec_02_04():
    """@trace SPEC-02.04"""
    # Tests requirement from SPEC-02.04

Coverage Verification

To verify spec coverage, check that every normative paragraph has:

1. At least one test with @trace SPEC-XX.YY marker
2. Implementation with corresponding @trace comment

Coverage Check Script Pattern

# Extract all spec paragraph IDs
grep -rhoE '\[SPEC-[0-9]+\.[0-9]+[a-z]?\]' docs/spec/ | sort -u > spec-ids.txt

# Extract all traced tests
grep -rhoE '@trace SPEC-[0-9]+\.[0-9]+[a-z]?' tests/ | \
    sed 's/@trace /[/' | sed 's/$/]/' | sort -u > test-traces.txt

# Find untested specs
comm -23 spec-ids.txt test-traces.txt > untested-specs.txt

Spec Modification Rules

1. New features: Add new paragraph IDs, never reuse deleted ones
2. Modifications: Update paragraph text, add version note
3. Deprecation: Mark as deprecated, don't delete (for traceability)
4. Breaking changes: Create new section, deprecate old

Version Notes

[SPEC-03.07] Input length MUST NOT exceed 1024 bytes.

> **History**: Changed from 512 bytes in v2.0. See ADR-0015.

Informative vs Normative Content

Type	Marker	Purpose	Tested?
Normative	[SPEC-XX.YY]	Requirements	Yes
Informative	Blockquote or "Note:"	Rationale, examples	No
Example	Code block	Illustration	Optional

Quick Reference

• Every MUST/SHALL/SHOULD gets a [SPEC-XX.YY] ID
• Implementation uses @trace SPEC-XX.YY comments
• Tests use @trace SPEC-XX.YY in name or docstring
• Coverage tooling verifies all specs have tests
• Never reuse deleted paragraph IDs