Adr Code Traceability

ADR Code Traceability

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

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

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)

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

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure. 2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

Skill: ADR Code Traceability

Language-Specific ADR Reference Patterns

Standard patterns for referencing ADRs in code across different programming languages.

Reference Format

Standard: ADR: {adr-id}

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

---

Python

New File (Module Header)

"""
Module description here.

ADR: 2025-12-01-my-feature
"""

import ...

Inline Comment

# ADR: 2025-12-01-my-feature - reason for this choice
result = some_operation()

Docstring Reference

def my_function():
    """
    Function description.

    ADR: 2025-12-01-my-feature
    """
    pass

---

TypeScript / JavaScript

New File (JSDoc Header)

/**
 * Module description here.
 *
 * @see ADR: 2025-12-01-my-feature
 */

import ...

Inline Comment

// ADR: 2025-12-01-my-feature - reason for this choice
const result = someOperation();

Class/Function JSDoc

/**
 * Class description.
 *
 * @see ADR: 2025-12-01-my-feature
 */
class MyClass {
  ...
}

---

Rust

New File (Module Documentation)

//! Module description here.
//!
//! ADR: 2025-12-01-my-feature

use ...;

Inline Comment

// ADR: 2025-12-01-my-feature - reason for this choice
let result = some_operation();

Doc Comment

/// Function description.
///
/// ADR: 2025-12-01-my-feature
fn my_function() {
    ...
}

---

Go

New File (Package Documentation)

// Package mypackage provides ...
//
// ADR: 2025-12-01-my-feature
package mypackage

import ...

Inline Comment

// ADR: 2025-12-01-my-feature - reason for this choice
result := someOperation()

Function Documentation

// MyFunction does something.
//
// ADR: 2025-12-01-my-feature
func MyFunction() {
    ...
}

---

Configuration Files

YAML/JSON Comments

# ADR: 2025-12-01-my-feature - configuration rationale
setting: value

Markdown Documents

<!-- ADR: 2025-12-01-my-feature -->

# Document Title

---

Quick Reference Table

Skill: ADR Code Traceability

ADR Reference Placement Guidelines

When and where to add ADR references in code for optimal traceability.

---

When to Add References

Always Add (File Headers)

Add ADR reference in file header for:

• New files created as part of the ADR implementation
• New modules/packages introduced by the ADR
• Configuration files with settings specific to the ADR

Selectively Add (Inline Comments)

Add inline ADR comments for:

• Non-obvious implementation choices - Why was this approach chosen?
• Workarounds or constraints - What limitation drove this decision?
• Breaking changes - What changed and why?
• Performance-critical code - Why was this optimization necessary?

Do NOT Add

Skip ADR references for:

• Every line touched - Only add where traceability adds value
• Trivial changes - Formatting, typo fixes, minor refactors
• Standard patterns - Well-known idioms that don't need explanation
• Test files - Unless the test approach itself is an ADR decision

---

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

---

File Header vs Inline Comment

---

Good vs Bad Examples

Good: File Header for New Module

"""
Redis cache adapter for session management.

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

class RedisSessionCache:
    ...

Good: Inline for Non-Obvious Choice

# ADR: 2025-12-01-rate-limiting - Using token bucket over sliding window
# for better burst handling in our use case
rate_limiter = TokenBucketLimiter(rate=100, burst=20)

Bad: Unnecessary Reference

# ADR: 2025-12-01-fix-typo  # ❌ Trivial change doesn't need ADR
name = "correct_spelling"

Bad: Every Line

# ADR: 2025-12-01-my-feature  # ❌ Too verbose
import os
# ADR: 2025-12-01-my-feature  # ❌ No value added
import sys

---

Traceability Value Test

Before adding an ADR reference, ask:

1. Would a future developer benefit from knowing why this exists? 2. Is the connection to the ADR non-obvious from context? 3. Does this code represent a deliberate decision vs standard practice?

If all answers are "No" → Skip the reference. If any answer is "Yes" → Add the reference.

---

Maintenance

When modifying code with ADR references:

• Keep reference if ADR still applies - Implementation evolved but decision stands
• Remove reference if ADR superseded - New ADR replaces the old decision
• Update reference if ADR amended - Point to the current version

ADR references should track the decision, not the implementation details.