adr

Files (1)

• SKILL.md

SKILL.md (first lines)

# ADR Skill

## Purpose

Help create Architecture Decision Records and analyze their impact on related
architecture artifacts. Treat every AI-created artifact, relation, and impact
claim as proposed until a human reviewer accepts it in the repository.

This skill is guidance and reusable content only. Do not implement AI execution,
do not implement a generator, and do not add automation as part of using this
skill.

Apply the repository contract hierarchy: this skill narrows `AGENTS.md`, and
`AGENTS.md` adapts `general-semantic-contracts.md`. Do not duplicate general
metadata, anchor, or Docs-as-Code rules here unless the ADR workflow needs a
stricter rule.

## Core Workflow

1. Inspect existing architecture documentation before writing.
2. Inspect relevant source code if available.
3. Identify existing ADRs, risks, quality scenarios, requirements, constraints,
   components, interfaces, and concepts that may relate to the decision.
4. Draft a proposed ADR with explicit assumptions, options, consequences,
   metadata, provenance, and a 3-point Pugh matrix.
5. Analyze impacts on existing risks and quality scenarios.
6. Create new risk or quality scenario artifacts only when no existing artifact
   covers the impact.
7. Propose explicit metadata relations.
8. Update affected artifacts with **outgoing** relations only when justified by evidence.
   Never create reciprocal incoming relations; they are derived automatically during generation.
9. Add stable AsciiDoc anchors to created documentation artifacts and use
   anchor-based `xref` links for visible references to documentation artifacts.
10. Prefer small, reviewable patches.
11. Run the repository validator after changes if one is available.

## Required Reading

Read these references as needed:

- `../../src/docs/arc42/04-solution-strategy/doc-04001-metamodel.adoc` before writing or
  changing artifact metadata, artifact types, lifecycle states, or relation
  semantics.
- `../references/metadata-rules.md` before writing YAML front matter.
- `../references/relation-rules.md` before proposing or updating relations.
- `../references/adr-writing-guide.md` before drafting ADRs.
- `../references/risk-writing-guide.md` before creating or changing risks.
- `../references/quality-scenario-guide.md` before creating or changing quality
  scenarios.

Use these templates:

- `../../templates/adr.adoc` for ADR artifacts.
- `../../templates/risk.adoc` for new risk artifacts.
- `../../templates/quality-scenario.adoc` for new quality scenario artifacts.
- `../../templates/impact-report.adoc` for review reports when the user wants
  analysis without direct artifact changes.

## Inputs To Collect

- Decision topic and desired outcome.
- Forces, constraints, and candidate options.
- Existing architecture artifacts and their stable IDs.
- Relevant source code, configuration, API contracts, deployment files, tests, or
  operational evidence.
- Known risks, quality scenarios, requirements, or stakeholder concerns.
- Review scope: draft-only, update artifacts, or produce an impact report.

## Inspection Rules

- Prefer reviewed repository source files over conversational memory.
- Do not load derived output as evidence or architecture context. This includes
  `generated/`, `build/`, `dist/`, `target/`, `out/`, rendered HTML/PDF,
  generated indexes, traceability views, and assembled documentation.
- Treat explicit metadata as more authoritative than inferred prose.
- Check existing artifact IDs before assigning new IDs.
- Read the closest architecture index, ADR register, risk list, quality tree, and
  affected arc42 chapter when present.
- Inspect code only to gather evidence or discover affected components; do not
  implement the decision unless the user separately asks for implementation.

## Output Rules

- Keep all AI-generated artifacts `status: proposed` or `status: draft`.
- Set `reviewed: false` for AI-generated or AI-modified content unless human
  review is already recorded in the repository.
- Preserve existing accepted statuses unless there is explicit repository
  evidence that they changed.
- Mark uncertain values as assumptions or open questions.
- Do not invent accepted relationships.
- Do not change a relation's status because its target was retired. `rejected`
  is a verdict about the claim, not about the passage of time. Retirement is a
  human decision recorded on the target artifact's validity axis; propose it,
  do not record it as done.
- Do not create new risk or quality scenario artifacts when a justified relation
  to an existing artifact is sufficient.
- Keep metadata relation targets as stable artifact IDs; render visible
  documentation references as anchor-based AsciiDoc `xref` links.
- Add `derived_from` metadata when the ADR originates from a specific user
  question, prompt, Q&A entry, external document, repository document, or
  existing artifact. Prefer an anchor, URL, repository path, or artifact ID when
  available; otherwise record a concise text description.
- If the ADR body should display its provenance, include the generated
  metadata attribute fragment and render `Derived from {derived_from_description}`
  inside `ifdef::derived_from_description[]`.
- Use `derived_from` for provenance and `relations` for architecture
  traceability. Do not invent an artifact relation just to preserve where the
  ADR came from.
- Keep ADR impact and traceability data exclusively in YAML front matter
  relations. Do not add a manual impact matrix, manual traceability matrix, or
  reciprocal incoming relations to the ADR body.
- Make impact and traceability visible through `=== Impact` and
  `=== Traceability` sections that include the generated local
  `generated/<artifact-anchor>-impact.adoc` and
  `generated/<artifact-anchor>-traceability.adoc` fragments with
  `leveloffset=+2`. The generator owns the visible tables, and each fragment
  starts with `== Matrix` because the source document owns the semantic section
  heading.
- Use explicit target anchors for visible links; do not derive xrefs from raw

From docs-as-code-toolkit/architecture-knowledge-toolkit, MIT.

More from docs-as-code-toolkit/architecture-knowledge-toolkit