jellytau/docs/traces-quick-ref.md

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

/// 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): README.md
2. Integration Requirements (IR): README.md
3. Development Requirements (DR): README.md
4. Jellyfin API (JA): README.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 README.md
4. No typos in requirement IDs

CI/CD Validation

The workflow automatically checks:

• ✅ Coverage stays >= 50%
• ✅ 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!