Claude-Code-Workflow/.claude/skills/ccw-loop/templates/understanding-template.md

Understanding Document Template

调试理解演变文档的标准模板。

Template Structure

# Understanding Document

**Session ID**: {{session_id}}
**Bug Description**: {{bug_description}}
**Started**: {{started_at}}

---

## Exploration Timeline

{{#each iterations}}
### Iteration {{number}} - {{title}} ({{timestamp}})

{{#if is_exploration}}
#### Current Understanding

Based on bug description and initial code search:

- Error pattern: {{error_pattern}}
- Affected areas: {{affected_areas}}
- Initial hypothesis: {{initial_thoughts}}

#### Evidence from Code Search

{{#each search_results}}
**Keyword: "{{keyword}}"**
- Found in: {{files}}
- Key findings: {{insights}}
{{/each}}
{{/if}}

{{#if has_hypotheses}}
#### Hypotheses Generated (Gemini-Assisted)

{{#each hypotheses}}
**{{id}}** (Likelihood: {{likelihood}}): {{description}}
- Logging at: {{logging_point}}
- Testing: {{testable_condition}}
- Evidence to confirm: {{confirm_criteria}}
- Evidence to reject: {{reject_criteria}}
{{/each}}

**Gemini Insights**: {{gemini_insights}}
{{/if}}

{{#if is_analysis}}
#### Log Analysis Results

{{#each results}}
**{{id}}**: {{verdict}}
- Evidence: {{evidence}}
- Reasoning: {{reason}}
{{/each}}

#### Corrected Understanding

Previous misunderstandings identified and corrected:

{{#each corrections}}
- ~~{{wrong}}~~ → {{corrected}}
  - Why wrong: {{reason}}
  - Evidence: {{evidence}}
{{/each}}

#### New Insights

{{#each insights}}
- {{this}}
{{/each}}

#### Gemini Analysis

{{gemini_analysis}}
{{/if}}

{{#if root_cause_found}}
#### Root Cause Identified

**{{hypothesis_id}}**: {{description}}

Evidence supporting this conclusion:
{{supporting_evidence}}
{{else}}
#### Next Steps

{{next_steps}}
{{/if}}

---
{{/each}}

## Current Consolidated Understanding

### What We Know

{{#each valid_understandings}}
- {{this}}
{{/each}}

### What Was Disproven

{{#each disproven}}
- ~~{{assumption}}~~ (Evidence: {{evidence}})
{{/each}}

### Current Investigation Focus

{{current_focus}}

### Remaining Questions

{{#each questions}}
- {{this}}
{{/each}}

Template Variables

Variable	Type	Source	Description
session_id	string	state.session_id	会话 ID
bug_description	string	state.debug.current_bug	Bug 描述
iterations	array	从文件解析	迭代历史
hypotheses	array	state.debug.hypotheses	假设列表
valid_understandings	array	从 Gemini 分析	有效理解
disproven	array	从假设状态	被否定的假设

Section Templates

Exploration Section

### Iteration {{N}} - Initial Exploration ({{timestamp}})

#### Current Understanding

Based on bug description and initial code search:

- Error pattern: {{pattern}}
- Affected areas: {{areas}}
- Initial hypothesis: {{thoughts}}

#### Evidence from Code Search

{{#each search_results}}
**Keyword: "{{keyword}}"**
- Found in: {{files}}
- Key findings: {{insights}}
{{/each}}

#### Next Steps

- Generate testable hypotheses
- Add instrumentation
- Await reproduction

Hypothesis Section

#### Hypotheses Generated (Gemini-Assisted)

| ID | Description | Likelihood | Status |
|----|-------------|------------|--------|
{{#each hypotheses}}
| {{id}} | {{description}} | {{likelihood}} | {{status}} |
{{/each}}

**Details:**

{{#each hypotheses}}
**{{id}}**: {{description}}
- Logging at: `{{logging_point}}`
- Testing: {{testable_condition}}
- Confirm: {{evidence_criteria.confirm}}
- Reject: {{evidence_criteria.reject}}
{{/each}}

Analysis Section

### Iteration {{N}} - Evidence Analysis ({{timestamp}})

#### Log Analysis Results

{{#each results}}
**{{id}}**: **{{verdict}}**
- Evidence: \`{{evidence}}\`
- Reasoning: {{reason}}
{{/each}}

#### Corrected Understanding

| Previous Assumption | Corrected To | Reason |
|---------------------|--------------|--------|
{{#each corrections}}
| ~~{{wrong}}~~ | {{corrected}} | {{reason}} |
{{/each}}

#### Gemini Analysis

{{gemini_analysis}}

Consolidated Understanding Section

## Current Consolidated Understanding

### What We Know

{{#each valid}}
- {{this}}
{{/each}}

### What Was Disproven

{{#each disproven}}
- ~~{{this.assumption}}~~ (Evidence: {{this.evidence}})
{{/each}}

### Current Investigation Focus

{{focus}}

### Remaining Questions

{{#each questions}}
- {{this}}
{{/each}}

Resolution Section

### Resolution ({{timestamp}})

#### Fix Applied

- Modified files: {{files}}
- Fix description: {{description}}
- Root cause addressed: {{root_cause}}

#### Verification Results

{{verification}}

#### Lessons Learned

{{#each lessons}}
{{@index}}. {{this}}
{{/each}}

#### Key Insights for Future

{{#each insights}}
- {{this}}
{{/each}}

Consolidation Rules

更新 "Current Consolidated Understanding" 时遵循以下规则:

1. 简化被否定项: 移到 "What Was Disproven"，只保留单行摘要
2. 保留有效见解: 将确认的发现提升到 "What We Know"
3. 避免重复: 不在合并部分重复时间线细节
4. 关注当前状态: 描述现在知道什么，而不是过程
5. 保留关键纠正: 保留重要的 wrong→right 转换供学习

Anti-Patterns

错误示例 (冗余):

## Current Consolidated Understanding

In iteration 1 we thought X, but in iteration 2 we found Y, then in iteration 3...
Also we checked A and found B, and then we checked C...

正确示例 (精简):

## Current Consolidated Understanding

### What We Know
- Error occurs during runtime update, not initialization
- Config value is None (not missing key)

### What Was Disproven
- ~~Initialization error~~ (Timing evidence)
- ~~Missing key hypothesis~~ (Key exists)

### Current Investigation Focus
Why is config value None during update?