Skill: Writing Explanation (Understanding-Oriented)

Goal: Clarify and illuminate specific topics.

content_rules

• Context Provider: Discuss the background, the "why," and the bigger picture.
• Discursive: Allow for connections between differing concepts.
• No Code: Avoid code blocks unless used for high-level architectural illustration.
• Permanence: Write content that changes slowly. Focus on design decisions.
• Justification: Explain why the software works the way it does.

structure

Explanation is the most loosely structured quadrant. It is discursive and essay-like — do not impose a rigid sequence. The following is a suggested flow, not a template to fill in:

• Topic: Name the concept being discussed and why it warrants explanation.
• Background: Provide contextual or historical information that helps the reader place this concept.
• Details: Explore the mechanics, philosophy, or trade-offs in depth. Allow for digressions and connections between ideas.
• Related: Link outward to specific Reference or How-to docs. Do not inline their content — cross-reference instead.

Adjust as needed: some explanations need no background; others need no "related" section. The measure of a good explanation is whether the reader comes away understanding why, not whether it followed a specific structure.