{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/banner.svg\" alt=\"WHY — Combat cognitive debt from AI-assisted development\" width=\"100%\" />\n</p>\n\n<p align=\"center\">\n  <a href=\"https://ko-fi.com/joshobrien15789\"><img src=\"https://ko-fi.com/img/githubbutton_sm.svg\" alt=\"Support on Ko-fi\" /></a>\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/version-1.0.0-6366f1?style=flat-square\" alt=\"Version\" />\n  <img src=\"https://img.shields.io/badge/license-MIT-22d3ee?style=flat-square\" alt=\"License\" />\n  <img src=\"https://img.shields.io/badge/Claude_Code-plugin-8b5cf6?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDJMMiAyMmgyMEwxMiAyeiIgZmlsbD0id2hpdGUiLz48L3N2Zz4=\" alt=\"Claude Code\" />\n</p>\n\n---\n\n> *\"Any fool can know. The point is to understand.\"* — Albert Einstein\n\nWHY is a [Claude Code plugin](https://code.claude.com/docs/en/plugins) that questions/quizzes you on code you've accepted from Claude in Terminal. Instead of accepting instantly and moving on, you spend 60 seconds confirming you actually understand what was implemented. This may seem extreme to some, but there is a fundemental reason for it which I will get into below. \n\nEvery question that will be asked from this is rooted in *your specific code* not generic textbook material.\n\n## The Problem\n\nThe world is very quickly flying into an AI Enhanced world of programming and many of us know from experience that AI in itself is a brilliant and helpful tool at furthering the development of outputted code. Most tools/plugins and otherwise focus on the AI portion of this equation 'more-context'/'more-tools'/ 'more-mcps','more efficency'. However it is rare we focus on the other side of the coin. How often do most people using these tools in any walks of life/vibe coding or otherwise *understand fully* what has been created, or challenged themselves to understand  the code outputted by our AI companions. This is where we come to the human cost or: **cognitive debt**: this is just one of the gaps between what you ship/what you can debug, extend, or explain. It compounds silently for many unlucky souls until they are potentially staring at something that breaks, and at code they don't recognise.\n\n## The Research\n\nWhile it may have been coined elsewhere the term I use *cognitive debt* I have taken from a 2025 MIT Media Lab study that used EEG brain monitoring to measure what happens when people rely on LLMs - I will go further into this in a [Medium Article](https://medium.com/aiexploration/ai-assistance-or-the-battle-to-negate-our-human-cognitive-debt-747421fb593a). \nBelow are some of the key takeaways summarised:\n\n- **55% reduced neural connectivity** in LLM users compared to those working without AI assistance\n- **83% of LLM users couldn't quote from work they'd produced minutes earlier** their brains never took any of it in\n- **Ownership collapsed** — Some LLM users denied authorship entirely\n- **The debt compounds over time** — when LLM users later worked without tools, they showed weaker neural connectivity than people who had never used LLMs at all\n\nThe researchers concluded that \"repeated reliance on external systems like LLMs replaces the effortful cognitive processes required for independent thinking\" and recommended combining AI assistance with tool free learning phases.\n\nWHY is exactly that: a Claude Plugin/Human Positive learning phase embedded in your workflow. Sixty seconds of forced cognitive engagement after each implementation. While in no way do I see this as a cure all, it is a step in ensuring those of us still learning (all of us) continue to do so without taking a backseat to AI.\n\nWHY won't turn you into someone who writes everything from scratch, neither would I want it to. AI I believe is a fundemental turning point in Software Engineering and is here to stay. That's not the point. It's that like financial debt/ cognitive deat compounds. WHY is harm reduction: 60 seconds of forced recall after an implementation, enough to encourage you to make your brain actually encode what happened. It won't replace genuine understanding, but it'll make you take a pause before shipping code you potentially couldn't describe/claim ownership of.\n\n> Kosmyna, N., Hauptmann, E., et al. (2025). *Your Brain on ChatGPT: Accumulation of Cognitive Debt when Using an AI Assistant for Essay Writing Task.* MIT Media Lab. arXiv:2506.08872.\n>\n> **Paper:** [arxiv.org/abs/2506.08872](https://arxiv.org/abs/2506.08872) · **Project:** [brainonllm.com](https://www.brainonllm.com/) · **MIT Media Lab:** [media.mit.edu](https://www.media.mit.edu/publications/your-brain-on-chatgpt/)\n>\n\n## How WHY Works\n\nWHY generates contextual multiple-choice questions across three tiers:\n\n| Tier | Tests | Example |\n|------|-------|---------|\n| **WHAT** | Can you identify what was implemented? | \"Which hook prevents re-renders on line 14?\" |\n| **HOW** | Can you trace how it works? | \"What's the execution order when the form submits?\" |\n| **WHY** | Can you justify the approach? | \"Why use a Map instead of a plain object for the cache?\" |\n\n5 questions per quiz (2 × WHAT, 2 × HOW, 1 × WHY), with explanations after every answer.\n\n```mermaid\ngraph LR\n    A[\"🤖 Claude generates code\"] --> B{\"quiz me\"}\n    B --> C[\"📝 5 contextual questions\"]\n    C --> D[\"WHAT × 2\"]\n    C --> E[\"HOW × 2\"]\n    C --> F[\"WHY × 1\"]\n    D --> G[\"✓ ✗ + explanation\"]\n    E --> G\n    F --> G\n    G --> H[\"📊 Score breakdown\"]\n    H --> I{\"≤ 3/5?\"}\n    I -- Yes --> J[\"💡 Offer walkthrough\"]\n    I -- No --> K[\"✅ Ship with confidence\"]\n\n    style A fill:#1a1a2e,stroke:#6366f1,color:#fff\n    style B fill:#1a1a2e,stroke:#8b5cf6,color:#fff\n    style C fill:#1a1a2e,stroke:#6366f1,color:#fff\n    style D fill:#0e3a42,stroke:#22d3ee,color:#22d3ee\n    style E fill:#1e1538,stroke:#a78bfa,color:#a78bfa\n    style F fill:#2d1528,stroke:#f472b6,color:#f472b6\n    style G fill:#1a1a2e,stroke:#6366f1,color:#fff\n    style H fill:#1a1a2e,stroke:#6366f1,color:#fff\n    style I fill:#1a1a2e,stroke:#eab308,color:#eab308\n    style J fill:#1a1a2e,stroke:#f472b6,color:#f472b6\n    style K fill:#1a1a2e,stroke:#22c55e,color:#22c55e\n```\n\n## Installation\n\n### Claude Code\n\n```bash\n/plugin marketplace add jobrien874/why-plugin\n/plugin install why@why-plugin\n```\n\n### Manual Installation\n\nClone this repo and point Claude Code at it:\n\n```bash\ngit clone https://github.com/jobrien874/why-plugin.git\n# Then in Claude Code:\n/plugin install --path /path/to/why-plugin\n```\n\n## Usage\n\n### Manual Quiz\n\nAfter receiving code from Claude, say:\n\n```\nquiz me\n```\n\nor\n\n```\n/why\n```\n\n### Auto-Quiz Mode\n\nEnable automatic quiz prompts after substantial code blocks:\n\n```\nenable why\n```\n\nClaude will offer a quiz after generating 50+ lines. Disable with `disable why`.\n\n### Targeted Quiz\n\nPoint at specific code:\n\n```\nquiz me on the auth middleware\ntest me on lines 40-80\n```\n\n### Session Review\n\nQuiz across everything from the current conversation:\n\n```\nquiz me on everything from this session\n```\n\n## Example Session\n\n```\nYou: Build me a debounced search component in React\n\nClaude: [generates component]\n\nYou: quiz me\n\nClaude:\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n  WHY Quiz — Debounced Search Component\n  Question 1 of 5  [WHAT]\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nWhat does the cleanup function returned by the useEffect\non line 22 do?\n\n  a) Cancels the pending API request\n  b) Clears the debounce timeout\n  c) Resets the search input value\n  d) Removes the event listener\n\nReply with a, b, c, or d.\n\nYou: b\n\nClaude:\n✓ Correct!\n\nThe cleanup function calls clearTimeout on the timeout ref,\npreventing the debounced callback from firing if the component\nunmounts or the dependency changes before the delay expires.\nOption (a) is wrong because there's no AbortController in this\nimplementation — that would be a good enhancement.\n```\n\n## Scoring\n\nAfter all questions, you get a tier breakdown:\n\n```\n  Score: 4/5 (80%)\n\n  WHAT  ██████████ 2/2\n  HOW   █████░░░░░ 1/2\n  WHY   ██████████ 1/1\n\n  💡 Your HOW score suggests you might want to trace\n     through the data flow once more.\n```\n\n## How Triggering Works\n\nWHY is a SKILL.md agent skill. \n\n| You say | What happens |\n|---------|-------------|\n| `quiz me` / `/why` / `test my understanding` | Quiz on the most recent substantial code block |\n| `quiz me on the auth middleware` | Quiz scoped to the referenced section only |\n| `quiz me on everything this session` | Review quiz spanning all code from the conversation (8 questions) |\n| `enable why` / `auto-quiz on` | Turns on auto-quiz mode (see below) |\n| `disable why` / `auto-quiz off` | Turns off auto-quiz mode |\n\n**Auto-quiz mode** is opt-in. Once enabled, after generating 50+ lines of code, the agent appends a soft prompt: *\"Ready to check understanding? Say 'go' for a quick WHY quiz, or keep moving.\"* You can ignore it entirely — no quiz is forced into the response. This mode persists for the session and resets when the conversation ends.\n\nIf you're clearly in a rush (\"just give me the code\", \"skip the explanation\"), WHY stays out of the way even in auto-quiz mode.\n\n## Token Cost\n\nAs I know this topic will come up :) the only overhead is the extra tokens, which will be from the model you are currently using roughly 200–300 tokens per question/answer cycle, or ~1,500 tokens for a full 5-question quiz. In order to combat cognitive debt I think it's well worth the time/tokens spent.\n\n**Tip:** Quiz generation doesn't need frontier-level intelligence. If you're running on Opus and want to save tokens, switch to Haiku or Sonnet before triggering the quiz:\n\n```\n/model\n# select haiku or sonnet\nquiz me\n# switch back after\n/model\n```\n\n## Roadmap\n\n- [x] **v1.0** — Multiple choice, 3-tier questions, session scoring\n- [ ] **v2.0** — \"Explain It Back\" free-text mode with LLM-as-judge scoring\n- [ ] **v2.1** — Difficulty scaling based on historical performance\n- [ ] **v3.0** — Interactive dashboard for claude.ai with persistent score tracking\n\n## Philosophy\n\nI have tried to enforce key points in the Skill, noted below, this is to prevent your performance effecting potential output of Claude.\n\n- **Not a gatekeeper.** WHY never withholds code or blocks your workflow.\n- **Not a test.** There's no pass/fail. A 2/5 is useful signal, not judgment.\n- **Not generic.** Every question is grounded in your actual implementation.\n\nThe tone is that of a senior colleague or peer who wants you to succeed.\n\n## Compatibility\n\nWHY uses the universal [SKILL.md agent skill format](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and works with:\n\n## Contributing\n\nIssues and PRs welcome. If you've got ideas for question patterns, difficulty scaling or really anything please start a discussion :) \n\n## Disclaimer\n\nWHY like AI itself is not a replacement for common sense. A passing score doesn't mean your code is production ready, or even should be used at all. Likewise a failing score doesn't mean it isn't. Use your judgment. WHY is a learning aid, not a safety net.\n\n## License\n\n[MIT](LICENSE)\n\n## Support\n\nIf WHY helps you in anyway or you like the idea, consider supporting development/buying me a coffee & or Guiness (€6.08 average price in Ireland [11/04/2026](https://guinndex.ai/)):\n\n<a href=\"https://ko-fi.com/joshobrien15789\">\n  <img src=\"https://ko-fi.com/img/githubbutton_sm.svg\" alt=\"Support on Ko-fi\" />\n</a>\n\n---\n\nBuilt by [Josh O'Brien](https://github.com/jobrien874)\n",
  "bytes": 11488,
  "sha": "a9c2f42cac36805ff33a8883a4aeb99b3a69527f88b731bfa7a5efd01da52f54",
  "repo_slug": "jobrien874/why-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_jobrien874_why_plugin_why_c8b7b526/readme"
}