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

{ "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

• Scan for explicit markers - Find all [ADR] tagged content

• Identify choice patterns - Look for decision language

• Extract trade-off discussions - Capture alternatives and reasoning

• Assess confidence - Rate each non-explicit decision

• Capture context - Note surrounding discussion for ADR writer

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