vm-adr-writer

# Architecture Decision Record Writer

This skill produces standardized Architecture Decision Records (ADRs) following the Michael Nygard template pattern. Each ADR captures a single material design decision with its full context, alternatives, trade-offs, and consequences.

## When to Invoke

Invoke this skill whenever a material architecture or design decision is made, including:

- Technology or framework selection
- API versioning, authentication, or contract strategy
- Database engine, schema pattern, or migration approach
- Component decomposition or service boundary placement
- Integration pattern selection (sync vs async, REST vs gRPC, etc.)
- Refactoring strategy that changes structural design
- Trade-off resolution where multiple viable alternatives existed

Do NOT invoke for trivial decisions (variable naming, formatting choices, minor implementation details).

---

## ADR File Naming

ADRs are numbered sequentially within the project output directory:

```
docs/{agent-output-folder}/adr/
  ADR-001-{slug}.md
  ADR-002-{slug}.md
  ...
```

The slug is a lowercase-hyphenated summary of the decision title. Example: `ADR-003-use-event-sourcing-for-audit-trail.md`.

To determine the next ADR number:
1. Check the `docs/{agent-output-folder}/adr/` directory for existing ADR files.
2. If no directory or no files exist, start at `ADR-001`.
3. Otherwise, increment from the highest existing number.

---

## ADR Template

Every ADR must follow this structure exactly. Load `assets/adr-template.md` and fill in all `{placeholder}` fields before writing the file.

---

## Output Rules

1. One ADR per decision. Do not combine multiple decisions into a single ADR.
2. The Status field starts as `Proposed` unless the calling agent has explicit approval authority, in which case use `Accepted`.
3. Always populate the Alternatives section. An ADR without alternatives is incomplete -- if only one option existed, explain why no alternatives were viable.
4. The Consequences section must include both positive and negative entries. Every decision has trade-offs.
5. Cross-reference related ADRs in the References section when a decision depends on or supersedes a prior one.
6. Keep language factual and concise. Avoid subjective qualifiers ("elegant", "beautiful", "ideal").
7. If the calling agent provides trade-off analysis output, incorporate it directly into the Alternatives and Consequences sections rather than duplicating the analysis.

---

## JSON Index

When creating ADRs, also maintain an `adr-index.json` file in the same `adr/` directory:

```json
{
  "generated_by": "{calling-agent-name}",
  "adr_directory": "docs/{agent-output-folder}/adr/",
  "records": [
    {
      "id": "ADR-001",
      "title": "{Decision title}",
      "status": "Accepted",
      "date": "2026-04-02",
      "file": "ADR-001-{slug}.md"
    }
  ]
}
```

If `adr-index.json` already exists, append the new record to the `records` array. Do not overwrite existing entries.

---

## Temp