{
  "schema_version": 1,
  "skill_name": "adr-authoring",
  "evals": [
    {
      "id": "adr-authoring",
      "prompt": "We just decided to switch our service-to-service communication from synchronous REST calls to an event-driven model with a message broker. I need to record this as an architecture decision record so future engineers understand why. What should the ADR contain and how should I write it?",
      "expected_output": "An ADR following the standard structure: a status line (proposed, accepted, or superseded with the date and decider), the context that explains the forces and constraints at the time (the coupling pain, the scale trajectory, the team's operational constraints), the decision stated in one unambiguous sentence, the alternatives that were considered with the reasons they were rejected (synchronous REST with retries, a shared database change feed), the consequences of the decision split into positive and negative so the trade-off is visible (decoupling and independent scaling against the new operational burden of message ordering, delivery guarantees, and debugging async flows), and the compliance and follow-up items. The response explains what makes it durable: the context captures the reasoning so the decision survives personnel changes, the alternatives are recorded honestly, and the consequences include what the team must now do differently.",
      "assertions": [
        "The ADR contains status, context, decision, alternatives, and consequences sections",
        "The decision is stated in one unambiguous sentence",
        "Alternatives are recorded with the reasons they were rejected",
        "Consequences are split into positive and negative with the trade-off visible",
        "The context captures the reasoning so the decision survives personnel changes"
      ]
    },
    {
      "id": "template-selection",
      "prompt": "We are starting to write ADRs for a new project and I have seen many formats: the original Nygard format, MADR, and heavier enterprise templates. The team has different preferences. How do I choose a template, and should I even pick one?",
      "expected_output": "A template-selection approach that prioritizes consistency and the decision's needs over format loyalty: the response explains that the template catalog exists because decision contexts differ \u2014 the original Nygard format suits a focused technical decision, MADR adds structure for incremental updates, and heavier formats carry the governance fields larger organizations need \u2014 and prescribes picking one default for the org with the selection made on criteria: the depth of governance required, how the ADRs will be consumed (read by the team, audited by a governance board), and the update pattern (append-only records versus evolving documents). It recommends starting with a lightweight default and migrating to a heavier format only if the governance need appears, and it stresses that the bigger win is a fixed convention \u2014 one template, one naming scheme, one location \u2014 over the choice of which format, because consistency is what makes ADRs searchable and reliable.",
      "assertions": [
        "Template choice is tied to the decision context and governance need, not format loyalty",
        "The response compares Nygard, MADR, and heavier formats on concrete criteria",
        "A lightweight default with optional migration is recommended",
        "Consistency of convention is valued above the specific format choice",
        "The recommendation covers naming and location conventions"
      ]
    },
    {
      "id": "adr-lifecycle-governance",
      "prompt": "We have an ADR that was accepted, then partially reversed a year later, and now a proposal wants to replace it entirely. Our ADR folder is a flat list of files with no states and nobody knows what is actually in force. How do I manage the ADR lifecycle and status transitions?",
      "expected_output": "A lifecycle governance design that makes status the primary way to understand an ADR: the response defines the status model (proposed, accepted, superseded, deprecated, and rejected), the transition rules (an accepted ADR moves to superseded when a new ADR replaces it and links to the replacement; a partially reversed decision is recorded as a new decision or a revision rather than silently editing the original), and the practical mechanics: each ADR carries its status and date in the header, superseded ADRs link to their successor, and the folder has an index (a README or status table) showing what is currently in force. The response prescribes the workflow: decisions flow through review before acceptance, supersession is explicit with a reason, and the index is part of the review so the team can see the current architecture at a glance instead of reading every file.",
      "assertions": [
        "The status model covers proposed, accepted, superseded, deprecated, and rejected with transition rules",
        "Superseded ADRs link to their replacement and record the reason",
        "Partial reversals are recorded as new decisions or revisions rather than silent edits",
        "An index shows what is currently in force",
        "The review workflow keeps statuses and the index current"
      ]
    },
    {
      "id": "adr-quality-review",
      "prompt": "I am reviewing ADRs before we accept them and I keep seeing the same problems: decisions with no alternatives, consequences that only list the positives, and context sections that describe the solution instead of the problem. What should my review checklist check?",
      "expected_output": "An ADR review checklist focused on the properties that make a decision durable: the response prescribes checking that the context describes the problem and forces, not the chosen solution; that the decision is a clear statement of what was decided and what was explicitly not decided; that alternatives are real alternatives that were seriously considered, with the rejection reasons recorded; that consequences include the negative and operational costs, not only benefits; and that the ADR records who decided, when, and under what constraints. It also covers the sustainability checks: whether the ADR would still make sense to a reader in two years who does not know the authors, whether the trade-offs are stated in terms that can be revisited when the context changes, and whether it leaves the team with follow-up items or open questions that should be tracked rather than hidden.",
      "assertions": [
        "The checklist verifies context describes the problem, not the chosen solution",
        "Alternatives are verified as seriously considered with rejection reasons",
        "Consequences must include negatives and operational costs",
        "The ADR records who decided, when, and under what constraints",
        "The review assesses durability: would it make sense in two years, and are follow-ups tracked"
      ]
    },
    {
      "id": "fitness-functions",
      "prompt": "We have an accepted ADR mandating that new services must use our standard logging format, but a year later half the services violate it and nobody noticed until an incident. I want the architecture rules enforced automatically. How do I turn ADRs into checkable constraints?",
      "expected_output": "A fitness-function approach that turns ADR decisions into automated checks: the response explains the concept \u2014 a fitness function is an automated test or check that continuously validates an architectural characteristic, and the ADR maps to one or more functions (a check that scans service code or configuration for the standard logging setup, run in CI or as a periodic audit). It prescribes the workflow: for each ADR with a mechanical consequence, define the check, implement it in the project's test or CI layer, and attach it to the ADR record so the link between decision and enforcement is explicit. The response covers the boundary: not every decision is mechanically checkable (judgment calls stay in review), but anything with a detectable pattern should be checked, and the check must be part of the definition of done for new services, not a retrofit after incidents. It includes an example check shape for the logging standard.",
      "assertions": [
        "The fitness-function concept is explained as automated enforcement of architectural rules",
        "Each mechanical ADR consequence maps to a concrete check",
        "The ADR record links to its enforcement check",
        "The boundary between checkable and judgment-based decisions is stated",
        "Enforcement is part of definition of done, not a post-incident retrofit"
      ]
    },
    {
      "id": "fitness-function-record",
      "prompt": "An ADR says that asynchronous jobs must not publish customer data outside the approved region. Design the fitness-function record, including scope, cadence, evidence type, invocation, threshold rationale, owners, false-positive and false-negative controls, gaming risks, exception handling, review triggers, retirement, and the link back to the ADR.",
      "expected_output": "A reusable operational record that traces the ADR claim to a measurable regional-boundary characteristic and an observed evidence artifact. It chooses a bounded scenario or structural scope, explains why change-triggered checks are paired with runtime or scheduled evidence, defines a defensible pass condition and denominator, names decision and function owners, handles indeterminate results and time-boxed exceptions, identifies ways the metric could be gamed, and states review and retirement criteria.",
      "assertions": [
        "The record links an unambiguous ADR claim to a named architectural characteristic and observed evidence location",
        "Scope, cadence, invocation, evidence type, inputs, and missing-result behavior are explicit",
        "The threshold rationale includes population, denominator, baseline or uncertainty, and the harm boundary",
        "Decision owner, function owner, and evidence consumer are distinguished",
        "False positives, false negatives, gaming risks, exceptions, review triggers, and retirement criteria are addressed"
      ]
    },
    {
      "id": "fitness-function-evidence-review",
      "prompt": "Our architecture check has passed for six months, but it samples only successful requests and the service team can exclude slow tenants from the denominator. Review whether this is trustworthy evidence for an ADR requiring fair tenant resource isolation, and propose a safer confirmation design.",
      "expected_output": "A critical review that identifies the sample-selection and denominator problems as false-negative and gaming risks rather than treating six months of passes as proof. The redesign uses immutable or auditable raw evidence, reports exclusions, measures relevant distributions or stratified tenant cohorts, states an appropriate cadence and threshold rationale, and preserves a link from the ADR to the check and observed evidence.",
      "assertions": [
        "The response identifies successful-request sampling as a false-negative risk",
        "The response identifies denominator exclusions as a gaming or proxy-metric risk",
        "The redesign reports exclusions and uses representative or adversarial evidence rather than only averages",
        "The response distinguishes a passing result from trustworthy evidence and defines an escalation for indeterminate data",
        "The redesign retains explicit ADR, function, and observed-evidence traceability"
      ]
    },
    {
      "id": "adr-fitness-boundary",
      "prompt": "Should the ADR authoring skill own a complete evolutionary-architecture program with architecture metrics, drift governance, and change sequencing, or should it define how an ADR is confirmed by a fitness function? Explain the boundary and route the work.",
      "expected_output": "A boundary decision that keeps ADR authoring responsible for the durable decision, rationale, confirmation link, and operational record, while routing system-wide evolutionary architecture, drift governance, and change sequencing to software-architecture. It may link to test, telemetry, or governance skills for execution, but it does not absorb their tool or operational runbooks.",
      "assertions": [
        "ADR authoring is limited to durable decisions and their confirmation links",
        "System-wide evolutionary architecture and drift governance are routed to software-architecture",
        "Execution ownership remains with the relevant test, CI, telemetry, runtime, or governance system",
        "The response explains why the boundary prevents duplicated or ambiguous ownership",
        "The proposed output includes an ADR-to-function-to-evidence trace rather than a standalone metric program"
      ]
    },
    {
      "id": "repository-conventions-first",
      "prompt": "Write the next ADR. CONTRIBUTING.md requires architecture/decisions/DEC-042.md, headings Status, Problem, Choice, Effects, and immutable accepted records. DEC-041 is accepted. Your skill suggests pyramid folders and living documents.",
      "expected_output": "Draft DEC-042 using the repository conventions without reorganizing the decision log.",
      "assertions": [
        "Uses architecture/decisions/DEC-042.md and the specified headings",
        "Preserves DEC-041 and its existing path and rationale",
        "Does not create pyramid directories or impose living-document amendments"
      ]
    },
    {
      "id": "experiment-approval-scope",
      "prompt": "I approved an isolated PostgreSQL trial. Restore and deletion checks passed in the harness. Production adoption is still undecided. Draft an ADR using our Proposed/Accepted statuses.",
      "expected_output": "Record the bounded trial approval and observed evidence separately from a proposed production decision.",
      "assertions": [
        "Does not describe production adoption as accepted",
        "If marked Accepted, explicitly limits the decision to the trial",
        "Distinguishes completed harness checks from production validation still needed",
        "Does not invent an approval date or decider"
      ]
    },
    {
      "id": "living-document-local-policy",
      "prompt": "Our ADR policy uses dated amendments to accepted records in decisions/. ADR-007 remains in force. Add new trial evidence without changing the decision; do not supersede it.",
      "expected_output": "Add a dated evidence amendment under the local living-document policy while preserving the accepted decision.",
      "assertions": [
        "Keeps ADR-007 in decisions/ and retains its accepted rationale",
        "Uses a dated amendment for the new evidence without inventing results",
        "Does not create a replacement ADR merely to enforce immutability"
      ]
    }
  ]
}

# ADR Format & Authoring Guide

Complete catalog of Architecture Decision Record formats from the community ADR repository (https://github.com/architecture-decision-record/architecture-decision-record), with selection guidance by decision type and worked examples.

## Template Selection Guide

| Decision Type | Recommended Template | Why |
|---|---|---|
| Routine technology choice (library, framework) | **Nygard** | Lightweight: Status, Context, Decision, Consequences |
| Multi-option trade-off with explicit comparison | **MADR** | Decision Drivers + Considered Options with pros/cons |
| High-stakes / regulatory / compliance | **Tyree & Akerman** | 12 sections covering Issue, Assumptions, Constraints, Positions, Argument, Implications, Related decisions/requirements/artifacts/principles |
| Vendor / procurement / build-vs-buy | **Business Case** | Evaluation criteria, cost analysis, SWOT, opinions/recommendations |
| QA-contract / SLAs / non-functional requirements | **Planguage** | Tag, Gist, Priority, Stakeholders, Risks, Defined terms |
| Quick internal consensus, no formal review | **Alexandrian** | Context-specific, minimal structure |
| C-suite / executive review | **ITD (Important Technical Decisions)** | Decision-first, optimized for fast executive scanning |

---

## Template Catalog

### 1. Michael Nygard (Simple & Popular)

**Origin:** http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

**When to use:** Everyday decisions where the rationale is straightforward and options are few. The default choice unless you need more structure.

```
# Title (present tense imperative verb phrase)

## Status

proposed | accepted | rejected | deprecated | superseded by ADR-NNN

## Context

What is the issue that we're seeing that motivates this decision or change?

## Decision

What is the change we're proposing and/or doing?

## Consequences

What becomes easier or more difficult to do because of this change?
```

**Section guidance:**
- **Title:** Short imperative phrase like "Use PostgreSQL for transaction storage" or "Adopt event-driven messaging between services"
- **Status:** Single value. Use lifecycle stages for more precision.
- **Context:** The forces at play — business need, technical constraint, team capability, timeline pressure. Include why this decision is being made *now*.
- **Decision:** The outcome. Concrete and unambiguous. "We will use X" not "We considered using X."
- **Consequences:** Both positive and negative. What trade-offs are being accepted? What follow-up decisions does this create?

**Pitfalls:**
- Too terse for multi-stakeholder decisions where options need explicit comparison
- No natural place for decision driver documentation
- Temptation to skip "Consequences" when they're the most important section

---

### 2. MADR — Markdown Any Decision Records (Structured)

**Origin:** https://adr.github.io/madr/

**When to use:** Most decisions that involve multiple options with explicit trade-off comparison. The best default for most engineering teams.

```
# [short title of solved problem and solution]

* Status: proposed | rejected | accepted | deprecated | superseded by ADR-NNN
* Deciders: [list everyone involved in the decision]
* Date: YYYY-MM-DD

Technical Story: [description | ticket/issue URL]

## Context and Problem Statement

[Describe the context and problem statement. You may want to articulate the
 problem in form of a question.]

## Decision Drivers

* [driver 1, e.g., a force, facing concern]
* [driver 2]
* ...

## Considered Options

* [option 1]
* [option 2]
* [option 3]

## Decision Outcome

Chosen option: "[option 1]", because [justification].

### Positive Consequences

* [e.g., improvement of quality attribute satisfaction]
* ...

### Negative Consequences

* [e.g., compromising quality attribute]
* ...

## Pros and Cons of the Options

### [option 1]

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]

### [option 2]

* Good, because [argument a]
* Bad, because [argument b]

## Links

* Refined by [ADR-0005](0005-example.md)
* Supersedes [ADR-0002](0002-example.md)
```

**Section guidance:**
- **Decision Drivers:** The non-negotiable constraints that any solution must satisfy. These are your selection criteria. If the decision doesn't need explicit criteria, consider using Nygard instead.
- **Considered Options:** Exhaustive enough that no reviewer asks "Did you think about X?" but not so exhaustive it becomes noise. 3-5 options is typical.
- **Pros and Cons:** Each option gets its own subsection with bullet-point pros and cons. Be specific — "Good, because reduces latency by 40% under peak load" not "Good, because faster."
- **Links:** Bidirectional links to related ADRs. Use semantic link types: supersedes, refines, contradicts, extends.

**Pitfalls:**
- "Considered Options" sections can balloon. Cap at 5 options; group similar alternatives.
- Decision Drivers are often just listed not ranked. Prioritize them (Must-have vs Nice-to-have).

---

### 3. Jeff Tyree & Art Akerman (Heavyweight / Enterprise)

**Origin:** https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf

**When to use:** High-stakes decisions with regulatory, compliance, or cross-team implications. Decisions that will be audited or referenced for years.

| Section | Purpose |
|---|---|
| **Issue** | The architectural design issue being addressed, with clear rationale for why *now* |
| **Decision** | The architecture's direction — the position selected |
| **Status** | pending, decided, approved |
| **Group** | Ontology grouping: integration, presentation, data, event, calendar, location |
| **Assumptions** | Underlying environmental assumptions (cost, schedule, technology, accepted standards) |
| **Constraints** | Additional constraints the chosen alternative imposes |
| **Positions** | Viable options considered. Include models, diagrams. This prevents "Did you think about X?" in review |
| **Argument** | Why you selected the position: implementation cost, TCO, time-to-market, resource availability. As important as the decision itself |
| **Implications** | Follow-on effects: new required decisions, new/modified requirements, additional constraints, scope/ schedule changes, training needs |
| **Related decisions** | Traceability matrix, decision trees, or metamodels. Links to related AD decisions |
| **Related requirements** | Direct mapping to business objectives. If a decision doesn't contribute to a requirement, don't make it |
| **Related artifacts** | Architecture, design, or scope documents this decision impacts |
| **Related principles** | Enterprise principles this decision is consistent with. Ensures cross-system alignment |
| **Notes** | Running notes from the socialization process |

**When to skip:** Routine choices, single-developer decisions, temporary workarounds.

---

### 4. Business Case (Procurement / Vendor)

**When to use:** Build-vs-buy, vendor selection, technology procurement — decisions where cost and organizational impact are primary drivers.

**Top-level structure:**
- Title
- Status
- Evaluation criteria
- Candidates to consider
- Research and analysis of each candidate
  - Does/doesn't meet criteria
  - Cost analysis (licensing, training, operating, metering)
  - SWOT analysis (Strengths, Weaknesses, Opportunities, Threats)
  - Internal and external opinions/feedback
- Recommendation

**Cost analysis dimensions:**
- **Licensing:** contract agreements, legal commitments, vendor lock-in risk
- **Training:** upskilling, change management, ramp time
- **Operating:** support, maintenance, incident response
- **Metering:** bandwidth, CPU, API calls, data egress

**Pitfalls:**
- External opinions can be biased toward whatever the vendor recommends. Cross-reference.
- Cost estimates age fast — include date stamps on all pricing references.

---

### 5. Planguage (QA / NFR Focused)

**Origin:** Tom Gilb, https://www.iaria.org/conferences2012/filesICCGI12/Tutorial%20Specifying%20Effective%20Non-func.pdf

**When to use:** Decisions driven by quality attributes, SLAs, or non-functional requirements where precision and measurability matter.

| Keyword | Purpose |
|---|---|
| **Tag** | Unique, persistent identifier |
| **Gist** | Brief summary of the requirement or area |
| **Requirement** | The requirement text |
| **Rationale** | Reasoning justifying the requirement |
| **Priority** | Statement of priority and claim on resources |
| **Stakeholders** | Parties materially affected |
| **Status** | Draft, reviewed, committed |
| **Owner** | Person responsible for implementing |
| **Author** | Person who wrote it |
| **Revision** | Version number |
| **Date** | Most recent revision date |
| **Assumptions** | Things that could cause problems if untrue |
| **Risks** | Things that could cause malfunction or delay |
| **Defined** | Glossary terms |

---

### 6. Alexandrian Pattern (Context-First)

**When to use:** Decisions where the context is the main driver and the solution space is tightly constrained.

```
## [Title]

## Context

[The forces at play — when does this pattern apply?]

## Problem

[The specific problem this decision addresses]

## Solution

[The decision, stated as the resolution of the forces]

## Consequences

[What follows from applying this solution]
```

---

### 7. Important Technical Decisions — ITD (Executive)

**Origin:** Ignacio Larrañaga

**When to use:** Decisions that need executive sign-off. Lean and decision-first — optimized for fast scanning, not detailed deliberation.

```
# [Decision title]

## Decision

[One-line statement of what was decided]

## Why

[Brief rationale — why this decision, why now]

## Impact

[What changes as a result — one paragraph]
```

---

### 8. arc42 ADR Template (Full Documentation Structure)

**Origin:** https://arc42.org/overview — License: CC-BY-SA 4.0

**When to use:** Decisions that need to be documented within the full arc42 architecture documentation framework. This is the ADR-specific template by the arc42 team, distinct from the arc42 full documentation template.

**Sections:**

| arc42 Section | Purpose |
|---|---|
| **1. Introduction & Goals** | Requirements, driving forces, quality goals, stakeholders |
| **2. Constraints** | Anything constraining design/implementation freedom |
| **3. Context & Scope** | System boundary, external interfaces, business/technical context |
| **4. Solution Strategy** | Fundamental decisions shaping the architecture |
| **5. Building Block View** | Static decomposition — modules, components, layers |
| **6. Runtime View** | Behavior via scenarios — use cases, errors, operations |
| **7. Deployment View** | Infrastructure, environments, mapping of building blocks |
| **8. Crosscutting Concepts** | Patterns, rules, regulations spanning multiple building blocks |
| **9. Architectural Decisions** | Important decisions including rationale (this is the ADR proper) |
| **10. Quality Requirements** | Quality scenarios, quality tree |
| **11. Risks & Technical Debt** | Known risks, debt; ordered by priority |

**Relationship to system documentation:** Use this when documenting a decision inside existing arc42 documentation. Route broader system architecture work to `software-architecture`.

---

### 9. EdgeX Template (Platform / IoT)

**Origin:** https://docs.edgexfoundry.org/2.3/design/adr/template/

**When to use:** Decisions involving platform components, service boundaries, or API changes — especially IoT/edge contexts where multiple services are impacted.

```
# [Title]

## Submitters

- Name (Organization)

## Change Log

- [Status](URL of PR) YYYY-MM-DD
  Status: pending, approved, amended, deprecated.

## Referenced Use Case(s)

- [Use Case Name](URL)

## Context

- How the design is architecturally significant
- High-level design approach

## Proposed Design

Details without implementation:

- Services/modules impacted (changed)
- New services/modules to be added
- Model and DTO impact (additions/removals)
- API impact (additions/removals)
- Configuration impact
- DevOps impact

## Considerations

Alternatives, concerns, issues from debate. Resolution status.

## Decision

Caveats, future considerations, remaining or deferred issues.
Requirements not satisfied by the proposed design.

## Other Related ADRs

- [ADR Title](URL) — Relevance

## References
```

**Distinctive features:** Change Log with state/date/PR URL; Referenced Use Case(s); unusually detailed Proposed Design (model/DTO/API/config/devops). Good for when the ADR serves as both decision record AND preliminary design document.

---

### 10. Gareth Morgan Template (Summary-Driven)

**Origin:** Gareth Morgan

**When to use:** Decisions needing an executive summary first, followed by structured option analysis. Summary → Drivers → Options → Analysis → Recommendation structure mirrors modern product decision-making.

```
# [Title]

**Status:** Proposed | Under Review | Accepted | Rejected | Superseded | Deprecated
**Updated:** YYYY-MM-DD

## Summary

Executive summary / elevator pitch. 2-4 sentences stating the core problem
and a hint at the decision. Think abstract of a technical paper.

## Drivers

Why this decision is being made now:

- {We are developing a new feature that needs...}
- {We need to improve performance, accessibility...}
- {The current approach imposes limitations...}

## Options

List of options with facts, links:

### {Option 1}
Description

### {Option n}
...

## Options Analysis

### {Option 1 Assessment}
- Pro: {Specific advantage}
- Con: {Specific disadvantage, risk, or cost}
- Other: {Relevant point}

### {Option n Assessment}
...

## Recommendation

Clear statement of the final decision and why it best addresses the Drivers.

### Consequences

- Pro: {Positive outcome}
- Con: {Accepted downside or risk}
- Other: {Matter-of-fact consequence}

### Confirmation

- How implementation will be verified (reviews, tests, demos)
- How compliance will be maintained (automated checks, audits)
- Metrics/indicators showing intended outcomes
- Responsible owner

## More Information

Supplementary info, links, re-evaluation timeframe.
```

**Distinctive features:** Summary-first (elevator pitch before detail); explicit Drivers section (why *now*); Consequences classified as Pro/Con/Other; **Confirmation section** — a verification plan with compliance monitoring, metrics, and ownership. Rare in ADR templates and essential for high-stakes decisions.

---

### 11. GIG Cymru NHS Wales Template (Governance-Focused)

**Origin:** NHS Wales / GIG Cymru

**When to use:** Regulated environments (healthcare, finance, infrastructure) where compliance monitoring, governance, and visual options analysis are required.

```
# [Title]

**Status:** DRAFT | ACTIVE | DEPRECATED by [000] | SUPERSEDES [000]

## Context

Problem(s) this ADR addresses and why they exist.

## Decided Approach

Architecturally significant decision and how it solves the problem.

## Consequences

Impact on architecture characteristics and functional requirements.

## Governance

How will outcomes be monitored? How will compliance be ensured?

## Options Analysis

Trade-off analysis with traffic-light comparison tables.

### Key

Green = good fit  Amber = moderate  Red = poor fit
+ = positive comment  - = negative comment

### High-Level Overview

| Summary | Option 1 | Option 2 | Option 3 |
|---|---|---|---|
| Ease of Implementation | + Quick (green) | - Tricky (amber) | - Complex (red) |
| Timescales | + Fast (green) | - Slow (amber) | - Very slow (red) |
| Strategic Value | - Tactical (red) | + Improves (amber) | + Ideal (green) |

### Functional Requirements

| Scenario | Option 1 | Option 2 | Option 3 |
|---|---|---|---|
| Scenario 1 | | | |

### Non-Functional Requirements

| Characteristic | Option 1 | Option 2 | Option 3 |
|---|---|---|---|
| Scalability | | | |
| Performance | | | |
| Availability | | | |
```

**Distinctive features:** **Governance section** — unique among templates, asks explicitly about compliance monitoring. **Traffic-light comparison tables** — color-coded visual evaluation across summary, functional, and NFR dimensions. Designed for audited environments where decisions must be enforced, not just recorded.

---

Use the repository template when one exists. The following tree is a fallback for a new convention.

### Template Selection Decision Tree

```
Is the decision quick, single-rationale?
  → YES → Nygard
  → NO → Multiple options being compared?
    → YES → Regulatory/governance requirement?
      → YES → Compliance monitoring needed?
        → YES → NHS Wales (governance + traffic-light tables)
        → NO → Cost a primary driver?
          → YES → Business Case (cost/SWOT)
          → NO → Platform/service boundary change?
            → YES → EdgeX (Change Log + Proposed Design)
            → NO → MADR (structured option comparison)
      → NO → MADR (default for multi-option)
    → NO → QA/NFR-driven? → Planguage
    → NO → C-suite consumption? → ITD
    → NO → Context-first? → Alexandrian
```

---

### Examples Reference

The community ADR repository includes ~50+ worked examples across multiple domains for learning and inspiration:

| Domain | Example Topics |
|---|---|
| **Frameworks** | CSS framework, React, Svelte, Vue, Rails, SvelteKit, Tailwind CSS |
| **Databases** | MySQL, PostgreSQL, Database technology choice |
| **Languages** | Go, Rust, Java, Python |
| **Infrastructure** | Docker Swarm, Kubernetes, AWS, GCP, Azure, CI, Secrets storage |
| **APIs & Protocols** | JSON vs gRPC, snake_case vs camelCase, Timestamp format |
| **Team & Process** | 4-day work week, Agile, High-trust teamwork, Work from home |
| **Cross-cutting** | Monorepo vs multirepo, Environment variable config, Metrics |

Browse the full collection at: https://github.com/architecture-decision-record/architecture-decision-record/tree/main/locales/en/examples/

Study 2-3 examples from your domain before writing a first ADR to internalize the conventions.

---

## Worked Example: MADR Format

```
# Use PostgreSQL for Service Transaction Storage

* Status: accepted
* Deciders: Magnus Hedemark, Sarah Chen, DevOps Team
* Date: 2026-06-05

Technical Story: Service requires durable, ACID-compliant storage for
customer transaction records across geographic regions.

## Context and Problem Statement

The service needs to store customer transaction data with strong consistency
guarantees. The current prototype uses in-memory storage which is unacceptable
for production. We need a database that supports ACID transactions, replication
across regions, and has a proven operational track record.

## Decision Drivers

* Must support ACID transactions (non-negotiable — regulatory requirement)
* Must support active-passive replication across 2 regions
* Team has existing PostgreSQL expertise (3 senior DBAs)
* Must fit within existing $500/mo infrastructure budget

## Considered Options

* PostgreSQL — relational, ACID, mature replication (pglogical / Patroni)
* MySQL — relational, ACID, Group Replication
* CockroachDB — distributed SQL, natively multi-region
* DynamoDB + transactions — managed NoSQL with limited ACID

## Decision Outcome

Chosen option: "PostgreSQL", because it satisfies all decision drivers,
eliminates team learning curve, and has the lowest operational cost for our
scale.

### Positive Consequences

* ACID compliance guaranteed within existing team expertise
* Active-passive replication via Patroni (deploy this week)
* No licensing costs; fits within infrastructure budget

### Negative Consequences

* Manual sharding may be needed above 5TB (unlikely in year 1)
* Single-writer limitation in active-passive mode

## Pros and Cons of the Options

### PostgreSQL

* Good, because full ACID with serializable isolation
* Good, because existing team expertise eliminates ramp time
* Good, because mature replication tooling (Patroni, repmgr)
* Bad, because single-writer topology limits write throughput

### MySQL

* Good, because ACID with InnoDB
* Good, because Group Replication supports multi-writer
* Bad, because less team expertise (1 DBA vs 3 for Postgres)
* Bad, because Group Replication has known stability issues in async mode

### CockroachDB

* Good, because natively multi-region with strong consistency
* Bad, because 2x infrastructure cost for equivalent hardware
* Bad, because operational complexity requires dedicated SRE support

### DynamoDB + Transactions

* Good, because zero operations overhead
* Bad, because transaction API has 25-item / 4MB limits
* Bad, because vendor lock-in to AWS
* Bad, because $0.50/hr per replica is over budget at scale

## Links

* Refined by [ADR-0010](0010-patroni-cluster-configuration.md)
* Supersedes [ADR-0003](0003-in-memory-storage-poc.md)
```

---

## Architecture Decision Log (ADL) Conventions

Existing repository paths, identifiers, templates, and amendment rules take precedence over these fallback examples. Never relocate accepted or superseded records merely to match this guide.

### File Naming

```
NNN-short-present-tense-phrase.md
```

Rules:
- **Number:** Zero-padded sequence (001, 002, ... 010). Preserve published identifiers; gaps are acceptable. Resolve a collision on an unpublished draft without renumbering existing records.
- **Phrase:** Present tense imperative verb phrase — like a good commit message.
  - Good: `012-use-postgresql-for-transaction-storage.md`
  - Bad: `012-postgresql.md` (no verb), `012-decided-to-use-postgresql.md` (past tense)
- **Case:** Lowercase with hyphens (kebab-case).
- **Extension:** `.md` for easy rendering.

### Directory Naming

Consider naming the directory `decisions/` instead of `adr/` — some teams respond better to plain language. The template is content-neutral; you can document vendor decisions, planning decisions, and scheduling decisions in the same format.

### Numbering Scheme

- Sequential across the entire project (not per-category)
- Never reuse a number — if an ADR is rejected, leave the number retired
- Consider prefix for multi-project orgs: `PLAT-012-use-postgresql.md`

# ADR-to-Pyramid Mapping

Apply only when artifact pyramids are already the project convention or explicitly requested. Existing ADR paths and lifecycle rules take precedence. Prefer links from pyramid indexes to canonical ADRs; this mapping does not require moving superseded records.

## Mapping Table

| ADR State | Pyramid Layer | What Lives There | Consumer |
|-----------|--------------|------------------|----------|
| Navigation index | **L1** (01-summary/) | List of all ADRs with status, link to each | Orchestrator needing to find a decision |
| Active ADRs | **L2** (02-analysis/) | Full decision record: context, options, rationale, consequences | Engineers, reviewers |
| Superseded ADRs | **L3** (03-dossiers/) | Historical decisions that have been replaced | Historians, anyone challenging a current decision |

## Why Layered Navigation Can Help

ADRs are modular by nature — each decision is a single document. But they still benefit from progressive disclosure:

- **L1:** A navigation index helps an agent find the right ADR without reading all of them
- **L2:** Active ADRs provide the decision rationale alongside the C4 views they relate to
- **L3:** Superseded ADRs preserve decision history without cluttering active analysis

## Relationship to C4

Every ADR in L2 should reference the C4 Container or Component it affects. Every C4 Container/Component diagram should reference the ADRs that shaped it.

# Decision Sustainability Framework

A framework for evaluating whether an Architecture Decision Record (ADR) will survive contact with reality. Based on the InfoQ article "Sustainable Architectural Design Decisions" and documented in the community ADR repository.

**Concept origin:** https://www.infoq.com/articles/sustainable-architectural-design-decisions/ — also at `locales/en/documents/decision-sustainability-criteria/` and `locales/en/documents/guidelines-to-achieve-sustainable-decisions/` in the ADR community repo.

## Five Sustainability Criteria

Every ADR should be evaluated against these criteria before acceptance. They form a quality gate checklist for the ADR review process.

### 1. Strategic

**Question:** Does this decision consider long-term impact?

A strategic decision accounts for future operations, maintenance, and evolution — not just the immediate problem. It explicitly addresses the downstream consequences of the choice.

**Checklist:**
- [ ] What is the projected lifespan of this decision? (6 months? 2 years? 10 years?)
- [ ] How will this decision affect future maintenance burden?
- [ ] Does this decision lock the team into a specific technology or pattern?
- [ ] Are the switching costs documented?

**Pitfall:** A decision that optimizes for today at the expense of the next 6-12 months may still be correct — but only if the short-term horizon is explicit in the rationale.

### 2. Measurable and Manageable

**Question:** Can this decision be objectively evaluated over time?

A sustainable decision has measurable outcomes. You should be able to look back in 6 months and determine whether the decision was correct.

**Checklist:**
- [ ] Are the criteria for success or failure defined?
- [ ] Are numeric targets specified where possible? (latency p99 < 200ms, cost < $500/mo)
- [ ] Is the decision granular enough to be traceable? (too fine-grained = noise, too coarse = ambiguity)
- [ ] Are dependencies between this decision and other decisions documented?

**Pitfall:** "Improve performance" is not measurable. "Reduce p99 latency from 800ms to under 200ms" is measurable. Quality attribute scenarios (from arc42) are the right tool here.

### 3. Achievable and Realistic

**Question:** Is this the "good enough" choice, not the perfect one?

A sustainable decision is grounded in what the team can actually deliver. Over-engineering for hypothetical future needs is a common failure mode.

**Checklist:**
- [ ] Can the team implement this given current skills and capacity?
- [ ] Does this decision avoid over-engineering? (Is there a simpler alternative that was considered and rejected for a documented reason?)
- [ ] Is the implementation timeline realistic?
- [ ] Are the operational costs within budget?

**Pitfall:** A technically elegant decision that the team cannot execute is a failure of architecture, not of the team. The "good enough" test: does this decision get us 80% of the benefit with 20% of the complexity?

### 4. Rooted in Requirements

**Question:** Does this decision trace back to real business or technical requirements?

A sustainable decision is grounded in the actual problem — company context, team makeup, user needs — not an abstract "best practice."

**Checklist:**
- [ ] Is this decision directly tied to a specific requirement or constraint?
- [ ] Have team skills, training budget, and organizational context been considered?
- [ ] If the requirements change, would this decision need revisiting? (If yes, flag it.)
- [ ] Are external dependencies (vendors, platforms, regulations) documented?

**Pitfall:** "Everyone uses Kubernetes" is not a requirement. "We need horizontal scaling for predictable traffic patterns our current single-server setup can't handle" is a requirement. Decisions rooted in bandwagon effects rather than actual requirements age poorly.

### 5. Timeless

**Question:** Is this decision based on knowledge unlikely to be outdated soon?

A sustainable decision favors durable knowledge over fashionable technology. Platform-neutral patterns and architectural tactics outlast specific tools.

**Checklist:**
- [ ] Is the decision based on architectural patterns/tactics rather than specific tool versions?
- [ ] If the chosen vendor/product disappeared tomorrow, would the architecture survive?
- [ ] Is the rationale still valid if underlying technology choices change?
- [ ] Does the ADR distinguish between "what" (the pattern) and "which" (the specific tool)?

**Example:** Choosing event sourcing because "we need an audit trail" is a timeless architectural decision. Choosing event sourcing because "Kafka is trendy" is not. The ADR should articulate the timeless principle, not just the tool choice.

## Eight Guidelines for Sustainable Decisions

From the InfoQ article, these guidelines help put the criteria into practice:

| # | Guideline | Applies to |
|---|-----------|-----------|
| 1 | **Use a lean/minimalistic approach for initial documentation.** Don't write a Tyree & Akerman on day one. Start with Nygard or MADR. | ADR drafting |
| 2 | **Prioritize and capture all important decisions first.** Identify what matters before elaborating. | ADR identification |
| 3 | **Detail important decisions after initial approval.** Full-blown templates come after stakeholders agree the direction is right. | ADR review |
| 4 | **Use lean versions for trivial decisions.** Not every decision needs Options Analysis. For obvious choices, a paragraph in the index or a Nygard ADR is enough. | Template selection |
| 5 | **Reuse existing architectural knowledge.** Don't reinvent patterns documented in arc42, Martin Fowler, or your own past ADRs. Reference them. | ADR writing |
| 6 | **Establish traceability links between decisions, requirements, and code.** Every ADR should link back to the requirement that drove it and forward to the code that implements it. | ADR structure |
| 7 | **Provide automated consistency checking for traceability links.** See `references/fitness-functions.md` for how to make this mechanical. | CI/governance |
| 8 | **Enforce justifications forcefully.** The rationale is the most important part of any ADR. A decision without justification is not a decision — it's an opinion. | ADR quality |

## Using the Framework: ADR Review Checklist

Before accepting an ADR, evaluate it against these questions:

```
1. STRATEGIC — Does this consider long-term impact beyond the immediate problem?
   If no: add a "Future considerations" section to the ADR.

2. MEASURABLE — Are success/failure criteria defined, ideally with numeric targets?
   If no: add quality attribute scenarios before accepting.

3. ACHIEVABLE — Is this "good enough," not over-engineered for hypothetical futures?
   If no: document what simpler alternatives were considered and why the extra complexity is justified now.

4. ROOTED — Does this trace back to a specific requirement, constraint, or team context?
   If no: identify the actual requirement and link it. If none exists, re-evaluate whether the decision is needed.

5. TIMELESS — Is the rationale based on durable architectural knowledge, not today's trends?
   If no: reframe the ADR to articulate the architectural principle, not the specific tool name.
```

## Further Reading

- InfoQ — "Sustainable Architectural Design Decisions": https://www.infoq.com/articles/sustainable-architectural-design-decisions/
- ADR community repo — sustainability criteria: https://github.com/architecture-decision-record/architecture-decision-record (see `locales/en/documents/decision-sustainability-criteria/` and `guidelines-to-achieve-sustainable-decisions/`)

# Fitness Functions for Decision Confirmation

A fitness function is a repeatable check that supplies evidence about whether an architectural decision still holds. It may be a static rule, a test, a runtime measurement, a scheduled audit, or a bounded human review. The useful unit is not the check alone: it is the trace from decision, to characteristic, to measurement, to observed evidence, and back to a reviewable owner.

## Ownership Boundary

The ADR owns the durable choice, rationale, consequences, and a link to confirmation. The fitness-function record owns the operational contract for the check. The project's test, CI, telemetry, runtime, or governance system owns execution and raw evidence. Do not put executable implementation in the ADR, and do not let an operational dashboard silently become the decision record.

For system-wide evolutionary architecture, use [`software-architecture`](../../software-architecture/SKILL.md). For general SLO, telemetry, or alerting design, use the relevant reliability or telemetry skill. For operating a named tool, use that tool's skill. This reference is about making an ADR's consequential claim confirmable.

## Decision-to-Evidence Trace

Record the chain explicitly:

```text
ADR-042: isolate tenant data at the repository boundary
  -> characteristic: cross-tenant access safety
  -> fitness function: integration test attempts reads and writes with mismatched tenant contexts
  -> observed evidence: CI run 1842, 0 unauthorized rows across 240 cases
  -> decision review: owner accepted evidence; next review 2026-09-30
```

An ADR link such as `Confirmed by: docs/architecture/fitness/tenant-isolation.md` is sufficient when the linked record contains the rest of the chain. A pass without a source, run identifier, sample window, or reviewer is not durable evidence.

## Select the Function

Start with the decision's observable characteristic, not with a favorite tool. Ask what would convince a skeptical future reviewer that the decision is holding.

### Scope

Choose the narrowest boundary that can falsify the decision without making the result meaningless:

- **Atomic:** one dependency, package, route, schema rule, or configuration property. Use for a crisp invariant such as forbidden imports.
- **Structural:** a set of components or relationships. Use for layering, cycles, ownership, or deployment topology.
- **Scenario:** a user or operational path across components. Use for authorization, recovery, ordering, or end-to-end guarantees.
- **Holistic:** a system-wide outcome such as latency distribution, cost, or recovery time. Use only when the decision itself is system-wide and the measurement can identify meaningful change.

State what is inside and outside the boundary, the population sampled, and the blind spots. A broad metric that cannot identify a violating path is a signal, not a compliance gate. Pair it with a narrower check when a missed violation would be costly.

### Cadence and Invocation

Select cadence from failure speed and change exposure:

- **Change-triggered:** run on pull requests, schema changes, or deployment configuration changes when a violation should block introduction.
- **Continuous:** collect at runtime when drift or harm can emerge between releases, such as error rates or resource isolation.
- **Scheduled:** sample periodically when the evidence is expensive, data-dependent, or needs a stable observation window.
- **Event-triggered:** run after an incident, migration, exception, or material dependency change.

Name the invocation mechanism and its failure behavior: command or job, environment, required fixtures, timeout, result sink, and whether a missing result is a failure, warning, or escalation. Automated invocation is preferred for repeatable facts. A manual review is valid when judgment is intrinsic, but it needs a named reviewer, structured evidence request, and due date rather than “review occasionally.”

### Evidence Type

Classify evidence before choosing a threshold:

| Evidence | Best for | Main limitation |
|---|---|---|
| Static analysis | Dependencies, ownership markers, configuration shape | Can miss runtime paths and generated behavior |
| Test result | Behavior under declared scenarios and fixtures | Only covers the scenarios and data exercised |
| Runtime telemetry | Actual distribution, incidents, saturation, and user impact | Needs context, sampling controls, and stable instrumentation |
| Audit sample | Data or process conditions that are expensive to check continuously | Sampling can miss rare failures |
| Expert review | Intent, trade-offs, and evidence not mechanically expressible | Must expose reviewer, rubric, dissent, and date |

Use at least two evidence types when the decision has both a structural condition and an outcome claim. Do not treat a proxy metric as proof of the decision; label it as leading, lagging, or diagnostic evidence.

### Threshold Rationale

Every threshold needs a reason, not just a number. Record:

1. the unit, population, aggregation, and time window;
2. the desired value or allowed range;
3. the baseline and measurement uncertainty;
4. the harm or decision consequence at the boundary;
5. why this threshold is achievable now;
6. who can change it and what evidence is required.

Prefer a hard gate for a safety or compatibility invariant. Prefer a warning band and trend review for noisy outcomes. Use a minimum sample size, confidence or uncertainty note, and a missing-data rule where they affect interpretation. A threshold that can be passed by reducing traffic, excluding difficult cases, or changing the denominator is not defensible until those gaming paths are addressed.

## Operate Without Fooling Yourself

### Ownership

Assign three roles when the blast radius warrants it:

- **Decision owner:** accountable for whether the ADR still applies and for approving changes to its rationale.
- **Function owner:** keeps the check runnable, interpretable, and linked to the current decision.
- **Evidence consumer:** reviews results and acts on failures; this may be an on-call, service, or governance owner.

For small teams one person may hold all roles, but record the names or teams and the escalation path. The function owner cannot unilaterally weaken a threshold that protects another team's boundary.

### False Positives and False Negatives

Document known failure modes for the measurement:

- A **false positive** reports violation when the decision holds. Record suppression criteria, fixture corrections, quarantine limits, and the human escalation path. Never make a permanent exception by hiding the result.
- A **false negative** reports compliance while the decision is violated. Record untested paths, sampling gaps, instrumentation failures, and a compensating check.

For every expected exception, identify the evidence that distinguishes it from a real violation. If a check fails because its own data or instrumentation is stale, mark the result as indeterminate rather than compliant.

### Gaming and Proxy Risk

Assume that teams optimize for the visible score. Review whether the subject can improve the metric while the decision's intent worsens: narrow the sample, move work outside the measured boundary, delete failures, retry until success, or optimize an average while harming the tail. Countermeasures include immutable raw evidence, denominator and exclusion reporting, stratified or adversarial samples, paired outcome measures, independent review, and periodic spot checks. Record which countermeasure is used and what it cannot prevent.

### Exceptions

An exception is a visible, time-bounded deviation, not a second threshold. Each exception record should state the affected boundary, reason, risk acceptance, compensating control, approver, start date, expiry date, and exit evidence. A failed function should route to the decision owner or named escalation path. Do not auto-approve an exception merely because the check is noisy.

## Review and Retirement

Review the function when the ADR changes, the measured system boundary changes, a failure or incident exposes a blind spot, the owner changes, or the evidence stops influencing a decision. At the review, ask:

- Does the decision still apply, and does the characteristic still matter?
- Does the scope cover the paths and populations that can violate the decision?
- Is the cadence early enough for the harm and affordable enough to sustain?
- Does observed evidence support the threshold, or is the baseline now stale?
- Are false positives, false negatives, gaming paths, and exceptions visible?
- Did a human act on the last meaningful result?

Retire a function only when the ADR is superseded, the characteristic is no longer a decision driver, or a better check replaces it. Record the retirement reason, date, owner approval, replacement link if any, last evidence location, and any unresolved risk. Do not delete historical results or leave an ADR link pointing to an unmarked dead check.

## Common Forms

Static architecture tests such as ArchUnit can enforce dependency direction, package cycles, or naming rules. TypeScript equivalents can inspect module relationships. Runtime or integration checks are better for tenant isolation, recovery, ordering, or authorization scenarios. CI can validate a Structurizr model's syntax and references. An AI-assisted review can compare a change against several ADRs when the claim is semantic, but it must identify its input artifacts, rubric, model or reviewer, uncertainty, and escalation path; it is evidence for review, not an unquestioned gate.

The implementation belongs in the project's test or operational infrastructure. The ADR should link to the record and the record should link to the observed run, report, query, or review artifact.

# Bootstrapping ADR Conventions in a New Project

A repeatable workflow for establishing Architecture Decision Records in a codebase that doesn't have them yet.

Use only after checking that no local convention exists or when the user asks to establish one. Existing repository instructions override every fallback below, including location, template, review workflow, and amendment policy.

## Quick Checklist

- [ ] Choose a template (default: Nygard; MADR for multi-option analysis)
- [ ] Decide directory location (default: `docs/adr/`)
- [ ] Write a README index (`docs/adr/README.md`)
- [ ] Document conventions in `CONTRIBUTING.md`
- [ ] Document ADR location in `AGENTS.md` (AI agents need to know where to look)
- [ ] Create initial batch of ADRs for the design decisions already made
- [ ] Deliver through the repository's established review workflow

## Step-by-Step

### 1. Choose a Template

| When | Template | Sections |
|------|----------|----------|
| Quick decision, single rationale | **Nygard** (default) | Status, Context, Decision, Consequences |
| Multi-option trade-off analysis | **MADR** | Status, Deciders, Date, Context, Decision Drivers, Considered Options, Outcome, Links |
| High-stakes / regulatory | **Tyree & Akerman** | 12 sections (Issue, Positions, Argument, Implications, etc.) |
| Vendor / procurement | **Business Case** | Evaluation criteria, cost/SWOT analysis |
| QA / NFR focused | **Planguage** | Tag, Gist, Priority, Stakeholders, Risks |

### 2. Set Directory Convention

```text
docs/
└── adr/
    ├── README.md          # Index table with statuses + links
    ├── 0001-title.md      # First ADR
    ├── 0002-title.md
    └── ...
```

**Naming convention:**
- `NNNN-title-with-dashes.md` — sequential zero-padded numbers, imperative verb phrase
- Status lives in the document header (`Status: accepted`), never in the filename
- Extension: `.md` for easy rendering

**Directory naming note:** Some teams prefer `decisions/` over `adr/` for plain-language accessibility. The ADR template format works identically with either name.

### 3. Write the README Index

The index serves as the entry point for anyone (including AI agents) exploring the decision log. Include:

- Brief explanation of what ADRs are and the convention
- Full table: ADR number, title, status
- Link back to `CONTRIBUTING.md` for the ADR workflow

See `docs/adr/README.md` in the GroktoCrawl repo (`groktopus/groktocrawl`) for a worked example.

### 4. Document in CONTRIBUTING.md

Add a section covering:

- **Convention:** file naming, statuses, immutability
- **When to write an ADR:** new integration/service, changing existing pattern, choosing between significant alternatives, decisions a future contributor would want the "why" on
- **Workflow:** create ADR with next number → include in PR → on acceptance update the index

### 5. Document in AGENTS.md

AI agents need a single sentence pointing them to the ADR directory:

```markdown
Architecture Decision Records (ADRs) live in `docs/adr/` and capture the context
and rationale behind significant design choices. Always check the ADR index at
`docs/adr/README.md` before making architectural changes — existing ADRs may
document constraints or rejected alternatives that inform your approach.
```

### 6. Example Issue-First PR Workflow

Use this only if the repository requires an issue-first workflow; do not create issues, commits, or PRs solely because this example lists them.

1. File an issue documenting the adapter/architecture design (L1 summary + L2 key decisions)
2. Branch from main with a descriptive name (`feat/adapter-architecture`)
3. Create ADR files using the MADR template
4. Document convention in `CONTRIBUTING.md`
5. Add agent reference in `AGENTS.md`
6. Ignore generated local artifacts only when relevant to this project
7. Commit with `Signed-off-by` (DCO) and `Refs: #NNN` in the commit body
8. Push and open PR referencing the issue (`Closes #NNN`)

## ADR Lifecycle (for ongoing use)

```text
proposed → accepted | rejected
accepted → deprecated | superseded by ADR-NNNN
```

- **Fallback amendment rule (local policy takes precedence):** Preserve accepted rationale. To change a decision, write a new ADR and update only the old record's status and successor link.
- **Linking:** Every ADR's Links section should reference related ADRs with semantic link types: `Refined by`, `Supersedes`, `Defined by`, `Contradicts`.
- **Retired numbers:** Never reuse an ADR number — if rejected, leave the number retired in the index with status `rejected`.

## Worked Example

The GroktoCrawl adapter architecture PR at `groktopus/groktocrawl#89` demonstrates this full workflow:
- 9 ADRs using the MADR template covering the adapter registry pattern
- README index with status table
- CONTRIBUTING.md update with ADR convention section
- AGENTS.md update with ADR reference

# Source index

- **Source repository:** https://github.com/magnus919/hermes-profiles
- **Inspected commit:** `867a555`
- **Imported source directory:** `architecture/adr-authoring`
- **Porting boundary:** Retained portable methodology, templates, scripts, and references. Removed or generalized Hermes profile, task-orchestration, memory, and rigid response-handoff assumptions.
- **Issue scope:** Issue #339 deepens fitness-function selection and lifecycle guidance without creating a separate evolutionary-architecture skill.
- **Synthesis boundary:** The fitness-function method, examples, record template, and eval fixtures in this skill are original repository prose synthesized from the existing ADR material, the issue requirements, and the repository's safe architecture gap analysis. No purchased ebook text, tables, diagrams, examples, taxonomies, or chapter structures are reproduced.
- **Ownership boundary:** `adr-authoring` owns the durable decision and its confirmation link. [`software-architecture`](../../software-architecture/SKILL.md) owns the system-wide evolution method; implementation and evidence execution belong to the relevant test, CI, telemetry, runtime, or governance owner.

# Fitness-Function Record

Use one record per check or deliberately grouped family of checks. Keep this record near the project's architecture governance artifacts and link it from the ADR. It describes the operational contract; executable code and raw results remain in the owning system.

## Identity

- **Record ID:** [stable identifier]
- **Status:** proposed | active | paused | retired
- **Decision:** [ADR number and link]
- **Decision owner:** [person or team]
- **Function owner:** [person or team]
- **Evidence consumer:** [person, team, or queue]
- **Last reviewed:** [YYYY-MM-DD]
- **Next review:** [YYYY-MM-DD or trigger]

## Claim And Scope

- **Architectural characteristic:** [what quality or constraint matters]
- **Decision claim:** [one sentence stating what the ADR requires]
- **Scope type:** atomic | structural | scenario | holistic
- **Included boundary:** [components, paths, environments, and population]
- **Excluded boundary and blind spots:** [what this cannot establish]
- **Failure consequence:** [what risk or decision consequence follows]

## Measurement And Execution

- **Function description:** [test, query, rule, audit, or review]
- **Evidence type:** static | test | runtime | audit sample | expert review | mixed
- **Inputs and fixtures:** [source data, versions, scenarios, and sample size]
- **Invocation:** [command, job, dashboard, review process, or URL]
- **Cadence:** change-triggered | continuous | scheduled | event-triggered
- **Environment and timeout:** [where, when, and how long]
- **Missing or indeterminate result:** [fail, warn, escalate, or retry rule]
- **Observed evidence location:** [run ID, report, query, or review artifact]

## Threshold And Validity

- **Pass condition:** [unit, aggregation, window, and allowed range]
- **Warning condition:** [if applicable]
- **Threshold rationale:** [baseline, uncertainty, harm boundary, and why achievable]
- **Denominator and exclusions:** [how the population is counted]
- **False-positive controls:** [known benign cases and their evidence]
- **False-negative controls:** [coverage gaps and compensating checks]
- **Gaming or proxy risks:** [ways the score could improve while intent worsens]
- **Countermeasures:** [raw evidence, sampling, paired measure, review, or spot check]

## Exceptions And Response

- **Failure response:** [block, alert, ticket, review, or escalation]
- **Exception process:** [required fields, approver, expiry, and compensating control]
- **Current exceptions:** [links or `none`]
- **Evidence review notes:** [what the last meaningful result changed or confirmed]

## Lifecycle

- **Review triggers:** [ADR change, boundary change, incident, owner change, stale data, or calendar]
- **Retirement criteria:** [when this check no longer tests a live decision]
- **Replacement or successor:** [link, or `none`]
- **Retirement record:** [date, approver, reason, last evidence, and unresolved risk]

## ADR Link Text

Add a concise link in the ADR, for example:

`Confirmed by: [FF-042](../architecture/fitness/FF-042.md); latest evidence: [CI run 1842](...)`