{"id":"6c54218b-3deb-4302-8e6a-863cb1bfc4d2","slug":"simplifeyn","kind":"skill","name":"simplifeyn","summary":"Feynman-technique code debriefs and diff explanations for AI coding agents","owner":"builtbyjuls","repoUrl":"https://github.com/builtbyjuls/simplifeyn","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-12T10:41:59.000Z","addedAt":"2026-10-21T11:46:05.776Z","logoUrl":"https://avatars.githubusercontent.com/u/323391382?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["antigravity","claude-code","code-review","developer-tools","feynman-technique","gemini-cli"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T19:01:43.315Z","sample":false,"url":"https://conduits.dev/tools/simplifeyn","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Simplifeyn (`simplifeyn`)\n\n[![Agent Skills Standard](https://img.shields.io/badge/Agent%20Skills-Standard-blue.svg)](https://agentskills.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)\n[![CI](https://github.com/builtbyjuls/simplifeyn/actions/workflows/ci.yml/badge.svg)](https://github.com/builtbyjuls/simplifeyn/actions/workflows/ci.yml)\n[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Simplifeyn%20PR%20Reviewer-purple.svg?logo=github)](https://github.com/marketplace/actions/simplifeyn-pr-reviewer)\n\n> **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.**\n\nCompatible with **Claude Code**, **Google Antigravity CLI**, **OpenAI Codex CLI**, **Cursor**, and any tool supporting the [Agent Skills open standard](https://agentskills.io).\n\n---\n\n## The Problem with AI Code Summaries\n\nWhen AI agents implement features or fix bugs, they default to reciting files and jargon:\n\n> *\"I updated `UserService` to inject an LRU cache with eviction policies and wrapped the query in thread-safe locks, optimizing latency and streamlining database interactions.\"*\n\n**Why this fails:**\n1. **Recites names instead of physical causality:** It tells you what classes exist, not what actually moves under the hood.\n2. **Hides trade-offs and limits:** It pretends the solution has zero costs or memory overhead.\n3. **Alienates reviewers:** Teammates, junior developers, and product managers can't evaluate whether the mental model is sound.\n\n---\n\n## The Simplifeyn Alternative\n\n`simplifeyn` forces the AI coding agent into Richard Feynman's cognitive model while enforcing strict brevity (< 170 prose words, zero conversational filler):\n\n1. **In One Sentence:** The physical delta in plain language (1 sentence). Zero buzzwords (`basically`, `simply`, `optimized`, `streamlined`).\n2. **The Tangible Picture & Limits:** One sensory, mechanical analogy, ASCII flow diagram, and its breaking limit in the same breath (1-2 sentences).\n3. **The Ladder:** Calibrated to the active audience (defaults to 1 targeted single-line rung; all 3 rungs with `--full`):\n   * **Level (Vibe Coder):** (Default) App behavior, state/event flow, and prompt-stacking safety without syntax jargon.\n   * **Level (Junior Dev):** Code symbols, data structures, and foundational programming patterns.\n   * **Level (Senior Dev):** Invariants, concurrency boundaries, latency/memory trade-offs, and scale ceilings.\n4. **The Ice-Water Test:** 1 physical sensory action in the browser, terminal, or DevTools to watch the mechanism work right now (1 sentence).\n5. **Where the Machine Snaps:** The exact code stress boundary, concurrency race, or prompt-stacking failure limit (1 sentence).\n6. **What Was Left Out:** Explicitly names what was simplified or deferred in 1 line.\n\n### The Feynman Philosophy: Experiments & Physical Boundaries\n\nRichard Feynman's approach to science and engineering rested on two immutable foundations:\n\n1. **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.\n   > *\"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.\"*\n   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.\n\n2. **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).\n   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.\n\n### Brevity & Anti-Verbosity Constraints\n- **Word Budget:** Target < 170 words of explanatory prose (excluding diagram block & headings; hard ceiling 250 total words). Fits completely in a standard terminal viewport without scrolling.\n- **Zero Chat Filler:** No preambles (\"Sure!\", \"Here is what changed:\"), no postambles (\"Hope this helps!\"). Starts directly with the first section heading and stops after the last bullet.\n\n**-> [See a complete Before vs. After Worked Example](./assets/worked-examples.md)**\n\n---\n\n## Installation\n\n### Via `skills.sh` Ecosystem (Recommended)\n\nInstall directly using the open Agent Skills ecosystem installer (`skills.sh`):\n\n```bash\nnpx skills add builtbyjuls/simplifeyn\n```\n\n### From Source (Review First)\n\nClone and inspect the repository before running the local installer:\n\n```bash\ngit clone https://github.com/builtbyjuls/simplifeyn.git\ncd simplifeyn\n\n# Auto-detect your installed tools and install\n./install.sh\n\n# Or target a specific client:\n./install.sh --antigravity   # Installs to ~/.gemini/config/skills/\n./install.sh --claude        # Installs to ~/.claude/skills/\n./install.sh --codex         # Installs to ~/.agents/skills/\n./install.sh --cursor        # Installs to ~/.cursor/skills/\n./install.sh --project       # Installs to current repo: .agents/skills/\n```\n\n### Manual Drop-in (One Folder)\n\nCopy the `simplifeyn` folder into whichever skill directory your CLI uses:\n\n* **Antigravity CLI:** `~/.gemini/config/skills/simplifeyn/`\n* **Claude Code:** `~/.claude/skills/simplifeyn/`\n* **OpenAI Codex CLI:** `~/.agents/skills/simplifeyn/`\n* **Cursor:** `~/.cursor/skills/simplifeyn/`\n\n> [!NOTE]\n> 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.\n\n---\n\n## Usage\n\n### Mode 1: Toggleable Session Mode (Recommended)\n\nTurn Feynman debriefing on or off dynamically during your session:\n\n```bash\n# Turn ON: every subsequent code change will conclude with a Feynman Debrief\n/simplifeyn on\n\n# Check whether debrief mode is currently active\n/simplifeyn status\n\n# Turn OFF: return to normal output style\n/simplifeyn off\n\n# Skip the debrief for the current turn only (while leaving persistent mode active):\n/simplifeyn skip\n```\n\n> **Note 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.\n\n### Complexity Gating: When Debriefs Run vs. Skip\n\nSimplifeyn avoids over-explaining trivial edits (like pure documentation or lockfile updates). The skill applies automatic complexity gating:\n\n* **Skipped (`[Simplifeyn debrief skipped: cosmetic/trivial change without causal mechanism shift]`):**\n  - Docs, Lockfiles & Ignores: Changes touching only `.md`, `.txt`, `.rst`, lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `Cargo.lock`), or repository ignores (`.gitignore`, `.editorconfig`, `LICENSE`).\n  - Cosmetic: Formatting, whitespace changes, or comment-only revisions with zero executable code modifications.\n  - Conventional commits: Commits prefixed with `docs:`, `chore:`, or `style:`.\n* **Debriefed:**\n  - Code & Config files are **never skipped by size**: Even 1-line changes to timeouts (`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.\n  - Causal mechanism shifts: Data flows through different paths, buffers, or states.\n  - Concurrency & Performance: Caching, locks, retries, jitter, debounce, or race conditions.\n  - New features & refactors: New endpoints, state machines, business logic.\n  - Security & Runtime Configs: Altering auth flags (`AUTH_REQUIRED`), SSL/TLS settings, permissions, or CI test steps.\n  - Conventional commits: `feat:`, `perf:`, non-trivial `fix:`, structural `refactor:`.\n  - Explicit invocation: `/simplifeyn` or user asks for explanation.\n\n\n### Mode 2: Audience Lenses (`for <audience>` or `--for=<audience>`)\n\nCalibrate the debrief to your technical comfort level (`vibe-coder`, `junior-dev`, `senior-dev`):\n\n```bash\n# Defaults to vibe-coder (app behavior, prompt safety, 1 targeted ladder rung):\n/simplifeyn\n\n# Target learning junior engineers (code symbols, patterns, trade-offs):\n/simplifeyn for junior-dev\n\n# Target systems maintainers (invariants, concurrency, scale limits):\n/simplifeyn for senior-dev\n\n# Combine audience with a themed lens:\n/simplifeyn for junior-dev as gaming\n/simplifeyn for senior-dev as transit\n```\n\n### Mode 3: Themed Lenses (`as <theme>` or `--as=<theme>`)\n\nDirect the debrief toward a specific physical domain (`kitchen`, `warehouse`, `workshop`, `transit`, `office`, `gaming`):\n\n```bash\n# One-shot with specific lens:\n/simplifeyn as kitchen\n/simplifeyn --as=warehouse\n/simplifeyn HEAD~1 as transit\n\n# Persistent mode locked to a lens:\n/simplifeyn on as workshop\n```\n\nIf 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.\n\n### Invariant Anchoring Protocol (Same Commit Preservation)\n\nWhen 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:\n* **Frozen Invariants:** Section 1 (In One Sentence), Section 4 (Verification Test), Section 5 (Failure Limit), and Section 6 (What Was Left Out) remain immutable facts of the commit.\n* **Variant Swap:** Switching theme (`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.\n\n### Mode 4: Targeted Micro-Commands\n\nInspect or swap individual sections without re-running the entire 6-section debrief:\n\n```bash\n# Output only a new Tangible Picture & ASCII diagram for a specific theme:\n/simplifeyn theme transit\n/simplifeyn theme warehouse\n\n# Output only the targeted ladder rung for a specific audience:\n/simplifeyn ladder junior-dev\n/simplifeyn ladder senior-dev\n```\n\n### Mode 5: One-Shot Command\n\nRun once for the latest change or a specific commit without enabling session persistence:\n\n```bash\n/simplifeyn\n# or for a specific commit:\n/simplifeyn HEAD~1\n```\n\nOr ask the agent in plain language:\n> *\"Explain what you just implemented using the Feynman technique.\"*\n\n### Mode 6: Always-On Project Rule\n\nIf 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`:\n\n```markdown\n## Post-Implementation Debrief\nWhenever 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):\n1. In One Sentence: The physical delta without buzzwords (1 sentence).\n2. The Tangible Picture: One mechanical analogy and where the picture breaks, with an ASCII mechanism flow diagram (1-2 sentences).\n3. 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).\n4. The Ice-Water Test: 1 physical action in the browser/terminal to observe the mechanism (1 sentence).\n5. Where the Machine Snaps: 1 code boundary limit / prompt-stacking failure condition (1 sentence).\n6. What Was Left Out: Deferred concerns and assumptions (1 line).\n7. Lens Footer: Suggest alternative lenses.\nIf the change is trivial (pure docs, lockfiles, formatting), output a 1-line note and append:\n`[Simplifeyn debrief skipped: cosmetic/trivial change without causal mechanism shift]`\n```\n\n### Mode 7: Automated GitHub Action PR Reviewer\n\nExplain pull requests automatically using the Richard Feynman technique on every PR by integrating the [Simplifeyn PR Reviewer](https://github.com/marketplace/actions/simplifeyn-pr-reviewer) Action into your CI pipeline:\n\n```yaml\n# .github/workflows/simplifeyn.yml\nname: Simplifeyn PR Review\non:\n  pull_request:\n    types: [opened, synchronize, reopened]\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  feynman-review:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n\n      - name: Run Simplifeyn PR Reviewer\n        id: simplifeyn\n        uses: builtbyjuls/simplifeyn@v1\n        with:\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n          api-key: ${{ secrets.GEMINI_API_KEY || secrets.ANTHROPIC_API_KEY || secrets.OPENAI_API_KEY }}\n          audience: 'vibe-coder'     # vibe-coder (default) | junior-dev | senior-dev | full\n          skip-cosmetic: 'true'      # skips trivial doc/lockfile PRs automatically\n          strict-audit: 'true'       # enforces < 170 words and zero buzzwords\n          step-summary: 'true'       # renders markdown debrief in GitHub Actions summary\n```\n\n#### Action Inputs\n\n| Input | Description | Default |\n| :--- | :--- | :--- |\n| `github-token` | GitHub token for posting pull request comments | `${{ github.token }}` |\n| `api-key` | API key for model provider (Gemini, Anthropic, or OpenAI) | `\"\"` |\n| `provider` | LLM provider (`gemini`, `anthropic`, `openai`, `mock`, `auto`) | `'auto'` |\n| `model` | Specific model identifier | `\"\"` |\n| `audience` | Audience calibration (`vibe-coder`, `junior-dev`, `senior-dev`, `full`) | `'vibe-coder'` |\n| `theme` | Physical analogy domain (`kitchen`, `warehouse`, `workshop`, `transit`, etc.) | `\"\"` |\n| `skip-cosmetic` | Automatically skip trivial doc/formatting PRs | `'true'` |\n| `strict-audit` | Strictly enforce < 170 prose words and zero buzzwords | `'true'` |\n| `step-summary` | Write debrief to GitHub Actions Step Summary (`$GITHUB_STEP_SUMMARY`) | `'true'` |\n| `dry-run` | Print debrief to stdout without posting comment | `'false'` |\n\n#### Action Outputs\n\n| Output | Description |\n| :--- | :--- |\n| `debrief` | The generated Feynman debrief markdown text |\n| `skipped` | Whether the debrief was skipped due to trivial/cosmetic diff (`true` or `false`) |\n| `comment-posted` | Whether the comment was successfully posted to the PR (`true` or `false`) |\n\n---\n\n## Quality Linter & Test Suite\n\nThis repository is built with **Test-Driven Development (TDD)** and includes an automated audit linter to verify that explanations adhere to Feynman principles:\n\n> **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.\n\n```bash\n# Run the test suite\npython3 -m unittest discover tests\n\n# Audit an explanation draft\npython3 scripts/audit_debrief.py my_explanation.md\n# Or via pipe:\ncat response.txt | python3 scripts/audit_debrief.py --stdin\n\n# Check if a git diff warrants a debrief (Complexity Gating)\npython3 scripts/audit_debrief.py --check-diff git_diff.patch\n# Or pass commit message to test conventional commit heuristics:\npython3 scripts/audit_debrief.py --check-diff --commit-msg \"docs: update guide\" git_diff.patch\n\n# Score an explanation with the Feynman Index (0-100 Scorecard)\npython3 scripts/eval_runner.py my_explanation.md\n\n# Run the automated benchmark leaderboard across all model transcript fixtures\npython3 scripts/eval_runner.py --benchmark\n```\n\n### The Feynman Index (0-100 Scorecard)\n\nThe Feynman Index evaluates technical explanations across 5 pedagogical pillars:\n\n1. **Mechanism Purity (25 pts):** Physical causality, concrete data flow, zero banned buzzwords.\n2. **Honest Limits & Metaphor (25 pts):** Clear everyday sensory analogy and explicit breaking point.\n3. **Audience Calibration (20 pts):** Proper target rung (`vibe-coder`, `junior-dev`, `senior-dev`, or `--full`).\n4. **Empirical Verifiability (15 pts):** Concrete, single-step browser or terminal test.\n5. **Brevity & Density (15 pts):** High signal-to-noise ratio within the 170 prose-word budget.\n\n---\n\n## Repository Structure\n\n```text\nsimplifeyn/\n|-- SKILL.md                  # Main Agent Skill specification\n|-- README.md                 # Documentation and guide\n|-- action.yml                # Reusable GitHub Action for PR reviews\n|-- install.sh                # Universal installer\n|-- LICENSE                   # MIT License\n|-- references/\n|   |-- voice.md              # Style forensics, banned buzzwords, sensory verbs\n|   |-- analogies.md          # Reference catalog of computing analogies & breaking points\n|   |-- ladder.md             # Audience calibration (Vibe Coder -> Junior -> Senior)\n|   \\-- failure-modes.md      # 5 critical ways technical explanations fail & fixes\n|-- assets/\n|   \\-- worked-examples.md    # Real PR diff with Before/After contrast\n|-- scripts/\n|   |-- audit_debrief.py      # Automated linter against lazy jargon\n|   |-- eval_runner.py        # Feynman Index evals & benchmark leaderboard harness\n|   |-- get-diff.sh           # Git diff extractor helper\n|   \\-- pr_reviewer.py        # GitHub Action PR Reviewer engine\n\\-- tests/                    # Automated TDD test suite\n```\n\n---\n\n## Security & Capability Transparency\n\n`simplifeyn` adheres strictly to the security expectations of the Agent Skills standard and Trust Hub audits:\n\n1. **Zero Remote Execution (No Unreviewed Shell Piping):**\n   - The repository does not provide, encourage, or execute unreviewed remote script piping from URLs into a shell.\n   - `install.sh` operates 100% locally on existing files within a cloned repository and performs zero remote downloads or network calls.\n2. **Read-Only Inspection:**\n   - `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.\n3. **Offline AST Analysis:**\n   - `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.\n4. **Indirect Prompt Injection Defense:**\n   - Ingested diff content is sandboxed within `<untrusted_diff>` and `</untrusted_diff>` boundary markers with nested tag escaping.\n   - The skill instructions explicitly direct agents to treat diff data strictly as passive code, ignoring any embedded instructions, prompt injection overrides, or tool invocation requests.\n\n---\n\n## Contributing\n\nContributions and feedback are welcome! Areas to explore:\n- New physical analogies and breaking points added to `references/analogies.md`.\n- Real-world worked examples in `assets/worked-examples.md`.\n- Additional edge case tests in `tests/`.\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n"}