ADR Decision Extraction#

Extract architectural decisions from conversation context for ADR generation.

Detection Signals#

Signal TypeExamplesExplicit 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:

text

[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:

ConfidenceCriteriahighClear statement of choice with rationalemediumImplied decision from action takenlowContextual 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#

FieldRequiredDescriptiontitleYesConcise decision summaryproblemYesProblem or context driving the decisionchosen_optionYesThe selected solution or approachalternatives_discussedNoOther options mentioned (empty array if none)driversNoFactors influencing the decisionconfidenceYeshigh, medium, or low``source_contextNoBrief 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). Pass: at most one row per distinct decision.
3. Schema validity — Serialized JSON matches Output Format and 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#

text

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

text

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

text

"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