# Backtrail Create Adr

> Create a Proposed ADR from decision input

- Skill: `ivan-gerasimov-1/backtrail-create-adr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ivan-gerasimov-1/backtrail-create-adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivan-gerasimov-1/backtrail-create-adr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ivan-gerasimov-1 (https://skillmd.com/u/ivan-gerasimov-1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ivan-gerasimov-1/backtrail-create-adr

---


## Purpose

Create ADR documentation only. Inspect code as needed, but write only ADR docs and `.backtrail/adl.md`.

ADR records durable decisions that constrain future work: architecture, repository structure, public contracts, generated output, build/test workflow, dependencies, or reversibility.

## Input

Use the text after this skill invocation as the decision brief.

## Resources

- Use `assets/adr-template.md` as the ADR template.

## Workflow

1. If the brief does not identify a decision, ask for the decision topic before creating files.
2. Read `.backtrail/adl.md`, relevant ADRs, docs, and code. If `.backtrail/adl.md` or `.backtrail/adrs/` is missing, plan to create it.
3. Apply the ADR gate before creating files.
   - Create ADRs only for durable decisions that constrain future work or change architecture, repository structure, public contracts, generated output, build/test workflow, dependencies, or reversibility.
   - Prefer commit, issue, PR note, or CHANGE for bug fixes, local refactors, tests, existing ADR implementation details, copy changes, dependency patches, or task-local choices.
   - If the gate fails, stop and explain why a non-ADR artifact fits better. Do not create ADR files.
4. Determine the ADR number.
   - Use an explicit number only when it appears at the start of input, after optional whitespace.
   - Supported prefixes: `ADR-014`, `ADR 014`, `#14`, `#014`, `014`, `14`.
   - Normalize to five digits: `#14 Split decisions` -> `ADR-00014`, `.backtrail/adrs/adr-00014-split-decisions.md`.
   - Do not scan the input body for ADR numbers.
   - If no starting number exists, use the highest `ADR-NNNNN` from `.backtrail/adl.md` + 1.
   - If `.backtrail/adl.md` is missing, create it and start at `ADR-00001` unless the brief has an explicit starting number.
5. Stop if `.backtrail/adrs/adr-NNNNN-title-slug.md` already exists.
6. Assess whether dedicated reversibility detail is required. Require it when the decision:
   - destroys or irreversibly transforms data;
   - creates a public contract or compatibility break;
   - changes authentication, authorization, security, billing, or financial behavior;
   - requires a migration, compatibility window, coordinated deployment, or manual recovery; or
   - would be materially costly, risky, or operationally complex to reverse.
7. Present rough approach before writing.
   - decision
   - key rationale
   - independent risks, when useful
   - reversibility assessment and, only when a trigger applies, the reversal or recovery plan
   - related ADRs, if any
8. Ask only questions that change decision, scope, compatibility, verification, or a required reversal or recovery plan.
9. Create `.backtrail/adrs/adr-NNNNN-title-slug.md` from `assets/adr-template.md`.
   - Add a dedicated `## Reversibility` section only when a trigger in step 6 applies.
   - Omit the section rather than filling it with generic text when no trigger applies.
   - Keep independently useful risk analysis in the relevant section without adding `## Reversibility` solely for that analysis.
10. Save the ADR and its `.backtrail/adl.md` entry with status `Proposed`.
11. Ask whether to promote to `Accepted`.
    - Use Yes/No buttons when `request_user_input` is available.
    - `Yes`: update status in the ADR and `.backtrail/adl.md`.
    - `No`: leave `Proposed`.
12. Ask whether to proceed with creating a CHANGE record.
    - Use Yes/No buttons when `request_user_input` is available.
    - `Yes`: use `backtrail-create-change`.
    - `No`: skip to the next step.
13. Stop after docs/status changes. Do not implement code.

## Question UX

- Use `request_user_input` when available for two or three meaningful choices.
- For yes/no decisions, present `Yes` and `No` choices.
- If `request_user_input` is unavailable, ask one concise plain-text question with numbered choices.
- Do not claim that a skill can switch modes or force button rendering.

## Guardrails

- Do not change implementation code, non-ADR templates, configs, or tests.
- Do not overwrite existing ADR files.
- Do not create CHANGE records; use the `backtrail-create-change` skill for implementation plans.
- Do not treat numbers in input body as ADR numbers.
- Superseding another ADR requires explicit user confirmation.