adr

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 ga

---

*Content truncated.*