Skip to content
Back to search

first-principles-skill

A Claude Code skill for systematic first principles thinking - analyze designs, challenge assumptions, build from fundamental truths

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/awesome-skills--first-principles-skill/badge.svg)](/listings/awesome-skills--first-principles-skill)

HTML

<a href="/listings/awesome-skills--first-principles-skill"><img src="/api/listings/awesome-skills--first-principles-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: Copy to your skills directory

# Clone the repo
git clone https://github.com/tt-a1i/first-principles-skill.git

# Copy to Claude Code skills directory
cp -r first-principles-skill ~/.claude/plugins/superclaude/skills/first-principles

Option 2: Symlink

git clone https://github.com/tt-a1i/first-principles-skill.git ~/skills/first-principles-skill
ln -s ~/skills/first-principles-skill ~/.claude/plugins/superclaude/skills/first-principles

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 196 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: First Principles Thinking
  3. description: This skill should be used when the user asks to "analyze from first principles", "第一性原理", "从根本分析", "从零开始思考", "think from scratch", "question this design", "这个设计合理吗", "is this the right approach", "为什么要这样做", "why are we doing it this way", "有没有更好的方案", "is there a better solution", "challenge assumptions", "挑战假设", or needs to evaluate architectural decisions, design choices, or problem-solving approaches without relying on analogies or conventions.
  4. version: 0.2.0
  5. ---
  6. # First Principles Thinking
  7. A systematic approach to decomposing complex problems into fundamental truths and reasoning up from there, avoiding the trap of reasoning by analogy.
  8. ## When to Use This Skill
  9. - Evaluating whether an architecture or design is truly optimal
  10. - Questioning "best practices" that may not fit the current context
  11. - Breaking through when conventional solutions feel inadequate
  12. - Making foundational decisions that will have long-term impact
  13. - Challenging inherited assumptions in legacy systems
  14. - Designing new systems without cargo-culting existing patterns
  15. ## Core Process
  16. ### Phase 1: Identify the Problem's Essence
  17. Strip away implementation details to find the core problem:
  18. 1. **State the problem clearly** - What exactly needs to be solved?
  19. 2. **Separate symptoms from causes** - Is this the real problem or a manifestation?
  20. 3. **Define success criteria** - What would a perfect solution achieve?
  21. **Key Questions:**
  22. - What is the fundamental job to be done here?
  23. - If this system didn't exist, what would users actually need?
  24. - What outcome matters, independent of how we get there?
  25. ### Phase 2: Challenge All Assumptions
  26. Identify and question every assumption:
  27. 1. **List explicit assumptions** - What are we taking as given?
  28. 2. **Surface implicit assumptions** - What conventions are we following without questioning?
  29. 3. **Test each assumption** - Is this actually a constraint, or just how it's always been done?
  30. **Assumption Categories:**
  31. | Category | Question to Ask |
  32. |----------|----------------|
  33. | Technical | "Must we use this technology/pattern?" |
  34. | Business | "Is this requirement actually fixed?" |
  35. | Resource | "Are these constraints real or perceived?" |
  36. | Historical | "Why was this decision made originally?" |
  37. **Red Flags (likely false assumptions):**
  38. - "We've always done it this way"
  39. - "Industry standard says..."
  40. - "Everyone uses X for this"
  41. - "That's too simple to work"
  42. ### Phase 3: Establish Ground Truths
  43. Identify the irreducible facts:
  44. 1. **Physics/Math constraints** - What cannot be violated?
  45. 2. **Business invariants** - What must remain true for the business?
  46. 3. **User needs** - What does the user fundamentally require?
  47. **Ground Truth Test:**
  48. - Can this be further decomposed?
  49. - Is this provably true, not just commonly believed?
  50. - Would violating this definitely cause failure?
  51. ### Phase 4: Reason Upward
  52. Build solutions from ground truths:
  53. 1. **Start minimal** - What's the simplest thing that satisfies ground truths?
  54. 2. **Add only what's necessary** - Each addition must justify itself
  55. 3. **Challenge each layer** - Does this layer earn its complexity?
  56. **Building Blocks Approach:**
  57. ```
  58. Ground Truth → Minimal Solution → Justified Additions → Final Design
  59. ↑ ↑ ↑
  60. (proven) (sufficient) (each defended)
  61. ```
  62. ### Phase 5: Validate the Reasoning
  63. Ensure the solution is sound:
  64. 1. **Trace back to ground truths** - Can every design decision be traced to a fundamental need?
  65. 2. **Identify weak links** - Where does the reasoning rely on assumptions?
  66. 3. **Stress test** - What would break this solution?
  67. ## Output Format
  68. When applying first principles thinking, structure the analysis as:
  69. ```markdown
  70. ## First Principles Analysis: [Topic]
  71. ### 1. Problem Essence
  72. **Core problem:** [One sentence]
  73. **Success criteria:** [Measurable outcomes]
  74. ### 2. Assumptions Challenged
  75. | Assumption | Challenge | Verdict |
  76. |------------|-----------|---------|
  77. | [Assumption] | [Why question it] | [Keep/Discard/Modify] |
  78. ### 3. Ground Truths
  79. - [Irreducible fact 1]
  80. - [Irreducible fact 2]
  81. - [Irreducible fact 3]
  82. ### 4. Reasoning Chain
  83. Ground Truth → [Step 1] → [Step 2] → Solution
  84. ### 5. Conclusion
  85. **Recommended approach:** [Description]
  86. **Key insight:** [What the first principles analysis revealed]
  87. **Trade-offs acknowledged:** [What we're accepting]
  88. ```
  89. ## Common Patterns
  90. ### Pattern: The Complexity Trap
  91. **Symptom:** Solution is more complex than the problem warrants
  92. **First Principles Check:**
  93. 1. Remove one component - does the system still solve the core problem?
  94. 2. If yes, that component wasn't essential
  95. 3. Repeat until removal breaks core functionality
  96. ### Pattern: The Analogy Trap
  97. **Symptom:** "Company X does it this way, so we should too"
  98. **First Principles Check:**
  99. 1. What problem was Company X actually solving?
  100. 2. Is our problem identical in all relevant dimensions?
  101. 3. What constraints did they have that we don't (and vice versa)?
  102. ### Pattern: The Legacy Trap
  103. **Symptom:** Maintaining compatibility with decisions that no longer serve us
  104. **First Principles Check:**
  105. 1. What was the original reason for this decision?
  106. 2. Do those conditions still exist?
  107. 3. What's the true cost of change vs. cost of maintaining?
  108. ## Integration with Other Thinking Tools
  109. First principles thinking works well with these complementary approaches:
  110. | Tool | When to Combine | How |
  111. |------|-----------------|-----|
  112. | **Trade-off Analysis** | After identifying ground truths | Evaluate options against fundamentals |
  113. | **5-Whys** | When assumptions surface | Dig deeper to find root causes |
  114. | **Pre-mortem** | Before finalizing solution | Stress-test reasoning chain |
  115. | **Hypothesis Testing** | When ground truths are uncertain | Validate assumptions empirically |
  116. ## Boundaries
  117. **Will:**
  118. - Challenge assumptions systematically
  119. - Identify ground truths from first principles
  120. - Build reasoning chains from fundamentals
  121. - Reveal when conventional wisdom doesn't apply
  122. **Will Not:**
  123. - Dismiss all existing solutions as wrong
  124. - Spend unlimited time on every decision (reserve for important choices)
  125. - Ignore practical constraints in favor of theoretical purity
  126. - Guarantee the "best" solution (reveals better reasoning, not perfect answers)
  127. ## Quick Reference
  128. **The First Principles Checklist:**
  129. - [ ] Problem stated in terms of outcomes, not solutions
  130. - [ ] All assumptions explicitly listed
  131. - [ ] Each assumption challenged and justified
  132. - [ ] Ground truths identified and verified
  133. - [ ] Solution built up from ground truths only
  134. - [ ] Every design decision traceable to a ground truth
  135. - [ ] Reasoning chain documented
  136. ## Additional Resources
  137. ### Reference Files
  138. - **`references/elon-musk-examples.md`** - Real-world examples from SpaceX and Tesla
  139. - **`references/software-examples.md`** - Software engineering applications
  140. ### Example Files
  141. - **`examples/architecture-review.md`** - First principles analysis of a microservices decision
README.md · README · 113 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # First Principles Thinking Skill
  2. A Claude Code skill that provides systematic first principles thinking methodology for evaluating designs, challenging assumptions, and building solutions from fundamental truths.
  3. ## What is This?
  4. This is a **skill** for [Claude Code](https://claude.ai/code) that enhances Claude's ability to analyze problems from first principles rather than relying on analogies or conventions.
  5. ## Installation
  6. ### Option 1: Copy to your skills directory
  7. ```bash
  8. # Clone the repo
  9. git clone https://github.com/tt-a1i/first-principles-skill.git
  10. # Copy to Claude Code skills directory
  11. cp -r first-principles-skill ~/.claude/plugins/superclaude/skills/first-principles
  12. ```
  13. ### Option 2: Symlink
  14. ```bash
  15. git clone https://github.com/tt-a1i/first-principles-skill.git ~/skills/first-principles-skill
  16. ln -s ~/skills/first-principles-skill ~/.claude/plugins/superclaude/skills/first-principles
  17. ```
  18. ## Usage
  19. The skill triggers automatically when you use phrases like:
  20. | Language | Trigger Phrases |
  21. |----------|-----------------|
  22. | English | "analyze from first principles", "think from scratch", "question this design", "is this the right approach", "challenge assumptions" |
  23. | Chinese | "第一性原理", "从根本分析", "从零开始思考", "这个设计合理吗", "为什么要这样做", "有没有更好的方案" |
  24. ### Example
  25. ```
  26. User: 用第一性原理分析一下我们是否应该采用微服务架构
  27. Claude: [Applies first principles thinking methodology]
  28. ## First Principles Analysis: Microservices Architecture
  29. ### 1. Problem Essence
  30. **Core problem:** Enable faster development and independent scaling
  31. **Success criteria:** Deploy without full regression, scale components independently
  32. ### 2. Assumptions Challenged
  33. | Assumption | Challenge | Verdict |
  34. |------------|-----------|---------|
  35. | Need microservices for modern apps | Do we have the team size? | Investigate |
  36. ...
  37. ```
  38. ## Structure
  39. ```
  40. first-principles-skill/
  41. ├── SKILL.md # Main skill definition
  42. ├── README.md # This file
  43. ├── LICENSE # MIT License
  44. ├── references/
  45. │ ├── software-examples.md # Software engineering case studies
  46. │ └── elon-musk-examples.md # SpaceX/Tesla examples
  47. └── examples/
  48. └── architecture-review.md # Complete microservices analysis example
  49. ```
  50. ## Core Methodology
  51. The skill follows a 5-phase process:
  52. 1. **Identify Problem Essence** - Strip away details to find the core problem
  53. 2. **Challenge Assumptions** - Question every assumption systematically
  54. 3. **Establish Ground Truths** - Identify irreducible facts
  55. 4. **Reason Upward** - Build solutions from fundamentals
  56. 5. **Validate Reasoning** - Ensure every decision traces to ground truths
  57. ## Output Format
  58. The skill produces structured analysis:
  59. ```markdown
  60. ## First Principles Analysis: [Topic]
  61. ### 1. Problem Essence
  62. ### 2. Assumptions Challenged (table)
  63. ### 3. Ground Truths
  64. ### 4. Reasoning Chain
  65. ### 5. Conclusion
  66. ```
  67. ## Complementary Skills
  68. This skill works well with:
  69. - **5-Whys** - Dig deeper when assumptions surface
  70. - **Trade-off Analysis** - Evaluate options against fundamentals
  71. - **Pre-mortem** - Stress-test reasoning before implementation
  72. ## Contributing
  73. Contributions welcome! Please feel free to submit issues or pull requests.
  74. ## License
  75. MIT License - see [LICENSE](LICENSE) file.
  76. ## Author
  77. Created for use with Claude Code's skill system.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.