Files

Zhongwei Li fab98d059b Initial commit

2025-11-30 09:07:22 +08:00

10 KiB

Raw Blame History

Pattern: Example-Driven Explanation

Status: ✅ Validated (2+ uses) Domain: Documentation Transferability: Universal (applies to all conceptual documentation)

Problem

Abstract concepts are hard to understand without concrete instantiation. Theoretical explanations alone don't stick—readers need to see concepts in action.

Symptoms:

Users say "I understand the words but not what it means"
Concepts explained but users can't apply them
Documentation feels academic, not practical
No clear path from theory to practice

Solution

Pair every abstract concept with a concrete example. Show don't tell.

Pattern: Abstract Definition + Concrete Example = Clarity

Key Principle: The example should be immediately recognizable and relatable. Prefer real-world code/scenarios over toy examples.

Implementation

Basic Structure

## Concept Name

**Definition**: [Abstract explanation of what it is]

**Example**: [Concrete instance showing concept in action]

**Why It Matters**: [Impact or benefit in practice]

Example: From BAIME Guide

Concept: Dual Value Functions

Definition (Abstract):

BAIME uses two independent value functions:
- V_instance: Domain-specific deliverable quality
- V_meta: Methodology quality and reusability

Example (Concrete):

Testing Methodology Experiment:

V_instance (Testing Quality):
- Coverage: 0.85 (85% code coverage achieved)
- Quality: 0.80 (TDD workflow, systematic patterns)
- Maintainability: 0.90 (automated test generation)
→ V_instance = (0.85 + 0.80 + 0.90) / 3 = 0.85

V_meta (Methodology Quality):
- Completeness: 0.80 (patterns extracted, automation created)
- Reusability: 0.85 (89% transferable to other Go projects)
- Validation: 0.90 (validated across 3 projects)
→ V_meta = (0.80 + 0.85 + 0.90) / 3 = 0.85

Why It Matters: Dual metrics ensure both deliverable quality AND methodology reusability, not just one.

When to Use

Use This Pattern For

✅ Abstract concepts (architecture patterns, design principles) ✅ Technical formulas (value functions, algorithms) ✅ Theoretical frameworks (BAIME, OCA cycle) ✅ Domain-specific terminology (meta-agent, capabilities) ✅ Multi-step processes (iteration workflow, convergence)

Don't Use For

❌ Concrete procedures (installation steps, CLI commands) - these ARE examples ❌ Simple definitions (obvious terms don't need examples) ❌ Lists and enumerations (example would be redundant)

Validation Evidence

Use 1: BAIME Core Concepts (Iteration 0)

6 concepts explained: Value Functions, OCA Cycle, Meta-Agent, Agents, Capabilities, Convergence
Each concept: Abstract definition + Concrete example
Pattern emerged naturally from complexity management
Result: Users understand abstract BAIME framework through testing methodology example

Use 2: Quick Reference Template (Iteration 2)

Command documentation pattern: Syntax + Example + Output
Every command paired with concrete usage example
Decision trees show abstract logic + concrete scenarios
Result: Reference docs provide both structure and instantiation

Use 3: Error Recovery Example (Iteration 3)

Each iteration step: Abstract progress + Concrete value scores
Diagnostic workflow: Pattern description + Actual error classification
Recovery patterns: Concept + Implementation code
Result: Abstract methodology becomes concrete through domain-specific examples

Pattern Validated: ✅ 3 uses across BAIME guide creation, template development, second domain example

Best Practices

1. Example First, Then Abstraction

Good (Example → Pattern):

**Example**: Error Recovery Iteration 1
- Created 8 diagnostic workflows
- Expanded taxonomy to 13 categories
- V_instance jumped from 0.40 to 0.62 (+0.22)

**Pattern**: Rich baseline data accelerates convergence.
Iteration 1 progress was 2x typical because historical errors
provided immediate validation context.

Less Effective (Pattern → Example):

**Pattern**: Rich baseline data accelerates convergence.

**Example**: In error recovery, having 1,336 historical errors
enabled faster iteration.

Why: Leading with concrete example makes abstract pattern immediately grounded.

2. Use Real Examples, Not Toy Examples

Good (Real):

**Example**: meta-cc JSONL output
```json
{"TurnCount": 2676, "ToolCallCount": 1012, "ErrorRate": 0}


**Less Effective** (Toy):
```markdown
**Example**: Simple object
```json
{"field1": "value1", "field2": 123}


**Why**: Real examples show actual complexity and edge cases users will encounter.

### 3. Multiple Examples Show Transferability

**Single Example**: Shows pattern works once
**2-3 Examples**: Shows pattern transfers across contexts
**5+ Examples**: Shows pattern is universal

**BAIME Guide**: 10+ jq examples in JSONL reference prove pattern universality

### 4. Example Complexity Matches Concept Complexity

**Simple Concept** → Simple Example
- "JSONL is newline-delimited JSON" → One-line example: `{"key": "value"}\n`

**Complex Concept** → Detailed Example
- "Dual value functions with independent scoring" → Full calculation breakdown with component scores

### 5. Annotate Examples

**Good** (Annotated):
```markdown
```bash
meta-cc parse stats --output md

Output:

| Metric | Value |
|--------|-------|
| Turn Count | 2,676 |  ← Total conversation turns
| Tool Calls | 1,012 |  ← Number of tool invocations


**Why**: Annotations explain non-obvious elements, making example self-contained.

---

## Variations

### Variation 1: Before/After Examples

**Use For**: Demonstrating improvement, refactoring, optimization

**Structure**:
```markdown
**Before**: [Problem state]
**After**: [Solution state]
**Impact**: [Measurable improvement]

Example from Troubleshooting:

**Before**:
```python
V_instance = 0.37  # Vague, no component breakdown

After:

V_instance = (Coverage + Quality + Maintainability) / 3
           = (0.40 + 0.25 + 0.40) / 3
           = 0.35

Impact: +0.20 accuracy improvement through explicit component calculation


### Variation 2: Progressive Examples

**Use For**: Complex concepts needing incremental understanding

**Structure**: Simple Example → Intermediate Example → Complex Example

**Example**:
1. Simple: Single value function (V_instance only)
2. Intermediate: Dual value functions (V_instance + V_meta)
3. Complex: Component-level dual scoring with gap analysis

### Variation 3: Comparison Examples

**Use For**: Distinguishing similar concepts or approaches

**Structure**: Concept A Example vs Concept B Example

**Example**:
- Testing Methodology (Iteration 0: V_instance = 0.35)
- Error Recovery (Iteration 0: V_instance = 0.40)
- **Difference**: Rich baseline data (+1,336 errors) improved baseline by +0.05

---

## Common Mistakes

### Mistake 1: Example Too Abstract

**Bad**:
```markdown
**Example**: Apply the pattern to your use case

Good:

**Example**: Testing methodology for Go projects
- Pattern: TDD workflow
- Implementation: Write test → Run (fail) → Write code → Run (pass) → Refactor

Mistake 2: Example Without Context

Bad:

**Example**: `meta-cc parse stats`