ADR-Skill: Architecture Decision Record Management

Overview

This skill enables systematic creation, maintenance, and enforcement of Architecture Decision Records (ADRs) for the OTGW-firmware project. ADRs document significant architectural choices along with their context, alternatives considered, and consequences. They serve as living documentation to help current and future developers understand why the system is built the way it is.

When to Use

Automatic Trigger Scenarios

Use this skill automatically when:

• Code review or PR analysis - Verify changes align with existing ADRs
• CI/CD automation review - Enforce architectural compliance
• Major code changes - Check if new ADR is needed
• Architecture planning - Document important decisions before implementation
• Refactoring proposals - Validate against existing decisions or create new ADR

Explicit User Requests

Use this skill when user mentions:

• "Create an ADR"
• "Document this decision"
• "Architecture decision"
• "Why did we choose..."
• "Alternatives considered"
• "Document my choice"

Decision Triggers

Create a new ADR when making a decision that:

• Has long-term impact on architecture
• Affects multiple components or modules
• Involves trade-offs between alternatives
• Constrains future development choices
• Addresses a significant technical challenge
• Changes existing architectural patterns
• Requires human decision that should be preserved

Do NOT Create ADR For

• Bug fixes that don't change architecture
• Code refactoring maintaining same structure
• Configuration changes
• Documentation updates (non-architectural)
• Minor feature additions within existing patterns
• Temporary workarounds or experiments

---

Initial Codebase Analysis

First-Time Use: Discovering Undocumented Decisions

IMPORTANT: On first use or when introducing this skill to an existing codebase, perform a comprehensive architectural analysis to identify and document existing but undocumented decisions.

Analysis Workflow

Step 1: Identify Architectural Patterns

# Areas to analyze:
1. Platform choices (ESP8266, Arduino, frameworks)
2. Memory management patterns (static buffers, PROGMEM)
3. Network architecture (protocols, security models)
4. Integration patterns (MQTT, APIs, WebSocket)
5. Core system design (timers, scheduling, persistence)
6. Hardware interfaces (sensors, watchdog, GPIO)
7. Build and development tools

Step 2: Ask Critical Questions

For each pattern discovered:
- WHY was this approach chosen? (context, constraints)
- WHAT alternatives exist? (at least 2-3 viable options)
- WHY were alternatives rejected? (specific technical reasons)
- WHAT are the consequences? (benefits, costs, risks)
- HOW is this implemented? (code examples, key files)
- WHEN was this decided? (estimate if unknown)

Step 3: Generate ADRs Systematically

For each undocumented architectural decision:
1. Use the explore agent to understand the pattern
2. Review code, comments, git history for context
3. Identify constraints (memory, performance, compatibility)
4. Research alternatives (even if obvious)
5. Document consequences (positive AND negative)
6. Create ADR with Status: Accepted (since implemented)
7. Link to actual implementation (files, commits)

Step 4: Prioritize Documentation

Start with foundational decisions that:
- Affect multiple components
- Constrain future choices
- Are non-obvious or counterintuitive
- Have significant trade-offs
- Are frequently questioned

Initial Analysis Prompts

Trigger codebase analysis:

"Analyze this codebase to identify undocumented architectural decisions"
"Generate ADRs for existing architectural patterns in this codebase"
"What architectural decisions should be documented in this project?"

For specific areas:

"Identify and document memory management architectural decisions"
"What network architecture decisions are undocumented?"
"Analyze platform choices and create ADRs"

Example: Discovering ADR-009 (PROGMEM)

Pattern discovered: String literals use F() and PSTR() macros throughout codebase

Critical questions:

• WHY? → ESP8266 has only 40KB RAM; string literals waste 5-8KB
• Alternatives? → Keep in RAM, external RAM, compressed strings, string table
• Why rejected? → RAM too limited, hardware changes, complexity, doesn't solve problem
• Consequences? → +5-8KB heap (positive), verbose code (negative), flash slower than RAM (accepted)

Result: ADR-009 documents mandatory PROGMEM usage with clear rationale

---

ADR Principles

The Golden Rules

1. One Decision Per ADR - Each ADR captures a single architectural choice
2. Immutable History - Never modify accepted ADRs; supersede with new ones instead
3. Context is King - Explain WHY the decision was made, not just WHAT
4. Alternatives Matter - Document what was considered but rejected
5. Human Decisions Marked - Clearly indicate when decision came from user/stakeholder
6. Critical Analysis - Be thorough, question assumptions, document trade-offs honestly
7. Understandable Language - Write for developers unfamiliar with the decision; avoid unexplained jargon

ADR Best Practices

✓ Write for future developers who weren't there
✓ Include code examples and diagrams
✓ Reference related ADRs
✓ Use clear, simple language
✓ Document constraints that drove the decision
✓ Explain consequences (positive and negative)
✓ Link to implementation (files, PRs, commits)
✓ Be critical - question the decision, document risks
✓ Provide specific evidence (measurements, benchmarks)
✓ Explain technical terms on first use

✗ Don't use jargon without explanation
✗ Don't assume reader knows the context
✗ Don't skip alternatives (even obvious ones)
✗ Don't make assumptions unstated
✗ Don't forget to update status when superseding
✗ Don't be vague ("it's better", "improves performance")
✗ Don't skip negative consequences
✗ Don't write marketing copy - be honest about trade-offs

---

ADR Template

Use this comprehensive template for all new ADRs:

# ADR-XXX: [Concise Decision Title]

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date:** YYYY-MM-DD
**Decision Maker:** [Copilot Agent | User: Name | Team Discussion]

## Context

### Problem Statement
[What problem are we solving? What is the situation or challenge?]

### Background
[Relevant history, current state, or technical context]

### Constraints
[What constraints apply? Hardware, memory, security, compatibility, budget, timeline?]

### Stakeholders
[Who is affected by this decision? Users, developers, operations, integrations?]

## Decision

[Clear statement of the choice made and rationale]

### Why This Choice
[Explain reasoning behind the decision]

### Implementation Summary
[High-level description of how this will be implemented]

## Alternatives Considered

### Alternative 1: [Name]
**Description:** [What is this alternative?]

**Pros:**
- Benefit 1
- Benefit 2

**Cons:**
- Drawback 1
- Drawback 2

**Why Not Chosen:** [Clear explanation]

### Alternative 2: [Name]
[Repeat structure for each alternative]

[Include at least 2-3 alternatives. If none exist, explain why this is the only viable option.]

## Consequences

### Positive
- **[Benefit Category]:** Specific benefit
- **[Another Category]:** Another benefit

### Negative
- **[Cost/Limitation]:** Specific drawback
- **[Trade-off]:** What we're giving up

### Risks & Mitigation
- **Risk:** [Description]
  **Mitigation:** [How we address this]

### Impact Areas
- **Performance:** [Impact on system performance]
- **Maintainability:** [Impact on code maintenance]
- **Security:** [Security implications]
- **Scalability:** [Scaling implications]
- **Developer Experience:** [Impact on development]

## Implementation Notes

### Key Files/Modules Affected
- `path/to/file.ext` - [Brief description of changes]
- `another/file.ext` - [Brief description]

### Code Examples

```language
// Example showing how this decision is implemented
function example() {
  // Demonstrate the pattern
}

Migration Required

[If this changes existing code, describe migration steps. Otherwise state "None."]

Verification

How to Verify This Decision

[How can a developer verify this decision is being followed?]

Testing Requirements

[What testing ensures this decision is properly implemented?]

Monitoring/Metrics

[What metrics indicate this decision is working?]

Related Decisions

• Depends on: ADR-XXX ([Title])
• Related to: ADR-XXX ([Title])
• Supersedes: ADR-XXX ([Title]) - if applicable
• Superseded by: ADR-XXX ([Title]) - if applicable

References

• [Link to relevant documentation]
• [Link to code examples]
• [Link to related issues/PRs]
• [External resources]
• [Standards or specifications]

Timeline

• YYYY-MM-DD: Initial proposal
• YYYY-MM-DD: Discussion/review
• YYYY-MM-DD: Accepted
• YYYY-MM-DD: Implemented
• YYYY-MM-DD: Superseded (if applicable)

---

Metadata:

• ADR Number: XXX
• Status: [Current status]
• Category: [Platform/Memory/Network/Integration/etc.]
• Impact: [High/Medium/Low]

---

## Naming Convention

### ADR File Naming

Format: ADR-XXX-short-descriptive-title.md

Where:

• XXX = Zero-padded sequential number (001, 002, ..., 029, 030, etc.)
• short-descriptive-title = Kebab-case description

Examples: ✓ ADR-001-esp8266-platform-selection.md ✓ ADR-009-progmem-string-literals.md ✓ ADR-029-simple-xhr-ota-flash.md

✗ ADR-1-esp8266.md (not zero-padded) ✗ ADR-030-This_Is_Wrong.md (not kebab-case) ✗ adr-030-lowercase-adr.md (ADR prefix must be uppercase)

### Number Assignment

- Sequential numbering starting from 001
- Check `docs/adr/` for highest number and increment
- Don't reuse numbers from deprecated/superseded ADRs
- Don't leave gaps in numbering

---

## ADR Categories

Group ADRs by architectural domain for easier navigation:

- **Platform & Build System** - Platform choice, build tools, frameworks
- **Memory Management** - RAM optimization, buffer strategies, PROGMEM
- **Network & Security** - Protocols, encryption, authentication
- **Integration & Communication** - APIs, MQTT, WebSocket
- **System Architecture** - Core patterns, scheduling, persistence
- **Hardware & Reliability** - Hardware interface, watchdog, sensors
- **Development & Build** - Developer tools, CI/CD, testing
- **Core Services** - Time management, queuing, configuration
- **Features & Extensions** - Specific features, sensor integration
- **Browser & Client** - Frontend, browser compatibility, UX
- **OTA & Updates** - Firmware updates, version management

---

## ADR Workflow

### 1. Before Making Architectural Changes

```bash
# Step 1: Review existing ADRs
- Read docs/adr/README.md for navigation
- Search for related decisions
- Check if change conflicts with existing ADRs
- Understand architectural constraints

# Step 2: Determine if new ADR needed
- Will this have long-term impact?
- Does it affect multiple components?
- Are there multiple alternatives?
- Will future developers need context?

# Step 3: If ADR needed, draft it
- Use the template above
- Fill in all sections thoughtfully
- Include code examples
- Document alternatives thoroughly

2. During Implementation

# Step 1: Create ADR with Status: Proposed
- Get next ADR number
- Write comprehensive ADR
- Include decision maker (Copilot Agent or User: Name)

# Step 2: Reference ADR in code
- Add comments linking to ADR
- Example: // See ADR-030 for why we use this pattern

# Step 3: Implement according to decision
- Follow patterns established in ADR
- Ensure code aligns with decision
- Implement mitigation for identified risks

3. After Implementation

# Step 1: Update ADR status to Accepted
- Change Status: Proposed → Accepted
- Add implementation date to timeline
- Link to PR/commit that implemented it

# Step 2: Update docs/adr/README.md
- Add entry to ADR index
- Categorize appropriately
- Update reference counts if applicable

# Step 3: Store memory (if using Copilot)
- Store key facts for future reference
- Include ADR number in citations

4. When Superseding an ADR

# Step 1: Create new ADR
- Write new ADR explaining change
- Reference original ADR
- Explain why change needed

# Step 2: Update old ADR
- Change status to "Superseded by ADR-XXX"
- Do NOT delete or modify decision/context
- Add superseded date to timeline

# Step 3: Update README
- Update both ADRs in index
- Note the supersession relationship

---

Code Review Integration

During Code Reviews

Automatic Checks:

1. Do changes violate any existing ADRs?
2. Do changes require a new ADR?
3. Are ADR references in code accurate?
4. Is ADR status up to date?

Example Review Comments:

✗ "This change violates ADR-004 (Static Buffer Allocation).
   The String class should not be used here."

✓ "This change aligns with ADR-007 (Timer-Based Scheduling).
   Good use of DECLARE_TIMER_SEC macro."

? "This introduces a new architectural pattern.
   Please create an ADR documenting the decision."

! "ADR-029 is referenced but hasn't been updated to Accepted status.
   Please update the status since this is now implemented."

PR Checklist with ADRs

## ADR Compliance Checklist

- [ ] Changes reviewed against existing ADRs
- [ ] No violations of architectural decisions
- [ ] New ADR created if needed (Status: Proposed)
- [ ] ADR status updated if implementing existing ADR
- [ ] Code comments reference relevant ADRs
- [ ] docs/adr/README.md updated if new ADR added

---

CI/CD Integration

Pre-Commit Checks

# Check ADR compliance
python evaluate.py  # Includes ADR pattern enforcement

# Verify ADR references are valid
grep -r "ADR-[0-9]" src/ | while read line; do
  # Extract ADR number and verify file exists
  # Report broken references
done

# Check for architectural pattern violations
# (e.g., String usage, missing PROGMEM, etc.)

PR Automation

# .github/workflows/adr-check.yml
name: ADR Compliance Check

on: [pull_request]

jobs:
  adr-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Check ADR compliance
        run: |
          # Run automated checks
          # Verify no ADR violations
          # Check if new ADRs needed

      - name: Comment on PR
        if: violations found
        # Post comment suggesting ADR review

---

Human Decision Documentation

When User Makes Architectural Choice

If a user explicitly makes an architectural decision, document it clearly:

# ADR-XXX: [Title]

**Status:** Accepted
**Date:** YYYY-MM-DD
**Decision Maker:** User: [Name/Role]  ← IMPORTANT: Mark as human decision

## Context
[User's problem or request]

## Decision
**User Decision:** [What the user chose]

The user explicitly chose [X] over [Y] because [reason given].

## Alternatives Considered
[What was presented to the user]

### Alternative 1: [Option presented]
**User Feedback:** [User's reasoning for/against]

### Alternative 2: [Option presented]
**User Feedback:** [User's reasoning for/against]

## Rationale
**User's Stated Reasons:**
- Reason 1
- Reason 2

**Technical Context:**
[Agent's analysis of the decision's technical implications]

Example Human Decision ADR

# ADR-030: Use PostgreSQL for Sensor Data Storage

**Status:** Accepted
**Date:** 2026-02-06
**Decision Maker:** User: Rob van den Breemen

## Context
User requested evaluation of database options for storing sensor historical data.

## Decision
**User Decision:** Use PostgreSQL instead of SQLite

The user explicitly chose PostgreSQL after being presented with both options,
citing need for multi-client access and superior analytics capabilities.

## Alternatives Considered

### Alternative 1: SQLite
**Pros:** Lightweight, embedded, no server needed
**Cons:** Single writer limitation
**User Feedback:** "Need multiple Home Assistant instances to query simultaneously"

### Alternative 2: PostgreSQL
**Pros:** Multi-client, powerful queries, excellent HA integration
**Cons:** Requires separate server, more complex setup
**User Feedback:** "Worth the complexity for analytics and flexibility"

## Rationale
**User's Stated Reasons:**
- Need concurrent access from multiple HA instances
- Plan to use TimescaleDB extension for time-series data
- Want to run complex queries for energy analytics
- Already running PostgreSQL for other home automation

**Technical Context:**
This decision means we'll implement a RESTful API for sensor data
instead of direct database access from the firmware.

---

ADR Index Management

Maintaining docs/adr/README.md

The README is the navigation hub for all ADRs. Keep it up to date:

Required Sections:

1. What are ADRs? - Explanation for new readers
2. Quick Navigation - By topic with counts
3. ADR Index - Full categorized list
4. ADR Template - Link or embed template
5. Key Architectural Themes - Cross-cutting concerns
6. Architectural Dependencies - Which ADRs depend on which
7. When to Create an ADR - Guidance
8. Superseding ADRs - How to handle changes
9. Resources - Links to best practices

Update Process:

# When adding new ADR:
1. Add entry under appropriate category
2. Update category count
3. Update "Foundational ADRs" if highly referenced
4. Update "Decision Timeline" if appropriate
5. Add to "Related Decisions" in other ADRs

---

Code Examples in ADRs

Good ADR Code Examples

Principle: Show, don't just tell

## Implementation Notes

### WRONG: No example
Use PROGMEM for string literals.

### RIGHT: Clear example
```cpp
// WRONG - String literal wastes RAM
DebugTln("Starting WiFi");

// CORRECT - F() macro stores in flash
DebugTln(F("Starting WiFi"));

// WRONG - strcmp on PROGMEM
strcmp(value, "ON");

// CORRECT - strcmp_P for PROGMEM
strcmp_P(value, PSTR("ON"));

### Include Diagrams When Helpful

```markdown
## Implementation Notes

### Architecture Diagram

[WebSocket Client] ─── ws:// ───> [ESP8266:81] │ ├─> [Buffer] (1KB) │ │ │ ▼ [HTTP Client] ──── http:// ─> [ESP8266:80] [Queue] │ │ └──────┴─> [PIC Serial]

### Data Flow

User Request → REST API → Command Queue → Serial → PIC → OpenTherm Boiler ↓ ↓ ↓ ↓ Validate JSON Parse Dedup Check Protocol

---

ADR Metrics & Maintenance

Health Indicators

Healthy ADR Repository:

• ✓ All ADRs have clear status
• ✓ Superseded ADRs reference replacement
• ✓ Code references match existing ADRs
• ✓ README index is up to date
• ✓ Recent ADRs include implementation dates
• ✓ Each ADR has at least 2 alternatives documented

Needs Attention:

• ✗ Multiple ADRs with "Proposed" status for >30 days
• ✗ ADR numbers with gaps
• ✗ Code comments reference non-existent ADRs
• ✗ ADRs without alternatives section
• ✗ README categories don't match actual ADRs

Periodic Review

Quarterly ADR Review:

# Review checklist
1. Are any "Proposed" ADRs abandoned? (Mark deprecated)
2. Are any "Accepted" ADRs being violated? (Update enforcement)
3. Do new patterns need ADRs? (Create them)
4. Are superseded ADRs properly linked? (Verify)
5. Is README accurately reflecting current state? (Update)

---

Integration with Copilot Instructions

How This Skill Connects to .github/copilot-instructions.md

The copilot instructions file references ADRs but doesn't duplicate them:

In copilot-instructions.md:

## Architecture Decision Records (ADRs)

**IMPORTANT:** This project maintains ADRs documenting key architectural choices.

- **ADR Index:** `docs/adr/README.md`
- **Before making changes:** Review relevant ADRs
- **ADR Compliance:** Follow patterns in ADRs
- **Creating ADRs:** Use the ADR-skill for guidance

**Key Decisions:**
- ADR-003: HTTP-Only (no HTTPS/WSS) ← Link, don't duplicate
- ADR-004: Static Buffer Allocation ← Link, don't duplicate
- ADR-009: PROGMEM String Literals ← Link, don't duplicate

In this skill:

• Full ADR creation process
• Templates and examples
• Decision guidance
• Workflow details

Division of Responsibility:

• Copilot Instructions: Quick reference, links to ADRs, enforcement rules
• ADR-Skill: Comprehensive ADR creation and management process
• Individual ADRs: Detailed context, decisions, and consequences

---

Examples from OTGW-Firmware

Example 1: Memory Management ADR (ADR-004)

What makes it good:

• Clear problem statement (heap fragmentation)
• Specific measurements (3,130-3,730 bytes saved)
• Multiple alternatives with detailed pros/cons
• Implementation patterns with code examples
• Risk mitigation strategies
• References to evaluation framework

Key Sections:

## Consequences

### Positive
- **Stability:** Eliminates most out-of-memory crashes
- **Scalability:** Can add features without exhausting RAM
- **Measurable:** RAM usage is stable and predictable

### Negative
- **Code verbosity:** Requires buffer size management
  - Accepted: Necessary trade-off for stability

Example 2: Protocol Decision ADR (ADR-003)

What makes it good:

• Explains why not HTTPS (memory constraints)
• Documents security model (local network only)
• Lists 4 rejected alternatives with clear reasoning
• Includes documentation requirements
• References related ADRs (dependencies)

Key Sections:

## Alternatives Considered

### Alternative 1: HTTPS with Self-Signed Certificates
**Cons:**
- Requires 20-30KB RAM for TLS handshake (50-75% of available heap)
- OTA updates may fail due to insufficient memory

**Why not chosen:** Memory constraints prohibitive

Example 3: Feature ADR (ADR-029)

What makes it good:

• Quantifies improvement (68.5% code reduction)
• Shows before/after code comparison
• Explains Safari-specific bug being fixed
• Links to the problem it solves (ADR-025)
• Includes migration path

---

Quick Reference

ADR Creation Checklist

Creating a new ADR? Check these:

- [ ] Next sequential number assigned (check docs/adr/)
- [ ] Filename follows ADR-XXX-kebab-case-title.md format
- [ ] Status field present (Proposed/Accepted/etc.)
- [ ] Date field present (YYYY-MM-DD)
- [ ] Decision Maker identified (Copilot Agent or User: Name)
- [ ] Context section explains problem clearly
- [ ] At least 2-3 alternatives documented
- [ ] Pros and cons listed for each alternative
- [ ] "Why not chosen" for each rejected alternative
- [ ] Consequences section complete (positive, negative, risks)
- [ ] Code examples included (if applicable)
- [ ] Related ADRs referenced
- [ ] Implementation notes with affected files
- [ ] Added to docs/adr/README.md index
- [ ] Category assigned
- [ ] References/links included

Common ADR Mistakes to Avoid