adr-decision-extraction

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADR Decision Extraction

ADR决策提取

Extract architectural decisions from conversation context for ADR generation.

从对话语境中提取架构决策以生成ADR。

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

信号类型	示例
明确标记	`[ADR]` , "decided:", "the decision is"
选择模式	"let's go with X", "we'll use Y", "choosing Z"
权衡讨论	"X vs Y", "pros/cons", "considering alternatives"
问题-解决方案对	"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.

标记有

[ADR]

的文本总会被提取：

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

这些内容会自动被标记为

confidence: "high"

。

AI-Detected Decisions

AI检测到的决策

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

未带有明确标签但被检测到模式的内容需要进行置信度评估：

置信度	标准
high	带有理由的明确选择声明
medium	从已采取的行动中推断出的决策
low	语境推断，可能需要验证

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"
    }
  ]
}

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

字段	是否必填	描述
`title`	是	简洁的决策摘要
`problem`	是	推动决策的问题或背景
`chosen_option`	是	选定的解决方案或方法
`alternatives_discussed`	否	提及的其他选项（若无则为空数组）
`drivers`	否	影响决策的因素
`confidence`	是	`high` 、 `medium` 或 `low`
`source_context`	否	决策出现位置的简要描述

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

扫描明确标记 - 查找所有带有
```
[ADR]
```
标签的内容
识别选择模式 - 寻找决策相关表述
提取权衡讨论 - 捕获备选方案和推理过程
评估置信度 - 为所有非明确标记的决策评级
捕获语境 - 记录ADR撰写者所需的周边讨论内容

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

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

提取结果：

标题：使用Redis进行缓存
问题：需要具备TTL功能的高速缓存
选定方案：Redis
备选方案：Memcached
驱动因素：亚毫秒级延迟、原生TTL支持、持久化能力
置信度：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

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

提取结果：

标题：前端使用TypeScript
问题：前端语言选择
选定方案：TypeScript
备选方案：（未提及）
驱动因素：与后端技术栈一致
置信度：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

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

提取结果：

标题：REST API架构
问题：API设计方案选择
选定方案：REST
备选方案：（未提及）
驱动因素：（未提及）
置信度：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?

始终为ADR撰写者捕获足够的语境：

讨论的主题是什么？
参与人员（若已知）？
决策的触发因素是什么？

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

当决策不明确或存在矛盾时：

在
```
source_context
```
中注明歧义
将置信度设置为
```
low
```
若存在多种解读，需全部纳入

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

分析会话记录以生成ADR
回顾对话历史以进行文档编制
从设计讨论中提取决策
为ADR撰写工具准备输入内容