gh-yaleh-meta-cc-claude/skills/documentation-management/templates/concept-explanation.md

# Template: Concept Explanation

**Purpose**: Structured template for explaining individual technical concepts clearly
**Based on**: Example-driven explanation pattern from BAIME guide
**Validated**: Multiple concepts in BAIME guide, ready for reuse

---

## When to Use This Template

✅ **Use for**:
- Abstract technical concepts that need clarification
- Framework components or subsystems
- Design patterns or architectural concepts
- Any concept where "what" and "why" both matter

❌ **Don't use for**:
- Simple definitions (use glossary format)
- Step-by-step instructions (use procedure template)
- API reference (use API docs format)

---

## Template Structure

```markdown
### [Concept Name]

**Definition**: [1-2 sentence explanation in plain language]

**Why it matters**: [Practical reason or benefit]

**Key characteristics**:
- [Characteristic 1]
- [Characteristic 2]
- [Characteristic 3]

**Example**:
```[language]
[Concrete example showing concept in action]
```

**Explanation**: [How example demonstrates concept]

**Related concepts**:
- [Related concept 1]: [How they relate]
- [Related concept 2]: [How they relate]

**Common misconceptions**:
- ❌ [Misconception]: [Why it's wrong]
- ❌ [Misconception]: [Correct understanding]

**Further reading**: [Link to detailed reference]
```

---

## Section Guidelines

### Definition
- **Length**: 1-2 sentences maximum
- **Language**: Plain language, avoid jargon
- **Focus**: What it is, not what it does (that comes in "Why it matters")
- **Test**: Could a beginner understand this?

**Good example**:
> **Definition**: Progressive disclosure is a content structuring pattern that reveals complexity incrementally, starting simple and building to advanced topics.

**Bad example** (too technical):
> **Definition**: Progressive disclosure implements a hierarchical information architecture with lazy evaluation of cognitive load distribution across discretized complexity strata.

### Why It Matters
- **Length**: 1-2 sentences
- **Focus**: Practical benefit or problem solved
- **Avoid**: Vague statements like "improves quality"
- **Include**: Specific outcome or metric if possible

**Good example**:
> **Why it matters**: Prevents overwhelming new users while still providing depth for experts, increasing completion rates from 20% to 80%.

**Bad example** (vague):
> **Why it matters**: Makes documentation better and easier to use.

### Key Characteristics
- **Count**: 3-5 bullet points
- **Format**: Observable properties or behaviors
- **Purpose**: Help reader recognize concept in wild
- **Avoid**: Repeating definition

**Good example**:
> - Each layer is independently useful
> - Complexity increases gradually
> - Reader can stop at any layer and have learned something valuable
> - Clear boundaries between layers (headings, whitespace)

### Example
- **Type**: Concrete code, diagram, or scenario
- **Size**: Small enough to understand quickly (< 10 lines code)
- **Relevance**: Directly demonstrates the concept
- **Completeness**: Should be runnable/usable if possible

**Good example**:
```markdown
# Quick Start (Layer 1)

Install and run:
```bash
npm install tool
tool --quick-start
```

# Advanced Configuration (Layer 2)

All options:
```bash
tool --config-file custom.yml --verbose --parallel 4
```
```

### Explanation
- **Length**: 1-3 sentences
- **Purpose**: Connect example back to concept definition
- **Format**: "Notice how [aspect of example] demonstrates [concept characteristic]"

**Good example**:
> **Explanation**: Notice how the Quick Start shows a single command with no options (Layer 1), while Advanced Configuration shows all available options (Layer 2). This demonstrates progressive disclosure—simple first, complexity later.

### Related Concepts
- **Count**: 2-4 related concepts
- **Format**: Concept name + relationship type
- **Purpose**: Help reader build mental model
- **Types**: "complements", "contrasts with", "builds on", "prerequisite for"

**Good example**:
> - Example-driven explanation: Complements progressive disclosure (each layer needs examples)
> - Reference documentation: Contrasts with progressive disclosure (optimized for lookup, not learning)

### Common Misconceptions
- **Count**: 2-3 most common misconceptions
- **Format**: ❌ [Wrong belief] → ✅ [Correct understanding]
- **Purpose**: Preemptively address confusion
- **Source**: User feedback or anticipated confusion

**Good example**:
> - ❌ "Progressive disclosure means hiding information" → ✅ All information is accessible, just organized by complexity level
> - ❌ "Quick start must include all features" → ✅ Quick start shows minimal viable path; features come later

---

## Variations

### Variation 1: Abstract Concept (No Code)

For concepts without code examples (design principles, methodologies):

```markdown
### [Concept Name]

**Definition**: [Plain language explanation]

**Why it matters**: [Practical benefit]

**In practice**:
- **Scenario**: [Describe situation]
- **Without concept**: [What happens without it]
- **With concept**: [What changes with it]
- **Outcome**: [Measurable result]

**Example**: [Story or scenario demonstrating concept]

**Related concepts**: [As above]
```

### Variation 2: Component/System

For explaining system components:

```markdown
### [Component Name]

**Purpose**: [What role it plays in system]

**Responsibilities**:
- [Responsibility 1]
- [Responsibility 2]
- [Responsibility 3]

**Interfaces**:
- **Inputs**: [What it receives]
- **Outputs**: [What it produces]
- **Dependencies**: [What it requires]

**Example usage**:
```[language]
[Code showing component in action]
```

**Related components**: [How it connects to other parts]
```

### Variation 3: Pattern

For design patterns:

```markdown
### [Pattern Name]

**Problem**: [What problem pattern solves]

**Solution**: [How pattern solves it]

**Structure**:
```
[Diagram or code structure]
```

**When to use**:
- ✅ [Use case 1]
- ✅ [Use case 2]

**When NOT to use**:
- ❌ [Anti-pattern 1]
- ❌ [Anti-pattern 2]

**Example**:
```[language]
[Pattern implementation]
```

**Trade-offs**:
- **Pros**: [Benefits]
- **Cons**: [Costs]
```

---

## Quality Checklist

Before publishing concept explanation:

**Clarity**:
- [ ] Definition is 1-2 sentences in plain language
- [ ] Example is concrete and understandable
- [ ] No undefined jargon
- [ ] Tested on someone unfamiliar with concept

**Completeness**:
- [ ] "Why it matters" answers "so what?"
- [ ] Key characteristics help identify concept
- [ ] Example directly demonstrates concept
- [ ] Related concepts provide context

**Accuracy**:
- [ ] Example is correct and runnable (if code)
- [ ] Characteristics are observable
- [ ] Misconceptions are actually common
- [ ] Links work and are relevant

**Usability**:
- [ ] Can be understood in < 2 minutes
- [ ] Example is copy-paste ready (if code)
- [ ] Structure follows template
- [ ] Visual hierarchy clear (headings, bold, lists)

---

## Example Usage

### Input: Need to explain "Dual-layer value functions"

**Step 1**: Apply template

```markdown
### Dual-Layer Value Functions

**Definition**: A quantitative evaluation framework that measures both domain-specific task quality (V_instance) and methodology transferability quality (V_meta) independently.

**Why it matters**: Enables objective assessment of both "did we solve the problem?" and "can others reuse our solution?", preventing local optimization where methodology works once but isn't reusable.

**Key characteristics**:
- Two independent value functions calculated each iteration
- Each function has 4 weighted components
- Both must reach ≥ 0.80 threshold for convergence
- Prevents premature convergence on either dimension alone

**Example**:
```
Iteration 0:
V_instance = 0.66 (documentation quality)
  - Accuracy: 0.70
  - Completeness: 0.60
  - Usability: 0.65
  - Maintainability: 0.70

V_meta = 0.36 (methodology quality)
  - Completeness: 0.25 (no templates yet)
  - Effectiveness: 0.35 (modest speedup)
  - Reusability: 0.40 (patterns identified)
  - Validation: 0.45 (metrics defined)
```

**Explanation**: Notice how V_instance (task quality) can be high while V_meta (methodology quality) is low. This prevents declaring "success" when documentation is good but methodology isn't reusable.

**Related concepts**:
- Convergence criteria: Uses dual-layer values to determine when iteration complete
- Value optimization: Mathematical framework underlying value functions
- Component scoring: Each value function breaks into 4 components

**Common misconceptions**:
- ❌ "Higher V_instance means methodology is good" → ✅ Need high V_meta for reusable methodology
- ❌ "V_meta is subjective" → ✅ Each component has concrete metrics (coverage %, transferability %)
```

**Step 2**: Review with checklist

**Step 3**: Test on unfamiliar reader

**Step 4**: Refine based on feedback

---

## Real Examples from BAIME Guide

### Example 1: OCA Cycle

```markdown
### OCA Cycle

**Definition**: Observe-Codify-Automate is an iterative framework for extracting empirical patterns from practice and converting them into automated checks.

**Why it matters**: Converts implicit knowledge into explicit, testable, automatable form—enabling methodology improvement at the same pace as software development.

**Key phases**:
- **Observe**: Collect empirical data about current practices
- **Codify**: Extract patterns and document methodologies
- **Automate**: Convert methodologies to automated checks
- **Evolve**: Apply methodology to itself

**Example**:
Observe: Analyze git history → Notice 80% of commits fix test failures
Codify: Pattern: "Run tests before committing"
Automate: Pre-commit hook that runs tests
Evolve: Apply OCA to improving the OCA process itself
```

✅ Follows template structure
✅ Clear definition + practical example
✅ Demonstrates concept through phases

### Example 2: Convergence Criteria

```markdown
### Convergence Criteria

**Definition**: Mathematical conditions that determine when methodology development iteration should stop, preventing both premature convergence and infinite iteration.

**Why it matters**: Provides objective "done" criteria instead of subjective judgment, typically converging in 3-7 iterations.

**Four criteria** (all must be met):
- System stable: No agent changes for 2+ iterations
- Dual threshold: V_instance ≥ 0.80 AND V_meta ≥ 0.80
- Objectives complete: All planned work finished
- Diminishing returns: ΔV < 0.02 for 2+ iterations

**Example**:
Iteration 5: V_i=0.81, V_m=0.82, no agent changes, ΔV=0.01
Iteration 6: V_i=0.82, V_m=0.83, no agent changes, ΔV=0.01
→ Converged ✅ (all criteria met)
```

✅ Clear multi-part concept
✅ Concrete example with thresholds
✅ Demonstrates decision logic

---

## Validation

**Usage in BAIME guide**: 6 core concepts explained
- OCA Cycle
- Dual-layer value functions
- Convergence criteria
- Meta-agent
- Capabilities
- Agent specialization

**Pattern effectiveness**:
- ✅ Each concept has definition + example
- ✅ Clear "why it matters" for each
- ✅ Examples concrete and understandable

**Transferability**: High (applies to any concept explanation)

**Confidence**: Validated through multiple uses in same document

**Next validation**: Apply to concepts in different domain

---

## Related Templates

- [tutorial-structure.md](tutorial-structure.md) - Overall tutorial organization (uses concept explanations)
- [example-walkthrough.md](example-walkthrough.md) - Detailed examples (complements concept explanations)

---

**Status**: ✅ Ready for use | Validated in 1 context (6 concepts) | High confidence
**Maintenance**: Update based on user comprehension feedback