Architecture Decision Records
Create, update, or compact ADRs with cross-validated research.
Language
Detect from user's message. Load the matching template:
- Spanish → references/template-es.md
- English → references/template-en.md
ALL output in the detected language.
Modes
Parse $ARGUMENTS:
| Pattern | Mode |
|---|---|
crear/create <slug> |
Create — new ADR |
actualizar/update <path> |
Update — add log entry |
compactar/compact <path> |
Compact — reformat verbose ADR |
| No args or just a topic | Create — infer slug |
Create
- Extract context from conversation. Only ask if the topic or sources to check are unclear.
- Launch
source-researcheragent with: topic, sources to check, key terms. Instruct it to define domain concepts. - Draft ADR using research summary + language template. Context section must define domain concepts first, then the situation. Show draft before writing.
- Write to
docs/adr/YYYY-MM-DD-<slug>.md. Create directory if needed. - If researcher found discrepancies, list them as questions (conversation output, not in the ADR file).
Update
- Read existing ADR at given path.
- Extract what was discussed/decided from conversation. Ask only if unclear.
- If update involves technical decisions, optionally launch
source-researcherto validate against code. - Append entry under Log/Registro with today's date. If the decision changed, update Decision and Status sections too.
Compact
- Read verbose ADR. Identify decisions buried in noise, redundancies, missing sections.
- Rewrite following language template: preserve all decisions and rationale, discard meeting logistics, consolidate pros/cons into Alternatives, move chronological details to Log, keep technical references.
- Show what changed before writing.
Rules
- Context must be grounded in sources, not assumptions
- Alternatives must have pros AND cons
- Log is append-only
- If uncertain, it's an open question — never a stated fact
- Max ~200 lines per ADR; split if longer