
Feynman-technique code debriefs and diff explanations for AI coding agents
Feynman-technique code debriefs and diff explanations for AI coding agents
·
simplifeyn)An Agent Skill that explains code changes, PR diffs, and feature implementations the way Richard Feynman explained physics: physical mechanism first, one honest everyday analogy with its exact limits, and an audience-calibrated ladder from vibe coder to system maintainer.
Compatible with Claude Code, Google Antigravity CLI, OpenAI Codex CLI, Cursor, and any tool supporting the Agent Skills open standard.
When AI agents implement features or fix bugs, they default to reciting files and jargon:
"I updated
UserServiceto inject an LRU cache with eviction policies and wrapped the query in thread-safe locks, optimizing latency and streamlining database interactions."
Why this fails:
simplifeyn forces the AI coding agent into Richard Feynman's cognitive model while enforcing strict brevity (< 170 prose words, zero conversational filler):
basically, simply, optimized, streamlined).--full):
Richard Feynman's approach to science and engineering rested on two immutable foundations:
The Physical Experiment ("The Ice-Water Test"): During the 1986 Rogers Commission hearing on the Challenger disaster, NASA officials presented dense statistical risk models. Feynman cut through the bureaucratic fog with a simple tabletop experiment: he clamped a sample of the shuttle's rubber O-ring seal and dunked it into a glass of ice water at his desk. When released, the stiff rubber failed to rebound. In under ten seconds, everyone saw the causal truth.
"It doesn't matter how beautiful your theory is, it doesn't matter how smart you are. If it doesn't agree with experiment, it's wrong." For vibe coders directing AI coding agents, theoretical jargon ("optimizes mutation lifecycle") is unprovable without physical verification. The Ice-Water Test requires the AI to give you one concrete, 10-second sensory action (e.g., throttling DevTools to offline, clicking twice rapidly, inspecting a network panel) to witness the mechanism work.
The Boundary Condition ("Where the Machine Snaps"): Feynman taught that an engineer does not understand a physical machine until they know the exact conditions under which it ceases to work. In the Challenger investigation, the O-ring was not flawed in general; it lost elasticity specifically below 32 deg F (0 deg C). In software, while Where the Picture Breaks defines the limits of the everyday metaphor, Where the Machine Snaps identifies the physical stress threshold of the code itself. For vibe coders who build via iterative "prompt stacking", this prevents disaster: if the AI uses an in-memory dictionary or non-idempotent mutation, naming where the machine snaps alerts the developer before their next prompt triggers a catastrophic regression.
-> See a complete Before vs. After Worked Example
skills.sh Ecosystem (Recommended)Install directly using the open Agent Skills ecosystem installer (skills.sh):
npx skills add builtbyjuls/simplifeynClone and inspect the repository before running the local installer:
git clone https://github.com/builtbyjuls/simplifeyn.git
cd simplifeyn
# Auto-detect your installed tools and install
./install.sh
# Or target a specific client:
./install.sh --antigravity # Installs to ~/.gemini/config/skills/
./install.sh --claude # Installs to ~/.claude/skills/
./install.sh --codex # Installs to ~/.agents/skills/
./install.sh --cursor # Installs to ~/.cursor/skills/
./install.sh --project # Installs to current repo: .agents/skills/Copy the simplifeyn folder into whichever skill directory your CLI uses:
~/.gemini/config/skills/simplifeyn/~/.claude/skills/simplifeyn/~/.agents/skills/simplifeyn/~/.cursor/skills/simplifeyn/[!NOTE] Installation paths for Cursor (
~/.cursor/skills), Codex (~/.agents/skills), and Antigravity (~/.gemini/config/skills) reflect typical convention across multi-agent environments but may vary depending on CLI version. In addition, while the target budget is under 170 prose words, complex real-world diffs may expand up to the hard ceiling of 250 words.
Turn Feynman debriefing on or off dynamically during your session:
# Turn ON: every subsequent code change will conclude with a Feynman Debrief
/simplifeyn on
# Check whether debrief mode is currently active
/simplifeyn status
# Turn OFF: return to normal output style
/simplifeyn off
# Skip the debrief for the current turn only (while leaving persistent mode active):
/simplifeyn skipNote on Session State: Agent Skills provide instructions to your AI coding agent, not an OS background process. Mode 1 is an in-session instruction (best-effort across long context windows). For a guaranteed, repository-wide rule across all sessions and agent restarts, use Mode 4: Always-On Project Rule below.
Simplifeyn avoids over-explaining trivial edits (like pure documentation or lockfile updates). The skill applies automatic complexity gating:
[Simplifeyn debrief skipped: cosmetic/trivial change without causal mechanism shift]):
.md, .txt, .rst, lockfiles (package-lock.json, pnpm-lock.yaml, Cargo.lock), or repository ignores (.gitignore, .editorconfig, LICENSE).docs:, chore:, or style:.timeout = 0), retries (max_retries = 0), arithmetic (+ vs -), index math (len(xs) - 1), bounds (>= vs >), permissions (0o777), users (USER root), shell flags (set +e), or protocols (http vs https) alter runtime behavior and trigger a debrief.AUTH_REQUIRED), SSL/TLS settings, permissions, or CI test steps.feat:, perf:, non-trivial fix:, structural refactor:./simplifeyn or user asks for explanation.for <audience> or --for=<audience>)Calibrate the debrief to your technical comfort level (vibe-coder, junior-dev, senior-dev):
# Defaults to vibe-coder (app behavior, prompt safety, 1 targeted ladder rung):
/simplifeyn
# Target learning junior engineers (code symbols, patterns, trade-offs):
/simplifeyn for junior-dev
# Target systems maintainers (invariants, concurrency, scale limits):
/simplifeyn for senior-dev
# Combine audience with a themed lens:
/simplifeyn for junior-dev as gaming
/simplifeyn for senior-dev as transitas <theme> or --as=<theme>)Direct the debrief toward a specific physical domain (kitchen, warehouse, workshop, transit, office, gaming):
# One-shot with specific lens:
/simplifeyn as kitchen
/simplifeyn --as=warehouse
/simplifeyn HEAD~1 as transit
# Persistent mode locked to a lens:
/simplifeyn on as workshopIf a requested lens fundamentally distorts the code mechanism, Simplifeyn enforces Feynman honesty: it outputs a 1-line disclaimer and falls back to the accurate domain.
When re-invoking /simplifeyn on the same commit with a different lens or theme (e.g. /simplifeyn as transit after /simplifeyn for junior-dev), Simplifeyn anchors to the prior debrief in conversation history to prevent semantic drift:
as <theme>) regenerates only Section 2 (The Tangible Picture & ASCII diagram). Switching audience (for <audience>) swaps only Section 3 (The Ladder) while re-framing Section 4 and 5 in that role's vocabulary.Inspect or swap individual sections without re-running the entire 6-section debrief:
# Output only a new Tangible Picture & ASCII diagram for a specific theme:
/simplifeyn theme transit
/simplifeyn theme warehouse
# Output only the targeted ladder rung for a specific audience:
/simplifeyn ladder junior-dev
/simplifeyn ladder senior-devRun once for the latest change or a specific commit without enabling session persistence:
/simplifeyn
# or for a specific commit:
/simplifeyn HEAD~1Or ask the agent in plain language:
"Explain what you just implemented using the Feynman technique."
If you want your agent to conclude every feature implementation or bug fix with a Feynman Debrief automatically across the whole repo, add this block to your project's AGENTS.md, CLAUDE.md, or GEMINI.md:
## Post-Implementation Debrief
Whenever you complete a feature implementation, bug fix, or significant code modification, conclude your response with a lean Feynman Debrief (< 170 words prose, zero conversational preamble):
1. In One Sentence: The physical delta without buzzwords (1 sentence).
2. The Tangible Picture: One mechanical analogy and where the picture breaks, with an ASCII mechanism flow diagram (1-2 sentences).
3. The Ladder: 1 targeted single-line rung for active audience (default vibe-coder: Level (Vibe Coder)) or all 3 progressive rungs if requested with --full (Level 0 / Vibe Coder -> Level 1 / Junior Dev -> Level 2 / Senior Dev).
4. The Ice-Water Test: 1 physical action in the browser/terminal to observe the mechanism (1 sentence).
5. Where the Machine Snaps: 1 code boundary limit / prompt-stacking failure condition (1 sentence).
6. What Was Left Out: Deferred concerns and assumptions (1 line).
7. Lens Footer: Suggest alternative lenses.
If the change is trivial (pure docs, lockfiles, formatting), output a 1-line note and append:
`[Simplifeyn debrief skipped: cosmetic/trivial change without causal mechanism shift]`Explain pull requests automatically using the Richard Feynman technique on every PR by integrating the Simplifeyn PR Reviewer Action into your CI pipeline:
# .github/workflows/simplifeyn.yml
name: Simplifeyn PR Review
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
pull-requests: write
jobs:
feynman-review:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Simplifeyn PR Reviewer
id: simplifeyn
uses: builtbyjuls/simplifeyn@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
api-key: ${{ secrets.GEMINI_API_KEY || secrets.ANTHROPIC_API_KEY || secrets.OPENAI_API_KEY }}
audience: 'vibe-coder' # vibe-coder (default) | junior-dev | senior-dev | full
skip-cosmetic: 'true' # skips trivial doc/lockfile PRs automatically
strict-audit: 'true' # enforces < 170 words and zero buzzwords
step-summary: 'true' # renders markdown debrief in GitHub Actions summary| Input | Description | Default |
|---|---|---|
github-token | GitHub token for posting pull request comments | ${{ github.token }} |
api-key | API key for model provider (Gemini, Anthropic, or OpenAI) | "" |
provider | LLM provider (gemini, anthropic, openai, mock, auto) | 'auto' |
model | Specific model identifier | "" |
audience | Audience calibration (vibe-coder, junior-dev, senior-dev, full) | 'vibe-coder' |
theme | Physical analogy domain (kitchen, warehouse, workshop, transit, etc.) | "" |
skip-cosmetic | Automatically skip trivial doc/formatting PRs | 'true' |
strict-audit | Strictly enforce < 170 prose words and zero buzzwords | 'true' |
step-summary | Write debrief to GitHub Actions Step Summary ($GITHUB_STEP_SUMMARY) | 'true' |
dry-run | Print debrief to stdout without posting comment | 'false' |
| Output | Description |
|---|---|
debrief | The generated Feynman debrief markdown text |
skipped | Whether the debrief was skipped due to trivial/cosmetic diff (true or false) |
comment-posted | Whether the comment was successfully posted to the PR (true or false) |
This repository is built with Test-Driven Development (TDD) and includes an automated audit linter to verify that explanations adhere to Feynman principles:
Scope of the Linter: The linter verifies structural sections, word count boundaries, banned buzzwords, and stylistic tone (heuristic form check). It does not evaluate the factual domain accuracy of technical claims.
# Run the test suite
python3 -m unittest discover tests
# Audit an explanation draft
python3 scripts/audit_debrief.py my_explanation.md
# Or via pipe:
cat response.txt | python3 scripts/audit_debrief.py --stdin
# Check if a git diff warrants a debrief (Complexity Gating)
python3 scripts/audit_debrief.py --check-diff git_diff.patch
# Or pass commit message to test conventional commit heuristics:
python3 scripts/audit_debrief.py --check-diff --commit-msg "docs: update guide" git_diff.patch
# Score an explanation with the Feynman Index (0-100 Scorecard)
python3 scripts/eval_runner.py my_explanation.md
# Run the automated benchmark leaderboard across all model transcript fixtures
python3 scripts/eval_runner.py --benchmarkThe Feynman Index evaluates technical explanations across 5 pedagogical pillars:
vibe-coder, junior-dev, senior-dev, or --full).simplifeyn/
|-- SKILL.md # Main Agent Skill specification
|-- README.md # Documentation and guide
|-- action.yml # Reusable GitHub Action for PR reviews
|-- install.sh # Universal installer
|-- LICENSE # MIT License
|-- references/
| |-- voice.md # Style forensics, banned buzzwords, sensory verbs
| |-- analogies.md # Reference catalog of computing analogies & breaking points
| |-- ladder.md # Audience calibration (Vibe Coder -> Junior -> Senior)
| \-- failure-modes.md # 5 critical ways technical explanations fail & fixes
|-- assets/
| \-- worked-examples.md # Real PR diff with Before/After contrast
|-- scripts/
| |-- audit_debrief.py # Automated linter against lazy jargon
| |-- eval_runner.py # Feynman Index evals & benchmark leaderboard harness
| |-- get-diff.sh # Git diff extractor helper
| \-- pr_reviewer.py # GitHub Action PR Reviewer engine
\-- tests/ # Automated TDD test suitesimplifeyn adheres strictly to the security expectations of the Agent Skills standard and Trust Hub audits:
install.sh operates 100% locally on existing files within a cloned repository and performs zero remote downloads or network calls.scripts/get-diff.sh only executes read-only git status and diff commands (git rev-parse, git ls-files, git diff, git show). It never modifies repository state, writes to untrusted locations, or touches the network.scripts/audit_debrief.py is a self-contained Python heuristic linter that analyzes text structure and string length. It has zero network connectivity and executes zero external subcommands during debrief analysis.<untrusted_diff> and </untrusted_diff> boundary markers with nested tag escaping.Contributions and feedback are welcome! Areas to explore:
references/analogies.md.assets/worked-examples.md.tests/.This project is licensed under the MIT License - see the LICENSE file for details.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/simplifeyn-simplifeyn to learn what the "Simplifeyn (simplifeyn)" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
npx skills add builtbyjuls/simplifeynThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/simplifeyn-simplifeyn)Nothing comparable is listed yet.
v0.1.0v0.1.0 - Initial Public ReleaseRelease notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "simplifeyn-simplifeyn" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.