# TRACES Quick Reference Guide

## What are TRACES?

TRACES are requirement identifiers embedded in code comments to track which requirements are implemented where.

Format: `// TRACES: UR-001, UR-002 | DR-003`

## Quick Examples

### TypeScript

    // TRACES: UR-005, UR-026 | DR-029
    export function handlePlayback() { }

    /**
     * Resume playback from saved position
     * TRACES: UR-019 | DR-022
     */
    export async function resumePlayback(itemId: string) { }

### Svelte

    <!-- TRACES: UR-007, UR-008 | DR-007 -->
    <script>
      export let items = [];
    </script>

### Rust

    #![allow(unused)]
    fn main() {
    /// TRACES: UR-005 | DR-001
    pub enum PlayerState { ... }

    #[test]
    fn test_queue_next() {
        // TRACES: UR-005 | DR-005 | UT-003
    }
    }

## Requirement Types

Type | Meaning | Example
--- | --- | ---
UR | User Requirement | UR-005: Control media playback
IR | Integration Requirement | IR-003: LibMPV integration
DR | Development Requirement | DR-001: Player state machine
JA | Jellyfin API Requirement | JA-007: Get playback info
UT | Unit Test | UT-001: Player state transitions
IT | Integration Test | IT-003: Audio playback via libmpv

## Where to Find Requirements

1. User Requirements (UR): requirements.md
2. Integration Requirements (IR): requirements.md
3. Development Requirements (DR): requirements.md
4. Jellyfin API (JA): requirements.md

## How to Add TRACES

### Step 1: Find the Requirement

Look up the requirement in README.md or the traceability matrix.

Example: `UR-005: Control media playback (pause, play, skip, scrub)`

### Step 2: Add Comment

Add TRACES comment at the top of the function/type/module:

    // TRACES: UR-005
    export async function playMedia(itemId: string) {
      // Implementation
    }

### Step 3: Run Extraction

Verify the trace is captured:

    bun run traces:json | jq '.requirements | keys | grep "UR-005"'

## Common Patterns

### Single Requirement

    // TRACES: UR-005
    function handlePlay() { }

### Multiple Requirements, Same Type

    // TRACES: UR-005, UR-026, UR-019
    function handlePlaybackState() { }

### Multiple Types

    // TRACES: UR-005, UR-026 | DR-029
    function autoplayNextEpisode() { }

### Test Coverage

    // TRACES: UR-005 | UT-001
    #[test]
    fn test_player_state_transition() { }

### Modules/Files

    /**
     * Player event handling
     * TRACES: UR-005, UR-019, UR-023 | DR-001, DR-028
     */

## Validation

### Check Your Changes

    # View current coverage
    bun run traces:json | jq '.byType'

    # Generate full report
    bun run traces:markdown

    # Check specific requirement
    bun run traces:json | jq '.requirements."UR-005"'

### Before Committing

1. Ensure all new code has TRACES
2. Format is correct: `// TRACES: ...`
3. Requirements exist in `docs/requirements.md` — `bun run traces:validate`
4. No typos in requirement IDs (same command catches them)

## CI/CD Validation

The workflow automatically checks:

- ✅ Coverage stays >= 88% (a ratchet — raise it, never lower it)
- ✅ Every traced ID is defined in `docs/requirements.md`
- ✅ New files have TRACES
- ✅ JSON format is valid
- ✅ Reports are generated

See traceability-ci.md for details.

## Tips & Tricks

### Find Related Code

    # Find all code tracing to UR-005
    bun run traces:json | jq '.requirements."UR-005"'

    # List all tests
    bun run traces:json | jq '.requirements | keys | map(select(startswith("UT")))'

### Update Your Editor

VS Code:

    {
      "editor.wordBasedSuggestions": false,
      "editor.suggest.custom": [
        {
          "name": "TRACES Format",
          "insertText": "// TRACES: $1",
          "insertTextRules": "InsertAsSnippet"
        }
      ]
    }

### Find Untraced Code

    # Files modified without TRACES
    git diff --name-only | xargs grep -L "TRACES:" | head -10

## FAQ

Q: Do I need TRACES on every function? A: Only for code that implements requirements. Internal helpers don't need TRACES.

Q: Can I use TRACES on multiple related functions? A: Yes! Add at the file/module level or on individual functions.

Q: What if code doesn't relate to any requirement? A: Leave it untraced. TRACES are for requirement-driven development.

Q: How often should I regenerate reports? A: Automatically on push (CI/CD). Manually after changes: `bun run traces:markdown`

Q: Can I trace to requirements that aren't implemented yet? A: Yes! TRACES show your implementation plan.

## See Also

- Full Traceability Matrix
- CI/CD Pipeline Guide
- Requirements Specification
- Extraction Script

Quick Start:

1. Add `// TRACES: UR-XXX` to new code
2. Run `bun run traces:markdown`
3. Check `docs/traceability.md`
4. Submit PR - workflow validates automatically!