Diataxis Explanation Command

You are in the EXPLANATION phase of the Diataxis documentation workflow. Your mission is to create understanding-oriented documentation that provides context, background, and deeper insights into concepts, designs, and decisions.

⚠️ IMPORTANT: This command is for creating EXPLANATORY documentation ONLY. Focus exclusively on:

Providing conceptual understanding and context
Explaining the "why" behind decisions
Discussing alternatives and trade-offs
Offering broader perspectives and connections
Documenting everything in docs/explanation/[topic-slug].md

Concept to Explain

$ARGUMENTS

If no specific concept was provided above, ask the user: "What concept, architecture, or design decision would you like explained in depth?"

🤔 Explanation Objectives

Deepen Understanding: Provide context and background
Explain Rationale: Why things are the way they are
Discuss Alternatives: What other approaches exist
Make Connections: How concepts relate to each other
Provide Perspective: Historical and future context

Extended Thinking Strategy

Simple concepts: Clear analogies and examples
Complex systems: Think about relationships and interactions
Design decisions: Think hard about trade-offs and constraints
Architectural choices: Ultrathink about long-term implications

Parallel Explanation Subagents

Deploy concurrent documentation specialists: @docs-explanation-agent @architecture-documenter @system-designer @business-analyst

All subagents work in parallel to create comprehensive explanations:

@docs-explanation-agent: Create conceptual, understanding-oriented content
@architecture-documenter: Document design decisions and rationale
@system-designer: Explain system architecture and patterns
@business-analyst: Provide business context and requirements background

Explanation Documentation Framework

Step 1: Define the Topic

## About [Topic]

### Overview

[High-level introduction to the concept]

### Why This Matters

- [Business impact]
- [Technical significance]
- [User benefits]

### Scope of This Explanation

This document explains:

- [Aspect 1]
- [Aspect 2]
- [Aspect 3]

This document does not cover:

- [Out of scope 1]
- [Out of scope 2]

Step 2: Provide Context

## Background and Context

### Historical Perspective

[How we got here - evolution of the concept]

### Current State

[Where we are now - current implementation/understanding]

### Industry Context

[How others approach this - standards and practices]

### Our Approach

[Why we chose this path - specific context]

Step 3: Core Concepts

## Understanding [Core Concept]

### The Fundamental Idea

[Explain the core concept in simple terms]

### Analogy

Think of [concept] like [familiar analogy]. Just as [analogy explanation],
[concept] works by [parallel explanation].

### Key Principles

1. **Principle 1**: [Explanation]
   - Why it matters
   - How it works
   - Implications

2. **Principle 2**: [Explanation]
   - Why it matters
   - How it works
   - Implications

### Mental Model

[Visual or conceptual model] Component A → Process → Component B ↓ ↓ Storage Output

Step 4: Design Decisions

## Design Decisions and Trade-offs

### Decision: [Specific Choice Made]

#### Options Considered

1. **Option A** (Chosen)
   - Pros: [Benefits]
   - Cons: [Drawbacks]
   - Why chosen: [Reasoning]

2. **Option B**
   - Pros: [Benefits]
   - Cons: [Drawbacks]
   - Why not: [Reasoning]

3. **Option C**
   - Pros: [Benefits]
   - Cons: [Drawbacks]
   - Why not: [Reasoning]

#### Trade-offs Accepted

- We prioritized [quality] over [quality]
- We accepted [limitation] to gain [benefit]
- We chose [approach] knowing [consequence]

#### Future Considerations

- This decision allows for [future possibility]
- We may revisit if [condition changes]
- Migration path exists to [alternative]

Step 5: Relationships and Connections

## How This Relates to Other Concepts

### Relationship to [Related Concept 1]

[Explain connection and interaction]

### Relationship to [Related Concept 2]

[Explain connection and interaction]

### Part of Larger System

[Broader Context] ├── [This Concept] ├── [Related System] └── [Connected Component]


### Dependencies
- Depends on: [What this needs]
- Depended on by: [What needs this]
- Interfaces with: [What it connects to]

Explanation Deliverables

Output File Location

All explanation documentation will be generated in the docs/explanation/ directory with descriptive filenames based on the concept being explained.

Explanation Template Structure

# Understanding [Topic]

## Introduction

[Accessible introduction that draws readers in]

## The Big Picture

[Context and significance in the broader landscape]

## Core Concepts

### What Is [Concept]?

[Clear, accessible explanation]

### Why [Concept] Exists

[Problem it solves, need it addresses]

### How [Concept] Works

[Conceptual overview, not implementation details]

## Design Philosophy

### Guiding Principles

[What drives the design]

### Architectural Decisions

[Key choices and their rationale]

### Trade-offs

[What we optimized for vs. what we sacrificed]

## Alternatives and Comparisons

### Alternative Approaches

[Other ways to solve the same problem]

### When to Use Which

[Decision framework for choosing approaches]

### Evolution and History

[How approaches have evolved]

## Practical Implications

### Impact on Development

[How this affects day-to-day work]

### Impact on Users

[How this affects end users]

### Impact on Operations

[How this affects deployment and maintenance]

## Common Misconceptions

### Misconception 1: [Statement]

**Reality**: [Correction and explanation]

### Misconception 2: [Statement]

**Reality**: [Correction and explanation]

## Future Directions

### Current Limitations

[Honest assessment of current state]

### Planned Improvements

[Roadmap and vision]

### Industry Trends

[Where the field is heading]

## Summary

[Key takeaways and main points]

## Further Reading

- [Related explanation documents]
- [External resources]
- [Academic papers or industry articles]

Explanation Best Practices

DO:

✅ Provide rich context and background
✅ Explain the "why" behind decisions
✅ Discuss alternatives thoughtfully
✅ Make connections between concepts
✅ Use analogies and examples
✅ Admit uncertainties and opinions
✅ Consider multiple perspectives
✅ Include historical context

DON'T:

❌ Include step-by-step instructions
❌ Focus on implementation details
❌ Provide technical specifications
❌ Write tutorials or how-tos
❌ Be prescriptive about usage
❌ Avoid difficult topics
❌ Present only one viewpoint

Quality Checklist

Before finalizing explanation documentation:

Usage Examples

# Basic explanation creation
/diataxis-explanation "microservices architecture"

# Specify explanation type
/diataxis-explanation "database design" --architecture
/diataxis-explanation "algorithm choice" --design
/diataxis-explanation "CAP theorem" --theory
/diataxis-explanation "REST vs GraphQL" --comparison

# Specific concepts
/diataxis-explanation "event-driven architecture"
/diataxis-explanation "zero-trust security model"

Integration with Other Diataxis Types

Relationship to Other Documentation

From Tutorial: "To understand why we do this, see explanation"
From How-to: "For background on this approach, read explanation"
From Reference: "For conceptual understanding, see explanation"

Documentation Journey

Tutorial → How-to → Reference → Explanation (You are here)
Doing → Achieving → Looking up → Understanding deeply

Common Explanation Patterns

Architecture Explanation

## Understanding Our Architecture

### Why This Architecture?

[Problems it solves]

### Core Design Principles

[What guides decisions]

### Component Relationships

[How parts work together]

### Evolution Story

[How we got here]

Design Pattern Explanation

## The [Pattern Name] Pattern

### Problem It Solves

[Context and challenge]

### How It Works

[Conceptual mechanism]

### When to Use It

[Appropriate contexts]

### Trade-offs

[Benefits vs. costs]

Technology Choice Explanation

## Why We Chose [Technology]

### Requirements That Led Here

[What we needed]

### Alternatives Considered

[What else we looked at]

### Decision Factors

[What tipped the scales]

### Living with the Choice

[Experience and lessons]

Conceptual Model Explanation

## Understanding [Model]

### Mental Model

[How to think about it]

### Real-World Analogy

[Familiar comparison]

### Key Insights

[Aha moments]

### Common Pitfalls

[Misconceptions to avoid]

Final Output

Upon completion, generate docs/explanation/[topic-slug].md containing:

Rich contextual background
Clear conceptual explanations
Design decisions and rationale
Trade-off discussions
Alternative approaches
Connections between concepts
Future directions
Thought-provoking insights

Remember: Your job is to deepen understanding and provide the "why" behind everything!

🚫 DO NOT: Provide instructions, list specifications, avoid complexity ✅ DO: Explain concepts, discuss trade-offs, provide context, make connections

/docs-explanation