Hierarchical content structure - answer first, then supporting arguments, then details
Add this skill
npx mdskills install applied-artificial-intelligence/pyramid-principleComprehensive guide to hierarchical communication with clear rules, examples, and pitfalls
1---2name: pyramid-principle3description: Hierarchical content structure - answer first, then supporting arguments, then details4foundation: Barbara Minto's Pyramid Principle5use_case: Outlines, business communication, structured explanations6---78# Pyramid Principle Skill910**Foundation**: Barbara Minto's pyramid principle for clear, logical communication1112**Core Concept**: Start with the answer, then provide supporting arguments, then add details.1314**Why This Works**:15- Reader gets main point immediately (respects their time)16- Supporting structure makes logical sense17- Details are contextualized (not lost)18- Reader can stop at any level and still understand core idea19- Reduces cognitive load (top-down, not bottom-up)2021---2223## The Pyramid Structure2425```26 [ANSWER / Core Message]27 |28 ┌──────────────────┼──────────────────┐29 | | |30 [Argument 1] [Argument 2] [Argument 3]31 | | |32 ┌───┼───┐ ┌───┼───┐ ┌───┼───┐33 | | | | | | | | |34 [Details] [Details] [Details] [Details] [Details] [Details]35```3637**Levels**:381. **Level 1**: The answer/conclusion (what they need to know)392. **Level 2**: Major supporting arguments (why answer is true)403. **Level 3**: Evidence and examples (what proves arguments)414. **Level 4**: Details and elaboration (depth as needed)4243---4445## Core Rules4647### Rule 1: Answer First48**Always start with the conclusion**4950❌ **Don't do this** (bottom-up):51```markdown52We analyzed 10 frameworks. We tested each for 6 months.53We measured productivity, reliability, and ease of use.54Framework X performed best. Therefore, we recommend Framework X.55```5657✅ **Do this** (top-down):58```markdown59**We recommend Framework X** because it delivers 30% higher productivity60with proven reliability over 6 months of testing.6162Here's why:631. Productivity: 30% improvement vs alternatives642. Reliability: Zero critical failures in production653. Ease of adoption: 2-week learning curve vs 2-month for alternatives66```6768**Why**: Reader knows the answer immediately. Supporting details provide confidence, but aren't prerequisite to understanding recommendation.6970### Rule 2: Group Related Ideas71**Ideas in each group must be**:72- Related to each other (same category)73- Support the idea above them74- At same level of abstraction7576✅ **Good grouping**:77```78Core Message: "CAF transforms Claude Code into domain-specific agents"79├─ Argument 1: Customization spectrum (out-of-box → CAF → SDK)80├─ Argument 2: Domain transformation examples81└─ Argument 3: Proven patterns and constraints82```8384❌ **Bad grouping** (mixed levels):85```86Core Message: "CAF transforms Claude Code into domain-specific agents"87├─ Argument 1: Customization spectrum88├─ Argument 2: File-based persistence (this is a detail, not major argument)89└─ Argument 3: Stefan uses it for ML4T book (this is an example, not argument)90```9192### Rule 3: Logical Order93**Arguments must follow logical sequence**:9495**Structural order**: Parts of something96- Example: "Framework has 3 components: commands, agents, skills"9798**Chronological order**: Time sequence99- Example: "Workflow: positioning → research → outline → draft → review"100101**Comparative order**: Ranking or comparison102- Example: "Benefits ranked: reliability > productivity > ease"103104**Problem-solution order**: Issue then resolution105- Example: "Problem: Generic AI agents fail. Solution: Domain-specific customization."106107---108109## Application to Content Types110111### Application 1: Outlines (Architect Agent)112113**Structure**:114```markdown115# Outline116117## Opening (Level 1: Answer)118- Hook (grab attention)119- Core message (the answer)120- Preview (what's coming)121122## Body (Level 2: Arguments)123### Argument 1: [First supporting point]124- Evidence (Level 3)125- Examples (Level 3)126- Details (Level 4)127128### Argument 2: [Second supporting point]129- Evidence (Level 3)130- Examples (Level 3)131- Details (Level 4)132133### Argument 3: [Third supporting point]134- Evidence (Level 3)135- Examples (Level 3)136- Details (Level 4)137138## Closing (Level 1: Reinforce Answer)139- Restate core message140- Call to action141```142143**Example for CAF white paper**:144```markdown145Opening: "Transform Claude Code into specialized domain agents"146├─ Argument 1: Customization spectrum (out-of-box → CAF → SDK)147│ ├─ Evidence: What each level provides148│ ├─ Example: Content management workflow149│ └─ Details: When to use each level150├─ Argument 2: Domain transformation mechanism151│ ├─ Evidence: How markdown customization works152│ ├─ Example: Commands, agents, skills153│ └─ Details: Technical architecture154└─ Argument 3: Proven patterns and constraints155 ├─ Evidence: 6 months production use156 ├─ Example: Specific patterns157 └─ Details: How constraints prevent failure158Closing: Reinforce transformation message + CTA159```160161### Application 2: Business Communication162163**Memo structure**:164```markdown165Subject: Recommendation166167**Recommendation**: [The answer - one sentence]168169**Rationale**: [3-5 supporting arguments]1701. Argument 11712. Argument 21723. Argument 3173174**Details**: [Evidence for each argument]175[Expand on arguments with data, examples, elaboration]176```177178**Why this works**: Executive reads first line, gets answer, decides if they need to read more.179180### Application 3: Technical Explanations181182**Explain "What is CAF?"**:183184❌ **Bottom-up** (reader lost):185```markdown186Claude Code has plugins. Plugins have commands. Commands invoke agents.187Agents use skills. Skills provide patterns. Patterns create frameworks.188Therefore, CAF is a meta-framework for domain-specific agent customization.189```190191✅ **Top-down** (pyramid):192```markdown193**CAF transforms Claude Code into domain-specific agents through markdown-based customization.**194195How it works:1961. Commands: Encapsulate domain workflows1972. Agents: Provide specialized capabilities1983. Skills: Define behavior patterns199200Why it matters:201- Transforms generic AI into domain-expert202- Uses simple markdown (no coding required)203- Proven patterns prevent common failures204```205206**Reader benefit**: Understands "what it is" immediately, can drill into details if interested.207208---209210## Common Mistakes211212### Mistake 1: Burying the Lede213❌ **Don't hide the answer**:214```markdown215We conducted extensive research. We analyzed frameworks.216We tested implementations. We gathered feedback.217After 6 months, we discovered that...218```219220✅ **Answer first**:221```markdown222**CAF prevents AI chaos through stateless, file-based architecture.**223224Evidence from 6 months testing:225- Zero state corruption failures226- 100% reproducible results227- Context preserved across sessions228```229230### Mistake 2: Mixed Abstraction Levels231❌ **Arguments at different levels**:232```2331. Customization spectrum (high-level concept)2342. File-based persistence (implementation detail)2353. Domain transformation (high-level concept)236```237238✅ **Same level**:239```2401. Customization spectrum (what CAF provides)2412. Domain transformation (how it works)2423. Proven patterns (why it's reliable)243```244245### Mistake 3: Illogical Order246❌ **Random order**:247```2481. Benefits2492. How it works2503. What it is251```252253✅ **Logical order**:254```2551. What it is (establish understanding)2562. How it works (explain mechanism)2573. Benefits (show value)258```259260### Mistake 4: No Hierarchy261❌ **Flat list**:262```263- Point 1264- Point 2265- Point 3266- Point 4267- Point 5268(All at same level, no structure)269```270271✅ **Hierarchical**:272```273Core Message274├─ Major Point 1275│ ├─ Supporting detail276│ └─ Example277├─ Major Point 2278│ ├─ Supporting detail279│ └─ Example280└─ Major Point 3281 ├─ Supporting detail282 └─ Example283```284285---286287## Quality Checklist288289**When applying pyramid principle, verify**:290291- [ ] Answer/conclusion stated first (Level 1)292- [ ] 3-5 major supporting arguments identified (Level 2)293- [ ] Each argument supports answer above it294- [ ] Evidence/examples provided for arguments (Level 3)295- [ ] Details elaborated as needed (Level 4)296- [ ] Arguments grouped logically (related ideas together)297- [ ] Arguments ordered logically (structural/chronological/comparative/problem-solution)298- [ ] Each level is at consistent abstraction level299- [ ] Reader can stop at any level and still understand core idea300- [ ] No "burying the lede" (answer hidden at end)301302---303304## Integration with Other Skills305306**Pyramid + excellent-writing**:307- Pyramid: What structure to use308- excellent-writing: How to write clearly within that structure309310**Pyramid + SCQA**:311- Pyramid: Overall hierarchical structure312- SCQA: How to structure narrative within pyramid (especially opening)313314**Pyramid + positioning-first**:315- Positioning: What the core message is (Level 1 of pyramid)316- Pyramid: How to structure arguments supporting that message317318---319320## References321322**Foundation**: Barbara Minto, "The Pyramid Principle: Logic in Writing and Thinking"323324**Key insight**: "Any intelligent reader can absorb only one thought at a time, and will automatically assume that any sentence that follows a previous one is intended to explain that thought further."325326**Application**: Therefore, organize content to match how readers naturally process information - top-down, hierarchical, answer-first.327328---329330**Skill Version**: 1.0331**Created**: 2025-10-31332**Used by**: architect agent (outlines), author agent (optional)333**Key Innovation**: Answer-first hierarchical structure that respects reader's cognitive load334
Full transparency — inspect the skill content before installing.