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

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

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:

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

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

### 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 - Overall tutorial organization (uses concept explanations)
• 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