awesome-skills/first-principles-skill instruction manual

1. Purpose, scope, and Claude Code classification

`first-principles-skill` is a Markdown-based Claude Code skill for analyzing decisions from fundamental facts instead of copying conventions or reasoning by analogy. Its documented uses are architecture evaluation, design review, questioning best practices, breaking through inadequate conventional solutions, making long-lived foundational decisions, challenging legacy assumptions, and designing systems without cargo-culting existing patterns.

**Claude Code classification:** **context injection**, installed as a **Claude extension/skill**. The evidence is the `SKILL.md` file, whose frontmatter names the skill, describes activation phrases, and supplies a procedural method that Claude Code can load into context. The repository does not document an executable program, MCP server, hook, model provider, or standalone application. It changes Claude’s reasoning instructions rather than adding callable software tools. This classification is high confidence because both the repository description and first-party README explicitly call it a Claude Code skill, while the installation places its files under a Claude-related skills directory.

The skill’s intended result is not a guaranteed perfect answer. It provides a disciplined way to expose assumptions, identify ground truths, derive a minimally sufficient solution, and show how each design choice follows from a real need. It explicitly preserves practical constraints and does not assume that all established solutions are wrong. The supplied skill version is `0.2.0`, and the repository metadata identifies the public repository as `awesome-skills/first-principles-skill` under the MIT License.

2. Installation and repository-path caveat

The README documents two installation methods. Both place the entire repository at `~/.claude/plugins/superclaude/skills/first-principles`, preserving `SKILL.md`, references, and examples together.

Option 1: clone, then copy

# 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

This creates a separate installed copy. Later changes in the cloned checkout are therefore not documented as automatically propagating to the installed directory.

Option 2: clone, then 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

This links the Claude-facing path to the checkout under `~/skills`. The README does not document update, uninstall, migration, verification, or troubleshooting commands, so none should be inferred from these examples.

**Important provenance caveat:** the commands in the supplied README use the owner `tt-a1i`, but the supplied GitHub metadata identifies the current repository as `awesome-skills/first-principles-skill`. The commands above are reproduced because they are the only first-party installation commands supplied; their current target was not independently verified. The files also do not explain whether the `superclaude` directory requires another package, which Claude Code versions recognize this path, or whether parent directories are created automatically. Confirm the repository destination and local Claude Code skill layout before relying on either method.

3. Activation, appropriate uses, and example requests

The skill is described as activating automatically when a request asks for first-principles analysis or challenges whether a design is justified. Documented English triggers include “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,” and “challenge assumptions.” Documented Chinese triggers include “第一性原理,” “从根本分析,” “从零开始思考,” “这个设计合理吗,” “为什么要这样做,” “有没有更好的方案,” and “挑战假设.”

A source-supported request from the README is:

用第一性原理分析一下我们是否应该采用微服务架构

The expected behavior is a structured analysis of the microservices decision, beginning with the actual problem and success criteria rather than assuming that microservices are required. The README’s abbreviated example frames possible goals as faster development, independent deployment, and independent scaling, then questions assumptions such as whether a modern application necessarily needs microservices and whether team size supports the added complexity.

Use the skill for consequential choices where hidden assumptions matter: selecting an architecture, reviewing a design, reconsidering a legacy constraint, or deciding whether a popular pattern fits the present context. The skill says not to spend unlimited time on every decision, so routine or low-impact choices do not require the full process. Activation is described through phrases and the `SKILL.md` description; no explicit slash command, configuration switch, or invocation API is documented.

4. The five-phase first-principles process

Phase 1 — Identify the problem’s essence State exactly what must be solved, separate symptoms from causes, and define measurable success. Ask what job must be done, what users would need if the current system did not exist, and which outcome matters regardless of implementation. The point is to express the problem as an outcome rather than prematurely naming a solution.

Phase 2 — Challenge all assumptions List explicit assumptions, surface conventions being followed implicitly, and test whether each item is a true constraint. Examine technical assumptions (“Must we use this technology or pattern?”), business assumptions (“Is this requirement fixed?”), resource assumptions (“Is this limit real or perceived?”), and historical assumptions (“Why was this originally decided?”). Treat claims such as “we’ve always done it this way,” “industry standard says,” “everyone uses X,” or “that is too simple” as warning signs requiring evidence.

Phase 3 — Establish ground truths Identify facts that cannot be reduced further: physical or mathematical constraints, business invariants, and fundamental user needs. A candidate ground truth should be provable rather than merely popular, resist further decomposition, and cause definite failure if violated.

Phase 4 — Reason upward Begin with the simplest solution that satisfies those truths. Add elements only when each can justify its complexity. The documented progression is `Ground Truth → Minimal Solution → Justified Additions → Final Design`.

Phase 5 — Validate the reasoning Trace every decision back to a fundamental need, identify weak links that still depend on assumptions, and stress-test what could break the solution. The result should make both the supporting logic and remaining uncertainty visible.

5. Required analysis structure and how to read it

The skill documents a five-part response format. A conforming analysis can use this source-provided template:

## First Principles Analysis: [Topic]

### 1. Problem Essence
**Core problem:** [One sentence]
**Success criteria:** [Measurable outcomes]

### 2. Assumptions Challenged
| Assumption | Challenge | Verdict |
|------------|-----------|---------|
| [Assumption] | [Why question it] | [Keep/Discard/Modify] |

### 3. Ground Truths
- [Irreducible fact 1]
- [Irreducible fact 2]
- [Irreducible fact 3]

### 4. Reasoning Chain
Ground Truth → [Step 1] → [Step 2] → Solution

### 5. Conclusion
**Recommended approach:** [Description]
**Key insight:** [What the first principles analysis revealed]
**Trade-offs acknowledged:** [What we're accepting]

“Problem Essence” should distinguish the desired outcome from the current implementation. “Assumptions Challenged” records what was questioned, why it may be unsafe to accept, and whether it should be retained, discarded, or modified. “Ground Truths” lists only irreducible facts, not preferences disguised as facts. “Reasoning Chain” makes the derivation auditable by showing how the proposed solution follows from those facts. “Conclusion” states the recommendation without hiding the trade-offs accepted.

The format is part of the skill’s documented behavior, but it is not a machine-enforced schema. The repository supplies no parser, validator, or automated test for the response. Measurable success criteria and evidence-backed ground truths therefore remain important for a human reviewer assessing whether the analysis genuinely followed the method.

6. Diagnostic patterns and complementary thinking tools

The skill documents three recurring failure patterns.

**Complexity trap:** the proposed system contains more machinery than the core problem requires. Remove one component and ask whether the system still solves the essential problem. If it does, that component was not essential. Repeat until another removal would break core functionality. This is a test for necessity, not an instruction to ignore reliability, business, user, or physical constraints.

**Analogy trap:** the justification is that another company uses the same approach. Determine what problem that company was solving, whether your problem matches in every relevant dimension, and which constraints differ. An analogy may still provide evidence, but it does not replace a derivation from your own conditions.

**Legacy trap:** compatibility is maintained with a decision that may no longer help. Recover the original reason, check whether the old conditions still exist, and compare the real cost of changing with the continuing cost of maintenance.

Four complementary methods are documented. Use **5-Whys** when a surfaced assumption needs deeper root-cause investigation. Use **Trade-off Analysis** after identifying ground truths, comparing options against those fundamentals. Use a **Pre-mortem** before finalizing the recommendation to stress-test the reasoning chain. Use **Hypothesis Testing** when a supposed ground truth is uncertain and requires empirical validation. These methods supplement rather than replace the five phases. The repository describes them conceptually but provides no separate commands or bundled implementations for those complementary skills.

7. Boundaries, quality checks, and responsible interpretation

The documented method will systematically challenge assumptions, identify fundamentals, construct reasoning chains, and reveal cases where conventional wisdom does not apply. It will not reject every existing solution merely because it is conventional. It will not ignore practical constraints to achieve theoretical purity, spend unlimited time on every decision, or guarantee the objectively best solution. Its promise is improved reasoning transparency, not certainty.

Use the supplied checklist to review an analysis:

• The problem is stated in terms of outcomes rather than a preferred solution.
• All assumptions are explicitly listed.
• Each assumption is challenged and justified.
• Ground truths are identified and verified.
• The solution is built upward from those ground truths.
• Every design decision is traceable to a ground truth.
• The reasoning chain is documented.

A “ground truth” deserves particular scrutiny. According to the skill’s own test, it should not be further decomposable, should be provably true rather than commonly believed, and should lead to definite failure if violated. If evidence is missing, the integration table directs the analysis toward hypothesis testing instead of pretending uncertainty is fact.

The method’s output is advisory Markdown. No code execution, file modification, external research, quantitative model, or enforcement mechanism is documented. Users should independently validate factual premises and practical consequences, especially for architecture and other long-term decisions. The conclusion should retain acknowledged trade-offs and weak links rather than presenting the structured format as proof of correctness.

8. Repository contents, supporting material, licensing, and evidence limits

The documented repository layout contains `SKILL.md` as the main skill definition, `README.md` as the overview and installation guide, and `LICENSE` for the MIT License. The `references/` directory is said to contain `software-examples.md` with software-engineering case studies and `elon-musk-examples.md` with SpaceX and Tesla examples. The `examples/architecture-review.md` file is described as a complete first-principles review of a microservices decision.

Only `README.md` and `SKILL.md` were supplied here. The referenced case studies, complete architecture example, and license text were not included for inspection, although the GitHub metadata identifies the license as MIT. Accordingly, this manual does not reproduce or claim details from those absent files. The README welcomes issues and pull requests but documents no contribution workflow, branch policy, tests, formatting command, or release procedure.

The repository metadata identifies a public, non-archived repository whose default branch is `main`, with no primary programming language reported. This is consistent with the supplied Markdown-only behavior, but the complete tree was not independently inspected. There is also a source inconsistency: current metadata names `awesome-skills/first-principles-skill`, while the README installation examples clone `tt-a1i/first-principles-skill`. Finally, no minimum Claude Code version, compatibility matrix, installation verification procedure, update process, uninstall process, automated evaluation, telemetry statement, or security audit is documented in the supplied evidence. Treat automatic triggering and host-path compatibility as repository claims that may depend on the user’s Claude Code setup.