adr-manage

Skill: Create or update ADRs

Guide to create or update Architecture Decision Records.

Scope of an ADR: ADRs are limited to recording the architectural decision and its justification. They may include examples, diagrams or references internal or external supporting references (links to documentation, RFCs, PRs, other ADRs, etc.), but they do not develop the implementation. The implementation and operational instructions for the AI are the responsibility of the skills.

The canonical template is in references/adr-template.md (read it before writing any ADR).

Required subagent

This skill must necessarily run under the subagent docs-specialist. Do not run directly without delegating to that subagent.

File location

Artifact	Path
ADRs	`docs/adr/ADR-XXX-<slug>.md`
Index	`docs/adr/README.md`

File name conventions

Format: ADR-XXX-<slug>.md
XXX: 3-digit number with leading zero (001, 012, 123)
slug: lowercase, kebab-case, short and descriptive (e.g. auth-strategy, db-engine-selection)

Required metadata

Field	Rule
`Estado`	One of: `Draft` · `Proposed` · `Accepted` · `Deprecated` · `Superseded`
`Fecha de creación`	Actual creation date — never modified afterward
`Última actualización`	Today's date on every write to the file (creation or editing)
`Decisores`	Names or roles of those who made the decision
`Etiquetas`	Relevant keywords (technology, domain, etc.)

Information required before drafting

Before writing any ADR, the agent must have the following information clear. Do not invent anything — if any data is not explicit, ask the user.

Data	How to obtain it	If it is not available
Architectural problem or tension	From the context or the user's description	Ask the user
Concrete decision	From the context or the user's description	Ask the user
Decision makers	Indicated by the user	Ask explicitly before closing the ADR
Alternatives considered	Only if the user mentioned them explicitly	Do not include the section if the user did not mention them
Technology stack	Infer from the current repository (package.json, pom.xml, build files, etc.)	Ask the user
Previous ADRs or related documents	Review `docs/adr/` and user context	Ask if there are relevant references to cite

If the ADR is in status Draft or Proposed, the problem and the tentative decision are still required — an ADR without a defined decision makes no sense even if it is a draft.

Conflict validation

Before drafting any new ADR, verify that it does not conflict with existing ADRs in docs/adr/.

What is considered a conflict?

Another decision about the same component, technology or architectural pattern that is already Accepted
A decision that directly contradicts or invalidates an ADR in status Accepted or Proposed
A duplication of scope with an existing ADR, even if the decision is different Process:

Read the titles and section ## Decision of all existing ADRs in docs/adr/
Compare the scope and the proposed decision against the existing ADRs
If there is a conflict:
- Do not draft the ADR
- Inform the user, clearly indicating the conflict
- Include link(s) to the conflicting ADRs:
```
⚠️ Esta decisión entra en conflicto con ADR(s) existentes:
- [ADR-001: Título](docs/adr/ADR-001-slug.md) — <razón del conflicto>
```
- Suggest to the user whether they prefer: (a) updating the existing ADR, (b) creating a new ADR that replaces it by marking the previous one as Superseded, or (c) adjusting the scope so that there is no conflict
If there is no conflict, continue with the creation flow

Flow: Create a new ADR

Infer the sequential number
- List files in docs/adr/ with the pattern ADR-*.md
- Take the highest number and add 1
- If there are none, start at ADR-001
- If the user does not indicate a number, always infer it from the sequence — never ask for it
Build the file name
- Apply the naming conventions: lowercase, kebab-case, short and descriptive
Gather the necessary information (ask the user for whatever is missing)
- Clear title
- Decision-makers
- Relevant tags
- Context, decision and consequences
- Initial status (by default: Draft)
Write the ADR using the template from references/adr-template.md
- Fecha de creación = today
- Última actualización = today
Update docs/adr/README.md
- If it does not exist, create it with a header and an empty list
- Add the new link maintaining ascending order by number:
```
- [ADR-001: Título del ADR](ADR-001-slug.md)
```
- Never reorder or delete existing entries
Confirm by showing the path of the created ADR and the line added to the README

Flow: Update an existing ADR

Identify the file — by number, slug or title
Read the current content in full before editing
Apply the changes requested by the user
Invariant rules for every update:
- Update Última actualización to today's date
- Never modify Fecha de creación
Special rule for status Superseded:
- It is mandatory to add in ## Referencias the reference to the replacement ADR:
```
- Superseded by: [ADR-XXX: Título](docs/adr/ADR-XXX-slug.md)
```
- If the user did not provide the replacement ADR, ask before saving
Update docs/adr/README.md if the ADR title changed
Confirm showing the modified fields

Checklist before writing

Subagent docs-specialist active
Template read from references/adr-template.md
Required information complete (problem, decision, decision-makers, stack) — nothing invented
Number inferred from the sequence in docs/adr/ (never ask the user for it)
Slug in lowercase and kebab-case
Fecha de creación and Última actualización = today (creation) / only Última actualización = today (edition)
Required metadata complete: Status, Creation date, Last update, Decision-makers
If Estado = Superseded: reference to the replacement ADR in ## Referencias
docs/adr/README.md updated with the new link in order
The ADR records the decision and its justification — it does not develop the implementation nor operational instructions for the AI

About this skill