diff --git a/plugins/README.md b/plugins/README.md index cf4a21ecc5..171ac317ff 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -23,6 +23,7 @@ Learn more in the [official plugins documentation](https://docs.claude.com/en/do | [learning-output-style](./learning-output-style/) | Interactive learning mode that requests meaningful code contributions at decision points (mimics the unshipped Learning output style) | **Hook:** SessionStart - Encourages users to write meaningful code (5-10 lines) at decision points while receiving educational insights | | [plugin-dev](./plugin-dev/) | Comprehensive toolkit for developing Claude Code plugins with 7 expert skills and AI-assisted creation | **Command:** `/plugin-dev:create-plugin` - 8-phase guided workflow for building plugins
**Agents:** `agent-creator`, `plugin-validator`, `skill-reviewer`
**Skills:** Hook development, MCP integration, plugin structure, settings, commands, agents, and skill development | | [pr-review-toolkit](./pr-review-toolkit/) | Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification | **Command:** `/pr-review-toolkit:review-pr` - Run with optional review aspects (comments, tests, errors, types, code, simplify, all)
**Agents:** `comment-analyzer`, `pr-test-analyzer`, `silent-failure-hunter`, `type-design-analyzer`, `code-reviewer`, `code-simplifier` | +| [reframe](./reframe/) | Break through stuck debugging and design problems by reframing them through first principles, inversion, and analogy | **Command:** `/reframe` - Gather codebase context and reframe engineering problems through cognitive frameworks | | [ralph-wiggum](./ralph-wiggum/) | Interactive self-referential AI loops for iterative development. Claude works on the same task repeatedly until completion | **Commands:** `/ralph-loop`, `/cancel-ralph` - Start/stop autonomous iteration loops
**Hook:** Stop - Intercepts exit attempts to continue iteration | | [security-guidance](./security-guidance/) | Security reminder hook that warns about potential security issues when editing files | **Hook:** PreToolUse - Monitors 9 security patterns including command injection, XSS, eval usage, dangerous HTML, pickle deserialization, and os.system calls | diff --git a/plugins/reframe/.claude-plugin/plugin.json b/plugins/reframe/.claude-plugin/plugin.json new file mode 100644 index 0000000000..b4780a5397 --- /dev/null +++ b/plugins/reframe/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "reframe", + "description": "Break through stuck debugging and design problems by reframing them through first principles, inversion, and analogy", + "version": "1.0.0", + "author": { + "name": "Anuj Gupta", + "email": "anuj.1306.gupta@gmail.com" + } +} diff --git a/plugins/reframe/README.md b/plugins/reframe/README.md new file mode 100644 index 0000000000..70747d7e03 --- /dev/null +++ b/plugins/reframe/README.md @@ -0,0 +1,77 @@ +# Reframe Plugin + +Break through stuck debugging and design problems by reframing them through cognitive thinking frameworks. + +## Overview + +Developers get stuck not because they lack skill, but because they're locked into one way of seeing the problem. `/reframe` applies structured thinking frameworks to your actual codebase context — reading your git diff, locating error sources, and examining the code you're working on — to help you see the problem from a different angle. + +It auto-selects the 1-2 most relevant frameworks from: + +- **First Principles** — decompose to fundamental requirements, strip away inherited architecture assumptions +- **Inversion** — ask what would guarantee this code fails, then check if those conditions exist +- **Analogy** — map to a well-known engineering pattern (is this really a caching problem? a state machine?) + +## Commands + +### `/reframe` + +Gathers codebase context and reframes your engineering problem through the most relevant cognitive lens(es). + +**Usage:** + +``` +/reframe This API keeps timing out under load and I've already tried adding caching +``` + +``` +/reframe I can't figure out why this test is flaky — it passes locally but fails in CI +``` + +``` +/reframe This auth flow has gotten too complex and I don't know where to simplify +``` + +You can also select code in your editor and run `/reframe` to get a perspective shift on a specific block. + +**What it does:** + +1. **Gathers context** — reads your git diff, recent commits, and branch to understand what you've been working on +2. **Investigates** — if you mention a bug or error, uses Read, Grep, and Glob to locate relevant code and error messages in the codebase +3. **Reads code** — if you selected code or referenced files, reads the full source for the bigger picture +4. **Reframes** — applies 1-2 thinking frameworks directly to your code, referencing actual file names, functions, and patterns +5. **Next step** — suggests one concrete action, naming the specific file, function, or command to act on + +**Example output:** + +> **Inversion** — You're trying to make this faster, but haven't defined what's actually slow. +> +> Ask instead: what would guarantee `getDashboardData()` is slow? Answer: unbounded joins, no index on the filter column, synchronous calls to three external services. `src/api/dashboard.ts:47` does all three — it joins 4 tables on `events.created_at` which has no index. +> +> **Insight:** You've been optimizing the application layer, but the bottleneck is the query plan. +> +> **Next Step:** Run `EXPLAIN ANALYZE` on the query at `src/api/dashboard.ts:47` — check if `events` is doing a sequential scan. + +## Installation + +Install via the plugin marketplace: + +``` +/plugin install reframe@claude-plugins-official +``` + +Or add to your project's `.claude/settings.json`: + +```json +{ + "enabledPlugins": ["reframe@claude-plugins-official"] +} +``` + +## Author + +Anuj Gupta (anuj.1306.gupta@gmail.com) + +## Version + +1.0.0 diff --git a/plugins/reframe/commands/reframe.md b/plugins/reframe/commands/reframe.md new file mode 100644 index 0000000000..e59746695b --- /dev/null +++ b/plugins/reframe/commands/reframe.md @@ -0,0 +1,64 @@ +--- +description: Break through a stuck debugging or design problem by reframing it +argument-hint: [problem description or leave blank with code selected] +allowed-tools: Bash(git diff:*), Bash(git log:*), Bash(git status:*), Read, Grep, Glob +--- + +You are a developer problem-solving assistant. The user is stuck — on a bug, a design decision, a failing test, or a piece of code they can't untangle. Your job is to help them see the problem differently so they can move forward. + +## Context gathering + +Before reframing, silently gather relevant context to ground your analysis in the actual codebase. Do not narrate these steps to the user. + +**1. Working state** — understand what the user has been working on: +- Recent changes: !`git diff --stat HEAD 2>/dev/null || echo "not a git repo"` +- Recent commits: !`git log --oneline -5 2>/dev/null || echo "no git history"` +- Current branch: !`git branch --show-current 2>/dev/null || echo "unknown"` + +**2. Error and failure context** — if the user mentions a bug, test failure, or error, use Read, Grep, and Glob to locate the relevant code, error messages, or test files. Look at the actual code — do not guess. + +**3. Code context** — if the user selected code in their editor or referenced specific files, read those files to understand the full picture before reframing. + +Use this gathered context to make your reframing specific and grounded. Reference actual file names, function names, error messages, and code patterns. + +## Your task + +Analyze the developer's problem — combined with the codebase context you gathered — and reframe it using the most relevant framework(s). Pick only the 1-2 frameworks that provide the most useful shift in perspective for this specific engineering problem. Do not use all three unless they are all genuinely insightful. + +## Available frameworks + +### First Principles +Decompose the problem to its fundamental requirements and constraints. Strip away inherited architecture decisions, framework conventions, and "it's always been done this way." +- What does this code actually need to do vs. what it currently does? +- Which constraints are real (specs, performance budgets, API contracts) vs. assumed? +- If you rewrote this module from scratch today, what would be different? + +### Inversion +Instead of solving the problem directly, ask: what would guarantee this code fails? Then check if any of those conditions exist. +- What inputs, states, or race conditions would break this? +- What are you currently not testing or handling? +- What is the opposite of the approach you've been trying? + +### Analogy +Map the problem to a well-known engineering pattern. Find structural similarities that reveal solutions. +- Is this a caching problem disguised as a performance problem? +- Is this a state machine that's being treated as a linear flow? +- What solved this class of problem in a different system or domain? + +## Output format + +For each selected framework: + +1. **Name the framework** and explain in one sentence why it fits this specific engineering problem +2. **Reframe the problem** through that lens in 3-5 sentences, referencing specific code, files, or patterns from the gathered context +3. **Surface a concrete insight** — one specific thing the developer likely has not considered about their code or approach + +End with a **Next Step** — one clear, actionable thing to do right now. Name the specific file, function, test, or command to act on. + +## Important + +- Be specific to the codebase. Reference actual files, functions, variable names, and error messages. +- Do not give generic software advice. Every sentence should be grounded in the gathered context. +- Keep it concise. The value is in the perspective shift, not the word count. +- Do not explain the frameworks abstractly — apply them directly to the code. +- If context gathering reveals the root cause is obvious, say so plainly instead of forcing a framework.