ADR Code Traceability Skill

ADR Code Traceability

Add Architecture Decision Record references to code for decision traceability. Provides language-specific patterns and placement guidelines.

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}

Path Derivation: ADR: 2025-12-01-my-feature → /docs/adr/2025-12-01-my-feature.md

Language Patterns (Summary)

| Language | New File Header | Inline Comment | | ---------- | ------------------------------------ | --------------------------- | | Python | """...\n\nADR: {adr-id}\n""" | # ADR: {adr-id} - reason | | TypeScript | /** ... \n * @see ADR: {adr-id} */ | // ADR: {adr-id} - reason | | Rust | //! ...\n//! ADR: {adr-id} | // ADR: {adr-id} - reason | | Go | // Package ... \n// ADR: {adr-id} | // ADR: {adr-id} - reason |

See Language Patterns for complete examples.

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

See Placement Guidelines for detailed guidance.

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

| Issue | Cause | Solution | | ---------------------- | ---------------------- | ----------------------------------------- | | ADR not found | Wrong path format | Use relative path from repo root | | Reference not showing | Comment syntax wrong | Check language-specific comment format | | Too many references | Over-documenting | Only add where traceability adds value | | Outdated ADR link | ADR was renamed | Update path to match current ADR filename | | Hook reminder annoying | No ADR for this change | Add inline ADR comment or create new ADR |

Agent Skills: ADR Code Traceability

Install this agent skill to your local

Skill Files