ADR Plan: Task Analysis → Architecture Decision Record
Analyze a task, explore the codebase, and produce an ADR with concrete implementation steps.
Phase 1: Analyze
- Read the task description, active plan, or task list
- Explore affected areas of the codebase — do it concurrently for independent modules
- Map blast radius — search for consumers of functions/types/routes being changed
- Identify alternatives worth considering (at least 2)
Do this silently.
Phase 2: Detect ADR Setup
Check if the project has an ADR directory:
ls docs/adr/ || ls adr/ || ls doc/adr/
- Found → use existing directory, detect next number from existing files
- Not found → run
npx adr init en, then proceed
Phase 3: Produce ADR Content
Write the ADR using npx adr new "<title>", then edit the generated file with the following structure:
# ADR-NNNN: [Title]
## Status
Proposed
## Context
[What problem are we solving? What constraints exist?]
## Decision
[What we chose and why]
## Alternatives Considered
| Option | Pros | Cons |
|--------|------|------|
| ... | ... | ... |
## Implementation Steps
### Step 1: [Description]
- **Files:** [files to create/modify]
- **Depends on:** [previous step or "none"]
- **Done when:** [concrete acceptance criteria]
### Step 2: [Description]
...
## Consequences
- [Positive and negative outcomes, tradeoffs accepted]
Guidelines
- Steps are ordered by dependency — each step lists what it depends on
- Steps are parallelizable when independent — note which steps can run concurrently
- Each step has concrete "done when" criteria — no vague outcomes
- Alternatives table is honest — include the option you chose and why others lost
- Keep it short. 1-2 pages max. No padding.
Phase 4: Present to User
Show the ADR content and the file path. The user may:
- Approve → ADR stays as-is
- Adjust → edit and re-present
- Cancel → delete the file
Important
- The ADR is a planning artifact, not documentation for posterity
- Steps should map naturally to work units (a team member could own one or more steps)
- If the task is too simple for an ADR (single file, obvious fix), say so and skip
- Do not write implementation code — this is planning only
1---2name: adr-plan3description: Analyze a task and produce an Architecture Decision Record with implementation steps.4allowed-tools: Agent, AskUserQuestion, Bash(npx adr *), Bash(git diff *), Bash(git log *), Bash(git status *), Bash(ls *), Bash(cat *), Read, Grep, Glob5metadata:6 source: https://skillmd.com/skills/nikiforovall/adr-plan7---89# ADR Plan: Task Analysis → Architecture Decision Record1011Analyze a task, explore the codebase, and produce an ADR with concrete implementation steps.1213## Phase 1: Analyze14151. Read the task description, active plan, or task list162. Explore affected areas of the codebase — do it concurrently for independent modules173. Map blast radius — search for consumers of functions/types/routes being changed184. Identify alternatives worth considering (at least 2)1920Do this silently.2122## Phase 2: Detect ADR Setup2324Check if the project has an ADR directory:2526```27ls docs/adr/ || ls adr/ || ls doc/adr/28```2930- **Found** → use existing directory, detect next number from existing files31- **Not found** → run `npx adr init en`, then proceed3233## Phase 3: Produce ADR Content3435Write the ADR using `npx adr new "<title>"`, then edit the generated file with the following structure:3637```markdown38# ADR-NNNN: [Title]3940## Status41Proposed4243## Context44[What problem are we solving? What constraints exist?]4546## Decision47[What we chose and why]4849## Alternatives Considered50| Option | Pros | Cons |51|--------|------|------|52| ... | ... | ... |5354## Implementation Steps5556### Step 1: [Description]57- **Files:** [files to create/modify]58- **Depends on:** [previous step or "none"]59- **Done when:** [concrete acceptance criteria]6061### Step 2: [Description]62...6364## Consequences65- [Positive and negative outcomes, tradeoffs accepted]66```6768### Guidelines6970- **Steps are ordered by dependency** — each step lists what it depends on71- **Steps are parallelizable when independent** — note which steps can run concurrently72- **Each step has concrete "done when" criteria** — no vague outcomes73- **Alternatives table is honest** — include the option you chose and why others lost74- Keep it short. 1-2 pages max. No padding.7576## Phase 4: Present to User7778Show the ADR content and the file path. The user may:79- **Approve** → ADR stays as-is80- **Adjust** → edit and re-present81- **Cancel** → delete the file8283## Important8485- The ADR is a planning artifact, not documentation for posterity86- Steps should map naturally to work units (a team member could own one or more steps)87- If the task is too simple for an ADR (single file, obvious fix), say so and skip88- Do not write implementation code — this is planning only