Feynman Rigorous Learning

Build intuition, reconstruct formalism, test transfer, and audit what was actually learned.

English | 简体中文

Feynman Rigorous Learning is a portable Agent Skill for mathematics, statistics, computer science, and other technical subjects. It combines a four-phase concept workflow with complete lesson deep-dives, ordered bilingual exercise analysis, evidence-aware learning synthesis, and dependency-aware Mermaid mind maps.

It does not equate exposure with understanding or understanding with mastery. Every conclusion stays tied to observable evidence.

Install in one command

Recommended — a current GitHub CLI build with gh skill:

gh skill install 0neblaze/feynman-rigorous-learning feynman-rigorous-learning \
  --agent universal --scope user --pin v1.0.0

macOS, Linux, or WSL:

curl -fsSL https://raw.githubusercontent.com/0neblaze/feynman-rigorous-learning/v1.0.0/install.sh \
  | sh -s -- --ref v1.0.0

Windows PowerShell:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/0neblaze/feynman-rigorous-learning/v1.0.0/install.ps1))) -Ref v1.0.0

The standalone installers default to the platform-neutral universal client and user scope. They refuse to overwrite an existing installation unless --force or -Force is explicit. For a safer review-first workflow, see Inspect before running.

Contents

• Why this skill
• Learning modes
• Workflow
• Mandatory-step governance
• Evidence model
• Language behavior
• Example requests
• Installation options
• Security and permission boundaries
• Project structure
• Validation
• License

Why this skill

Technical learning often fails in one of three ways:

• intuition is vivid but mathematically inaccurate;
• formal definitions and proofs are memorized without a working mechanism; or
• completed explanations are reported as mastery without an independent test.

This skill connects intuition to formal structure, preserves assumptions and quantifiers, and keeps coverage, understanding, and mastery as separate claims.

Learning modes

Concept Learning Mode

Four independent but ordered prompts:

1. Intuition Builder — explains purpose, mechanism, a bounded analogy or simplified model, and ends with a reverse test.
2. Feynman Interrogator — finds jargon gaps, logical jumps, circular explanations, boundary errors, and analogy overreach without teaching around the learner's gap.
3. Formal Reconstruction — maps intuition to mathematical objects, notation, definitions, theorem structure, and proof architecture.
4. Mastery and Transfer Examiner — tests bidirectional translation, near misses, boundaries, unfamiliar transfer, reasoning prediction, and final compression.

Lesson Deep-Dive Mode

The agent pre-reads the complete accessible lesson, identifies its throughline, creates a page-level Coverage Ledger, teaches every page in source order, expands load-bearing reasoning, and finishes with a coverage audit, synthesis, and mind map.

Long sources are handled as contiguous logical blocks. A response limit is a reason to pause at a sound boundary, not to omit pages, compress away necessary reasoning, or pretend the lesson is complete.

Exercise Deep-Analysis Mode

The first response restates the workflow and solves nothing. After the user says start, each batch contains exactly four top-level questions in original order, except the final batch when fewer than four remain. Every question includes:

• the complete original statement and complete Chinese–English translation;
• problem decomposition;
• method choice and rationale;
• the definitions, assumptions, identities, or theorems that justify the method;
• a fully justified step-by-step solution;
• a clearly marked final answer;
• verification;
• tested knowledge;
• cautiously inferred examiner intent; and
• common errors.

The agent stops after each batch and waits for continue. Exercise mode uses direct, rigorous solution work by default; it enters P1–P4 only when the user explicitly requests a conceptual detour.

Workflow

flowchart LR
    A["Source and readability check"] --> B{"Route"}
    B -->|Concept| C["P1 Intuition"]
    C --> D["P2 Interrogation"]
    D --> E["P3 Formal reconstruction"]
    E --> F["P4 Transfer testing"]
    B -->|Lesson| G["Whole-source map"]
    G --> H["Coverage Ledger and logical blocks"]
    B -->|Exercises| I["Restate rules only"]
    I --> J["Start: four top-level questions"]
    F --> K["Evidence-aware synthesis"]
    H --> K
    J --> K
    K --> L["Mermaid mind map and validation disclosure"]

Loading

Mandatory-step governance

The default workflow may not be silently skipped, merged, reordered, shortened, or downgraded.

A user may explicitly authorize one named step or a clearly bounded set of steps to be skipped. Before applying that authorization, the agent records who authorized it, the exact scope and reason, its impact on coverage, understanding, mastery, and validation, the residual risks, and how to restore the omitted work.

“Be faster” or “keep it short” is not a skip authorization. Ambiguous requests require clarification. After an authorized skip, affected Coverage, Mastery, or Validation remains partial, untested, blocked, or skipped—it is never reported as complete.

Safety, permission, truthfulness, and required input-readability checks cannot be bypassed by an ordinary learning-workflow authorization.

Evidence model

Final reports use stable English keys while explanatory prose follows the user's language:

Key	Meaning	Evidence required
source_coverage	What the source contains and what was accounted for	Page, section, or question ledger
established_understanding	What the learner's explanations or comprehension checks support	Learner responses short of independent transfer
demonstrated_mastery	What independent testing supports within a stated scope	Learner test, solution, or transfer evidence
pending_review	What remains unreadable, skipped, untested, incorrect, or unresolved	Open ledger items and recovery actions

Mastery levels are an instructional rubric, not a scientifically calibrated measurement. The skill does not invent pass percentages, confidence levels, time limits, or hidden thresholds.

Language behavior

User-facing explanations follow the user's language. Stable state keys, filenames, prompt identifiers, and rubric labels remain English for portability. Exercise statements are always preserved as a complete Chinese–English pair.

The canonical SKILL.md, prompts, references, and examples are maintained in English.

Example requests

Use the four-stage workflow to help me understand eigenvalues.

Give a complete deep dive of this lecture PDF. Explain every page, preserve the
proof assumptions, maintain a Coverage Ledger, and finish with a mind map.

Analyze this exercise set. First restate the workflow without solving anything.
After I say start, solve four top-level questions per batch in source order.

Skip only the optional analogy on pages 12–13. Record the authorization and its
impact; keep all source coverage, formal reasoning, and validation steps.

More interaction patterns are documented in usage examples.

Installation options

Select an agent and scope

The official GitHub CLI supports host-specific installation and provenance metadata:

gh skill install 0neblaze/feynman-rigorous-learning feynman-rigorous-learning --agent claude-code --scope user --pin v1.0.0
gh skill install 0neblaze/feynman-rigorous-learning feynman-rigorous-learning --agent codex --scope user --pin v1.0.0
gh skill install 0neblaze/feynman-rigorous-learning feynman-rigorous-learning --agent github-copilot --scope user --pin v1.0.0
gh skill install 0neblaze/feynman-rigorous-learning feynman-rigorous-learning --agent opencode --scope user --pin v1.0.0

The standalone installers accept universal, claude-code, codex, github-copilot, and opencode, plus user or project scope:

sh install.sh --agent codex --scope project --ref v1.0.0
sh install.sh --from-local . --dest /tmp/agent-skills --dry-run

./install.ps1 -Agent codex -Scope project -Ref v1.0.0
./install.ps1 -FromLocal . -Destination ./tmp/agent-skills -DryRun

Client	Project scope	User scope
Universal	.agents/skills	~/.agents/skills
Claude Code	.claude/skills	~/.claude/skills
Codex	.agents/skills	~/.codex/skills
GitHub Copilot	.agents/skills	~/.copilot/skills
OpenCode	.agents/skills	~/.config/opencode/skills

Use --dest or -Destination to override the parent skills directory. Use --force or -Force only when replacement and a timestamped backup are intended.

Inspect before running

macOS, Linux, or WSL:

(
  installer=$(mktemp "${TMPDIR:-/tmp}/feynman-rigorous-learning-install.XXXXXX") || exit
  trap 'rm -f "$installer"' EXIT HUP INT TERM
  curl -fsSLo "$installer" \
    https://raw.githubusercontent.com/0neblaze/feynman-rigorous-learning/v1.0.0/install.sh &&
    less "$installer" &&
    sh "$installer" --ref v1.0.0
)

Windows PowerShell:

$installer = Join-Path ([System.IO.Path]::GetTempPath()) ("feynman-rigorous-learning-install-$([guid]::NewGuid().ToString('N')).ps1")
try {
    Invoke-WebRequest https://raw.githubusercontent.com/0neblaze/feynman-rigorous-learning/v1.0.0/install.ps1 -OutFile $installer -ErrorAction Stop
    Get-Content $installer -ErrorAction Stop
    & $installer -Ref v1.0.0
} finally {
    Remove-Item -LiteralPath $installer -Force -ErrorAction SilentlyContinue
}

Security and permission boundaries

The standalone installers:

• download a GitHub archive and extract only skills/feynman-rigorous-learning;
• reject unsafe archive paths, links, special files, wrong names, wrong authors, invalid versions, and incomplete packages;
• never execute a script from inside the Skill;
• stage the complete Skill before installation;
• reject replacement by default;
• serialize installation with an owned lock;
• create a randomized timestamped backup for an explicit forced replacement;
• use no-clobber checks and roll back after a failed replacement; and
• reject symbolic-link or reparse-point destinations.

The learning Skill itself does not require a network service, MCP server, or provider-specific model. It does not modify source material or write persistent learning state without explicit authorization for the exact write, destination, and scope.

agents/openai.yaml is optional display metadata for compatible clients. The core workflow does not read it or depend on it.

Project structure

.
|-- .github/workflows/validate.yml     # Cross-platform validation matrix
|-- README.md
|-- README.zh-CN.md
|-- LICENSE
|-- install.sh
|-- install.ps1
|-- tests/                             # Static and installer security tests
`-- skills/
    `-- feynman-rigorous-learning/
        |-- SKILL.md
        |-- LICENSE
        |-- agents/openai.yaml
        |-- prompts/
        |   |-- 01-intuition-builder.md
        |   |-- 02-feynman-interrogator.md
        |   |-- 03-formal-reconstruction.md
        |   `-- 04-mastery-transfer-examiner.md
        |-- references/
        |   |-- lesson-deep-dive-mode.md
        |   |-- exercise-deep-analysis-mode.md
        |   `-- mind-map-and-synthesis.md
        `-- examples/usage-examples.md

The source archive's self-referential manifest.txt was intentionally removed. Git trees, tags, releases, and installer source validation provide maintained provenance without a duplicate file list that can drift.

Validation

Release validation covers:

• Agent Skills frontmatter and directory naming;
• gh skill publish --dry-run;
• the official quick_validate.py in an isolated PyYAML environment;
• POSIX shell and PowerShell syntax;
• YAML, Markdown links and anchors, internal references, UTF-8, and file inventory;
• secrets, local absolute paths, provider binding, binary files, and generated cache files;
• first install, repeat refusal, forced replacement, backup, rollback, dry-run, missing dependencies, destination mappings, remote archives, locks, signals, root paths, symbolic links or reparse points, and no-clobber behavior; and
• independent Chinese and English behavior tests, including mandatory-step authorization.

License

Distributed under the MIT License. Maintained by 0neblaze.