Initial commit

skills/documentation-management/templates/concept-explanation.md

@@ -0,0 +1,408 @@
+# 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