ADR Code Traceability

When to Use This Skill

• Creating new files as part of an ADR implementation
• Documenting non-obvious implementation choices
• User mentions "ADR traceability", "code reference", "document decision"
• Adding decision context to code during

  /itp:go

  Phase 1

Quick Reference

Reference Format

ADR: {adr-id}

ADR: 2025-12-01-my-feature

/docs/adr/2025-12-01-my-feature.md

Language Patterns (Summary)

"""...\n\nADR: {adr-id}\n"""

# ADR: {adr-id} - reason

/** ... \n * @see ADR: {adr-id} */

// ADR: {adr-id} - reason

//! ...\n//! ADR: {adr-id}

// ADR: {adr-id} - reason

// Package ... \n// ADR: {adr-id}

// ADR: {adr-id} - reason

Placement Decision Tree

Is this a NEW file created by the ADR?
├── Yes → Add reference in file header
└── No → Is the change non-obvious?
    ├── Yes → Add inline comment with reason
    └── No → Skip ADR reference

Examples

New File (Python)

"""
Redis cache adapter for session management.

ADR: 2025-12-01-redis-session-cache
"""

class RedisSessionCache:
    ...

Inline Comment (TypeScript)

// ADR: 2025-12-01-rate-limiting - Using token bucket over sliding window
// for better burst handling in our use case
const rateLimiter = new TokenBucketLimiter({ rate: 100, burst: 20 });

Do NOT Add References For

• Every line touched (only where traceability adds value)
• Trivial changes (formatting, typo fixes)
• Standard patterns (well-known idioms)
• Test files (unless test approach is an ADR decision)

Reference Documentation

• Language Patterns - Python, TS, Rust, Go patterns
• Placement Guidelines - When and where to add

Troubleshooting