Adr Decision Extraction

Use when you need to mine a conversation, session transcript, or design discussion for architectural decisions before writing ADRs. Identifies problem-soluti...

Security Scan

The skill's requirements and instructions are consistent with its stated purpose of extracting architectural decisions from provided transcripts; it requests no extra permissions or installs.

Purpose & Capability

Name/description align with the SKILL.md: it describes detecting decision language, extracting problem/solution pairs, and emitting a structured JSON. No unrelated binaries, env vars, or install steps are requested.

Instruction Scope

The instructions restrict work to scanning the provided conversation text and include concrete extraction rules and schema validation gates. One minor concern: guidance to capture "who was involved (if known)" and to inspect the "full source" could encourage including participant identities or metadata beyond the transcript body — this is not required by the core task but may lead to collecting PII if the agent has access to metadata.

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is written to disk or fetched during install.

Credentials

No environment variables, credentials, or config paths are requested. The declared scope is proportionate to extracting decisions from text input.

Persistence & Privilege

always is false and the skill does not request persistent presence or modification of other skills. Autonomous invocation is allowed by platform default but is not combined with other red flags.

Assessment

This skill appears coherent and limited to analyzing transcripts. Before installing, ensure the agent only receives transcripts you intend to share (redact PII if necessary), confirm the agent has explicit access rights to those transcripts, and review any low-confidence extractions before including them in ADRs. The skill's prompt to record "who was involved" can surface identities — if you need to avoid that, instruct the agent not to capture participant metadata. Finally, validate outputs against the hard-gates (schema and low-confidence audit) before publishing ADRs.

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

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

"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