Skip to main content
skill CX Codex

adr-decision-extraction — Claude Code skill: install

The adr-decision-extraction skill pulls architectural decisions from chats and session transcripts before ADR writing. It identifies technology choices, trade-offs, and explicit decision tags.

Apache-2.0 144 installs ★ 89 updated 2026-09-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add existential-birds/beagle --skill adr-decision-extraction -a claude-code
Open on GitHub

What adr-decision-extraction does

The skill scans conversation context and returns decisions as JSON. It looks for [ADR] markers, choice statements, trade-off discussions, and problem-to-solution links. Each result can include a short title, the driving problem, the selected option, alternatives, decision drivers, confidence, and surrounding context.

Explicitly tagged decisions receive high confidence. Choices inferred from actions or context receive medium or low confidence, with ambiguity recorded for review. The output is meant to feed an ADR-writing step. It does not create ADR documents, so adr-writing or write-adr is needed for that part.

Use it after a long planning session or when a transcript contains decisions that were never recorded. The skill can also separate clear choices from weaker inferences before documentation starts.

What it helps with

  • extract decisions from a long planning session
  • find technology choices in a discussion
  • capture alternatives and decision drivers
  • separate explicit choices from inference
  • prepare structured input for an ADR

Example prompts for the agent

  • Extract the architectural decisions from this conversation and return them as JSON.
  • Find every decision marked [ADR] in this transcript.
  • Review our planning session, list the chosen options and alternatives, and rate confidence for each decision.

How to install adr-decision-extraction

1Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill adr-decision-extraction -a claude-code

2Manually: put the files in place

~/.claude/skills/adr-decision-extraction/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/adr-decision-extraction/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about adr-decision-extraction

How do I install adr-decision-extraction in Claude Code?

Run npx skills add existential-birds/beagle --skill adr-decision-extraction -a claude-code, then check ~/.claude/skills/adr-decision-extraction/SKILL.md.

What does adr-decision-extraction do?

It extracts architectural decisions from conversations, transcripts, and design discussions. The JSON result records choices, alternatives, drivers, confidence, and context.

Does adr-decision-extraction write ADR documents?

No. It prepares structured decision data for a separate ADR-writing step; use adr-writing or write-adr to create the document.

Source text

SKILL.md · Apache-2.0
---
name: adr-decision-extraction
description: "Use when you need to mine a conversation, session transcript, or design discussion for architectural decisions before writing ADRs. Identifies problem-solution pairs, trade-off debates, technology choices, and explicit \"[ADR]\" tags. Triggers on \"what decisions did we make\", \"extract decisions from this chat\", \"find the choices in our discussion\", or \"summarize architectural decisions\". Also useful after long planning sessions to capture decisions that were made implicitly. Does NOT write ADR documents \u2014 use adr-writing or write-adr for that."
---

# ADR Decision Extraction

Extract architectural decisions from conversation context for ADR generation.

## Detection Signals

| Signal Type | Examples |
|-------------|----------|
| Explicit markers | `[ADR]`, "decided:", "the decision is" |
| Choice patterns | "let's go with X", "we'll use Y", "choosing Z" |
| Trade-off discussions | "X vs Y", "pros/cons", "considering alternatives" |
| Problem-solution pairs | "the problem is... so we'll..." |

## Extraction Rules

### Explicit Tags (Guaranteed Inclusion)

Text marked with `[ADR]` is always extracted:

```
[ADR] Using PostgreSQL for user data storage due to ACID requirements
```

These receive `confidence: "high"` automatically.

### AI-Detected Decisions

Patterns detected without explicit tags require confidence assessment:

| Confidence | Criteria |
|------------|----------|
| **high** | Clear statement of choice with rationale |
| **medium** | Implied decision from action taken |
| **low** | Contextual inference, may need verification |

## Output Format

```json
{
  "decisions": [
    {
      "title": "Use PostgreSQL for user data",
      "problem": "Need ACID transactions for financial records",
      "chosen_option": "PostgreSQL",
      "alternatives_discussed": ["MongoDB", "SQLite"],
      "drivers": ["ACID compliance", "team familiarity"],
      "confidence": "high",
      "source_context": "Discussion about database selection in planning phase"
    }
  ]
}
```

### Field Definitions

| Field | Required | Description |
|-------|----------|-------------|
| `title` | Yes | Concise decision summary |
| `problem` | Yes | Problem or context driving the decision |
| `chosen_option` | Yes | The selected solution or approach |
| `alternatives_discussed` | No | Other options mentioned (empty array if none) |
| `drivers` | No | Factors influencing the decision |
| `confidence` | Yes | `high`, `medium`, or `low` |
| `source_context` | No | Brief description of where decision appeared |

## Extraction Workflow

1. **Scan for explicit markers** - Find all `[ADR]` tagged content
2. **Identify choice patterns** - Look for decision language
3. **Extract trade-off discussions** - Capture alternatives and reasoning
4. **Assess confidence** - Rate each non-explicit decision
5. **Capture context** - Note surrounding discussion for ADR writer

## Hard gates

Run these **in order** after the workflow above and **before** returning output. Each step has an objective pass condition.

1. **Explicit `[ADR]` inventory** — Capture every `[ADR]` segment from the full source (verbatim in working notes). **Pass:** a second pass over the same source adds no new `[ADR]` blocks.
2. **De-duplicate** — Merge or drop inferred rows that repeat an explicit `[ADR]` decision (see [Merge Related Decisions](#merge-related-decisions)). **Pass:** at most one row per distinct decision.
3. **Schema validity** — Serialized JSON matches [Output Format](#output-format) and [Field Definitions](#field-definitions). **Pass:** parse succeeds; every `decisions[]` item has non-empty `title`, `problem`, `chosen_option`; `confidence` ∈ {`high`,`medium`,`low`}; `alternatives_discussed` is an array (use `[]` if none); other optional fields per table.
4. **Low-confidence audit** — For any `confidence: "low"`, `source_context` states what was missing, weak, or contradictory. **Pass:** a reader can see why the rating is not higher.

## Pattern Examples

### High Confidence

```
"We decided to use Redis for caching because of its sub-millisecond latency
and native TTL support. Memcached was considered but lacks persistence."
```

Extracts:
- Title: Use Redis for caching
- Problem: Need fast caching with TTL
- Chosen: Redis
- Alternatives: Memcached
- Drivers: sub-millisecond latency, native TTL, persistence
- Confidence: high

### Medium Confidence

```
"Let's go with TypeScript for the frontend since we're already using it
in the backend."
```

Extracts:
- Title: Use TypeScript for frontend
- Problem: Language choice for frontend
- Chosen: TypeScript
- Alternatives: (none stated)
- Drivers: consistency with backend
- Confidence: medium

### Low Confidence

```
"The API seems to be working well with REST endpoints."
```

Extracts:
- Title: REST API architecture
- Problem: API design approach
- Chosen: REST
- Alternatives: (none stated)
- Drivers: (none stated)
- Confidence: low

## Best Practices

### Context Capture

Always capture sufficient context for the ADR writer:
- What was the discussion about?
- Who was involved (if known)?
- What prompted the decision?

### Merge Related Decisions

If multiple statements relate to the same decision, consolidate them:
- Combine alternatives from different mentions
- Aggregate drivers
- Use highest confidence level

### Flag Ambiguity

When decisions are unclear or contradictory:
- Note the ambiguity in `source_context`
- Set confidence to `low`
- Include all interpretations if multiple exist

## When to Use This Skill

- Analyzing session transcripts for ADR generation
- Reviewing conversation history for documentation
- Extracting decisions from design discussions
- Preparing input for ADR writing tools

© existential-birds · Apache-2.0 · existential-birds/beagle

Similar skills

All skills for Agent setup: memory, context, orchestration →
adr-create ruvnet adr-create — a skill for Claude Code and five other platforms creates numbered Architecture Decision Records, registers them in AgentDB graph, and links related decisions via semantic search. Runs on a command with the decision title. CX Codex +1 743installs architecture-decision Donchitos architecture-decision walks the agent through drafting an ADR: context, alternatives weighed, consequences. Useful when a technical decision needs a written record. CX Codex +1 679installs create-adr Tech Leads Club - github.com/tech-leads-club create-adr documents settled architectural choices directly in your repository. It captures context and consequences so future teammates understand past trade-offs. CX Codex +1 ★ 7,191repo stars adr-drafting giuseppe-trisciuoglio adr-drafting drafts Architecture Decision Records for significant technical choices, matching existing repository conventions. Helpful when documenting database migrations or service boundaries. CX Codex +1 3,700installs develop-adr product-on-purpose develop-adr — a skill that writes Architecture Decision Records: the context, the choice, and what it costs you later. Useful when the team picks a database, framework or pattern. CX Codex +1 886installs architecture-decision-records Seth Hobson Writes and maintains Architecture Decision Records (ADRs) — documents capturing technical decisions. Runs when you need to record a database choice, framework adoption or integration pattern. CX Codex +1 22,036installs

From the same set68

The whole set →
explanation-docs explanation-docs — a skill for writing conceptual docs that explain how systems work and why they were designed that way. Use it for architecture notes, design rationale, and onboarding. CX Codex +1 152installs llm-artifacts-detection llm-artifacts-detection detects leftover cruft from AI coding assistants: dead code, duplicate test helpers, redundant wrapper classes, and obvious comments. CX Codex +1 151installs go-testing-code-review go-testing-code-review reviews Go test files: table-driven cases, assertion messages, parallelism and coverage. Each finding is pinned to a file and line. CX Codex +1 148installs pydantic-ai-testing pydantic-ai-testing is a Claude Code skill for testing PydanticAI agents with mocked model responses, recorded API interactions, and inline snapshots. CX Codex +1 146installs deepagents-implementation deepagents-implementation is a Claude Code skill with recipes for building agents on Deep Agents: create_deep_agent, file backends, subagents and LangGraph streaming. CX Codex +1 142installs llm-judge llm-judge ranks two or more implementations of the same task against a spec file: facts first, then scores across five dimensions, then a report naming the winner. CX Codex +1 141installs pydantic-ai-dependency-injection pydantic-ai-dependency-injection — a skill for wiring databases, API clients, and user context into PydanticAI agents with RunContext and deps_type. CX Codex +1 141installs watchos-code-review The watchos-code-review skill reviews watchOS code for lifecycle, complications, WatchConnectivity, and resource limits. Use it when checking WatchKit or SwiftUI app code. CX Codex +1 137installs

Project sponsors

Companies that keep this analytics open