<p align="center">
  <picture>
    <img alt="mu-pyramid-principle" src="assets/default-banner.png" width="100%">
  </picture>
</p>

# 🔺 mu-pyramid-principle · Pyramid Principle Logic Coach

> No theory lectures — just diagnosis and reconstruction. Paste any text and get a 7-type logic disease scan, MECE check, SCQA variant selection, and a rebuilt pyramid structure with a polished rewrite.
>
> 📚 Based on *The Pyramid Principle* by Barbara Minto.

**English** | [中文](README_CN.md) | [🌐 Landing Page](https://muippt.github.io/mu-pyramid-principle/)

[![WeChat](https://img.shields.io/badge/muippt-07C160?logo=wechat&logoColor=white)](https://mp.weixin.qq.com/s/YLtXENt_7WzO2DgJCFUtPA)
[![Xiaohongshu](https://img.shields.io/badge/muippt-FF2442?logo=xiaohongshu&logoColor=white)](https://xhslink.com/m/ESxtgUNMdl)
[![Book](https://img.shields.io/badge/Book-Visual%20Team%20Management-BBDDE5?logo=bookstack&logoColor=white)](https://item.m.jd.com/product/14547345.html)
[![mu-skillhub](https://img.shields.io/badge/mu--skillhub-9E95B7?logo=refinedgithub&logoColor=white)](https://muippt.github.io/mu-skill-hub/)
[![License](https://img.shields.io/github/license/muippt/mu-pyramid-principle)](LICENSE)
[![Version](https://img.shields.io/github/v/release/muippt/mu-pyramid-principle)](https://github.com/muippt/mu-pyramid-principle/releases)
[![Stars](https://img.shields.io/github/stars/muippt/mu-pyramid-principle)](https://github.com/muippt/mu-pyramid-principle/stargazers)

---

### 💡 Usage Examples

📄 **"Here's my quarterly report — is the logic sound?"**
Paste the text and get a 7-type logic disease diagnosis: missing conclusion, sub-points that don't support the main argument, overlapping categories, logic jumps, MECE gaps, broken syllogisms, and fact-vs-judgment confusion — each quoting the original line with severity rating and fix suggestion.

🔺 **"Rebuild this into a pyramid."**
After diagnosis, the skill picks top-down or bottom-up construction, restructures your points into a MECE-checked pyramid, and outputs a polished rewrite with SCQA preamble — all preserving your original key information.

🎯 **"Help me organize my thoughts before I write."**
Guided mode walks you through: What do you want the audience to do? What do they already know? What's blocking them? — then distills a one-sentence thesis, breaks down 3-5 MECE sub-arguments, and generates the full document.

🔍 **"My proposal feels off but I can't pinpoint why."**
The "论证类比" four-character checklist catches it in seconds: Is the first sentence a complete judgment? Does every point have supporting evidence? Is the grouping non-overlapping and exhaustive? Is there a logical ordering within each group?

📝 **"Write me an SCQA opening for this report."**
Four SCQA variants — Standard, Action, Conflict, Proposal — auto-selected based on your audience and context. A decision tree picks the right one so your opening hits the right note every time.

🏋️ **"Train me on logical thinking."**
Four training drills: Fact vs Judgment, Deduction vs Induction, MECE Gap-Finding, and Pyramid Reassembly — each with instant feedback that praises what you got right before explaining what you missed.

📊 **"Structure my competitive analysis."**
Bottom-up construction mode: scatter all your raw notes → cluster by MECE → summarize each cluster into a sub-argument → distill the top-level conclusion → validate top-down consistency.

💼 **"Prep my performance review narrative."**
Guided mode → top-down → Action-variant SCQA: conclusion-first review narrative that leads with impact, supports with evidence, and keeps your manager's attention locked on results.

---

### ✨ Core Highlights

#### 🔍 7-Type Logic Disease Diagnosis — Quote, Rate, Fix

Every diagnosis scans all 7 disease types, quotes the exact original text, assigns a severity level (🔴 Fatal / 🟡 Moderate / 🟢 Minor), and provides a concrete fix for each hit.

| # | Disease | Severity | What It Catches |
|---|---------|----------|-----------------|
| 1 | Missing Conclusion | 🔴 Fatal | No judgment sentence anywhere — reader finishes and asks "so what?" |
| 2 | Sub ≠ Super | 🔴 Fatal | Sub-points are valid individually but don't add up to the parent argument |
| 3 | Overlapping Categories | 🟡 Moderate | Parallel items overlap — one thing fits into multiple buckets |
| 4 | Logic Jump | 🟡 Moderate | Missing intermediate steps between two points — a leap of faith |
| 5 | MECE Gap | 🟡 Moderate | Classification misses obvious cases — incomplete coverage |
| 6 | Broken Syllogism | 🟡 Minor | Major premise missing or conclusion doesn't follow from premises |
| 7 | Fact-Judgment Confusion | 🟡 Minor | Subjective opinion stated as objective fact with no evidence tag |

#### 🧩 "论证类比" Four-Character Checklist

A 4-second mental check borrowed from classical Chinese rhetoric, adapted for pyramid validation:

| 论 (Conclusion) | 证 (Evidence) | 类 (Grouping) | 比 (Ordering) |
|:---:|:---:|:---:|:---:|
| Conclusion first | Supported above by below | Mutually exclusive | Logically progressive |
| Is the first sentence a complete judgment? | Does every point have a reason? | Non-overlapping, exhaustive? | Ordered within each group? |

#### 📐 SCQA 4 Variants — Auto-Selected by Context

The preamble variant is chosen automatically based on audience awareness, decision urgency, and emotional resistance — not guessed.

| Variant | Best For | Structure |
|---------|----------|-----------|
| Standard | Formal reports | S→C→Q→A (full展开) |
| Action | Urgent decisions | S→A→C→Q (conclusion first) |
| Conflict | Persuasion | C→S→Q→A (pain point opening) |
| Proposal | Recommendation | Q→S→C→A (problem-led) |

#### 🔺 Dual-Mode Interaction — Quick & Guided

| Mode | Behavior | When It Activates |
|------|----------|-------------------|
| 🚀 Quick (default) | Paste → 7-type diagnosis → pyramid rebuild → polished rewrite | Text pasted with trigger words like "fix the logic" / "restructure this" |
| 💬 Guided | Dialogue-driven pyramid construction from fuzzy ideas | You say "help me organize my thoughts" / "I want to express X but don't know how" |

#### 🏗️ Top-Down & Bottom-Up Construction

Two construction paths, auto-selected based on what you bring:

```
Top-Down (you have a clear opinion):
  Thesis → Anticipate questions → 3-5 MECE sub-arguments → Evidence per argument → SCQA → Output

Bottom-Up (you have scattered material):
  List all points → Cluster by relationship → Summarize each cluster → Distill top thesis → Validate → SCQA → Output
```

#### 🏋️ Logic Training Mode — 4 Drill Types

When you say "train me" / "let me practice," the skill switches to coaching mode:

| Drill | What You Do | What You Learn |
|-------|-------------|----------------|
| A. Fact vs Judgment | Classify 5-7 sentences | Distinguish objective from subjective |
| B. Deduction vs Induction | Identify reasoning type | Spot when premises don't guarantee conclusions |
| C. MECE Gap-Finding | Find overlaps and gaps in a classification | Build the reflex for clean grouping |
| D. Pyramid Reassembly | Reorganize shuffled points and evidence | Practice full structural reconstruction |

---

### 📌 Comparison

| Dimension | mu-pyramid-principle | Generic ChatGPT prompt | Mind Mapping Tools | Traditional Writing Courses |
|-----------|:--------------------:|:----------------------:|:------------------:|:---------------------------:|
| Diagnostic framework | 7 logic diseases, full scan | Varies every run | None | Partial |
| MECE enforcement | Yes — every grouping checked | Occasional, unnamed | Manual | Yes, but theory-only |
| SCQA variant selection | Auto-selected by context | You choose manually | Not covered | Static examples |
| Construction paths | Top-down + bottom-up, auto-selected | One path, ad hoc | Free-form tree | Top-down only |
| Output format | Diagnosis report + tree visualization + polished rewrite | Free text | Visual map | Hand-written drafts |
| Logic training drills | 4 types with instant feedback | None | None | Homework, delayed feedback |
| Information preservation | Explicit rule: no over-deletion | Often loses key points | N/A | N/A |
| Severity rating | 🔴🟡🟢 per disease | None | None | Red marks on paper |
| IRON LAW guardrails | 8 non-negotiable rules | None | None | Implicit |
| Setup cost | Drop in a folder | Rewrite prompt each time | Learn the tool | Attend a course |
| Cross-skill linkage | mu-critical-thinking → diagnose, then restructure | None | None | None |

---

### 🚀 Two Interaction Modes & Six Scenarios

**Two interaction modes:**

| Mode | Behavior | When It Activates |
|------|----------|-------------------|
| 🚀 Quick (default) | Paste → diagnose → restructure → polished output | Text pasted with trigger words |
| 💬 Guided | Dialogue-driven construction from fuzzy ideas | You say "help me organize" / "I don't know how to structure this" |

**Six common scenarios:**

| Scenario | Recommended Flow | Key Output |
|----------|-----------------|------------|
| **Quarterly review** | Guided → top-down → Action SCQA | Conclusion-first review narrative |
| **Project proposal** | Quick → diagnose → restructure | Diagnosis report + optimized proposal |
| **Weekly email** | Quick → top-down | Lean pyramid structure |
| **Competitive analysis** | Guided → bottom-up | MECE classification + logic tree |
| **Upward reporting** | Quick → Conflict SCQA | Problem-oriented report |
| **Interview response** | Guided → STAR → pyramid | Conclusion-first answer structure |

---

### ⚙️ Technical Specs

| Item | Description |
|------|-------------|
| Type | Markdown-based AI skill — no code, no runtime, no build step |
| Dependencies | None. Zero npm/pip packages, zero API keys |
| Compatible with | Claude Code, Claude Desktop, and any agent supporting the Skill / SKILL.md convention |
| Package size | ~40 KB total (SKILL.md + 3 reference files) |
| Structure | 1 SKILL.md + 3 references (logic-diagnosis, pyramid-patterns, logic-frameworks) |
| Input | Plain text, proposals, reports, meeting notes, presentation outlines |
| Output | Structured Markdown — diagnosis report, tree visualization, SCQA preamble, polished rewrite |
| Language | Chinese-first content; works with English input and output |
| Progressive loading | Reference files are read only when the matching scenario fires, keeping context lean |
| Version | 1.2.0 |
| License | MIT |

**Cross-skill linkages** (optional, if you have them installed):
- `mu-critical-thinking` — critical thinking deconstructs the problem, pyramid principle restructures the expression
- `mu-humanizer-minesweeping` — strips the AI flavor out of the resulting text
- `mu-ippt` — turns the pyramid structure into a polished presentation

---

### 🛠️ Quick Start

**1. Install** — clone into your skills directory
```bash
git clone https://github.com/muippt/mu-pyramid-principle.git ~/.claude/skills/mu-pyramid-principle
```
> Using a different agent? Just drop the folder wherever your tool loads skills from. Project-level works too: `.claude/skills/mu-pyramid-principle`.

**2. Verify** — restart your agent and confirm the skill is picked up
```
List my available skills
```

**3. Run** — paste something and let it work
```
Paste any proposal, report, or paragraph → automatic logic diagnosis + pyramid rebuild
```
Or invoke a specific workflow:
```
Diagnose the logic of this text: "Our project is on track. Progress is at 80%. Resources are sufficient. We have some risks with the timeline."
```
```
Help me organize my thoughts for a quarterly review presentation.
```
```
Train me on MECE: give me a classification and let me find the gaps.
```

---

### 🔒 Security & Privacy

- **Fully local** — the skill is plain Markdown read by your agent. Nothing is installed, nothing runs.
- **Zero network calls** — no API endpoints, no external services, no remote fetches at any point.
- **Zero telemetry** — no usage tracking, no analytics, no phone-home. There is no code that *could* collect anything.
- **Zero dependencies** — no npm, pip, or third-party packages, so no supply-chain surface.
- **Your text stays where your agent is** — the skill adds no storage, no logging, and no persistence of the documents you analyze.
- **Fully auditable** — 4 Markdown files, all human-readable. Read the whole thing in ten minutes.
- **No credentials required** — no API keys, tokens, or accounts.
- **Preserves your information** — an explicit IRON LAW rule prohibits over-deletion; restructuring ≠ rewriting, and your key points survive every rebuild.

---

### ⭐ Star History

If this helps you turn one messy draft into a clear, conclusion-first document, a star would mean a lot.

[![Star History Chart](assets/star-history.png)](https://www.star-history.com/?repos=muippt%2Fmu-pyramid-principle&type=date)

> Seven logic diseases, four SCQA variants, one pyramid — turning "I know what I want to say but can't organize it" into "conclusion first, evidence below, logic airtight."

---

### 👤 About the Author

🎓 Signatory Author of Tsinghua University Press / 2026 Dangdang Influential Author / AI & Large Model Business HR Specialist at a Leading Tech Company / National Level-1 HR Manager / Level-2 Psychological Counselor / Self-taught Designer

📚 Author of [*Visual Team Management*](https://item.m.jd.com/product/14547345.html). Clients include ByteDance, Tencent, Baidu, China Mobile, SMG, BOE…

💡 [WeChat Official Account](https://mp.weixin.qq.com/s/YLtXENt_7WzO2DgJCFUtPA) / [Xiaohongshu](https://xhslink.com/m/ESxtgUNMdl): muippt

🧰 More skills: [mu-skill-hub](https://muippt.github.io/mu-skill-hub/) · [GitHub](https://github.com/muippt)

---

### 📄 License & Acknowledgments

[MIT](LICENSE) © 2026 muippt

**Acknowledgments**
- ***The Pyramid Principle: Logic in Writing and Thinking*** by **Barbara Minto** — the methodological foundation of this project. The MECE principle, SCQA framework, and top-down/bottom-up construction paths are all derived from her work.
- the three-element logic validation model is derived from his methodology practice.

**AI Co-creation Declaration**: This skill was co-created with AI assistance. The methodology framework is based on the works cited above; the skill structure, diagnostic standards, and output templates were designed and iterated through human-AI collaboration.
