What happens if there are no explicit ADR tags?

The system will apply AI-detected decisions using language cues and assign a confidence level based on clarity.

How are confidence levels determined?

High when there is a clear statement with rationale; medium for implied decisions; low for ambiguous or contextual inferences.

Can it merge multiple mentions into a single ADR?

Yes, related mentions are consolidated, with alternatives, drivers, and source_context combined for a complete ADR.

adr-decision-extraction

Scanned

npx machina-cli add skill existential-birds/beagle/adr-decision-extraction --openclaw

Files (1)

SKILL.md

4.2 KB

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

Source

git clone https://github.com/existential-birds/beagle/blob/main/plugins/beagle-analysis/skills/adr-decision-extraction/SKILL.md

View on GitHub

Overview

Extract architectural decisions from conversation context to generate ADRs. It detects explicit markers like [ADR], choice language, and trade-off discussions, then outputs structured decision records. This helps teams document why decisions were made and how alternatives were considered.

How This Skill Works

The tool scans transcripts for explicit ADR markers and patterns that signal a decision. It classifies each finding by confidence level and outputs a structured object with title, problem, chosen_option, alternatives_discussed, drivers, confidence, and source_context.

When to Use It

When analyzing session transcripts to generate ADRs for documentation.
When explicit ADR markers such as [ADR] or phrases like decided appear in chat logs.
When evaluating trade-off discussions (X vs Y) and extracting the rationale.
When you need confidence-scored decisions (high, medium, low) for audits.
When you want to preserve source_context for traceability of decisions.

Quick Start

Step 1: Scan transcripts for explicit ADR markers and decision language.
Step 2: Classify each decision with a confidence level (high, medium, low) based on clarity.
Step 3: Output a structured ADR record with title, problem, chosen_option, alternatives_discussed, drivers, confidence, and source_context.

Best Practices

Context Capture: document the discussion question, participants, and prompt that led to the decision.
Merge Related Decisions: consolidate multiple mentions into a single ADR, combining alternatives and drivers.
Flag Ambiguity: note uncertain or contradictory decisions for follow-up.
Capture drivers and alternatives: list the reasons and other options discussed.
Preserve source_context: include surrounding discussion to aid writer.

Example Use Cases

Use PostgreSQL for user data storage due to ACID requirements; problem: need reliable transactions; chosen: PostgreSQL; alternatives: MongoDB, SQLite; drivers: ACID compliance, team familiarity; confidence: high; source_context: Planning phase discussion about database selection.
Use Redis for caching due to sub-millisecond latency and TTL support; problem: need fast caching with TTL; chosen: Redis; alternatives: Memcached; drivers: latency, TTL support, persistence; confidence: high; source_context: Caching strategy meeting.
Frontend language TypeScript to align frontend with backend; problem: language consistency across stack; chosen: TypeScript; drivers: consistency with backend; confidence: medium; source_context: Architecture alignment.
API style REST API; problem: API design approach; chosen: REST; drivers: none stated; confidence: low; source_context: API planning meeting.
Data model for analytics selected PostgreSQL for analytics queries; problem: analytics performance and schema flexibility; chosen: PostgreSQL; alternatives: none stated; drivers: familiarity, SQL richness; confidence: medium; source_context: Data platform discussion.

Frequently Asked Questions

Add this skill to your agents