Reality Check Plugin

A Claude Code plugin that provides critical, skeptical feedback to counter AI over-agreement. Challenges assumptions, surfaces risks, and makes you think critically about AI-generated responses.

Why This Plugin?

AI assistants tend to be agreeable. They'll often validate ideas without sufficient pushback. This plugin provides:

• Skeptical analysis that questions assumptions
• Risk identification before problems become expensive
• Devil's advocate perspectives on proposals
• Evidence-based thinking that demands proof

Installation

Via NPM (Recommended)

npx @internal/reality-check

Via Git Clone

git clone <repository-url>
cd reality-check
npm link

Manual Installation

Copy the plugin directory to your Claude Code plugins location:

cp -r reality-check ~/.claude/plugins/

Available Commands

/reality-check [subject]

Full critical analysis including:

• Assumption identification
• Risk assessment
• Devil's advocate arguments
• Evidence gaps
• Failure scenarios
• Clear verdict

/reality-check
/reality-check "our new caching strategy"

/challenge [statement]

Quick push-back on specific claims:

/challenge
/challenge "this will be easy to implement"

/risks [scope]

Focused risk analysis:

/risks
/risks "database migration"

Skills

The plugin provides three auto-invocable skills:

| Skill | Purpose | |-------|---------| | reality-check | Comprehensive critical analysis | | risk-analysis | Systematic risk identification | | assumption-audit | Surface and validate assumptions |

Skills can be invoked automatically by Claude when relevant, or manually via commands.

Agents

Three specialized agents provide different perspectives:

Skeptic Agent

Primary devil's advocate. Questions everything, demands evidence.

Risk Assessor Agent

Focuses on what could go wrong. Categorizes and quantifies risks.

Assumption Challenger Agent

Identifies hidden assumptions. Maps dependencies and prerequisites.

Hooks

The plugin configures automatic hooks:

| Event | Behavior | |-------|----------| | SessionStart | Reminds that critical thinking mode is active | | UserPromptSubmit | Detects overconfidence markers and assumptions | | Stop | Offers final critical review opportunity |

Trigger Words

The UserPromptSubmit hook watches for:

• Overconfidence: "obviously", "clearly", "simply", "just", "easy"
• Deployment: "deploy", "release", "ship", "launch"
• Assumptions: "assume", "should work", "probably"

Configuration

Disabling Hooks

Edit hooks/hooks.json and set:

{
  "config": {
    "enabled": false
  }
}

Adjusting Verbosity

{
  "config": {
    "verbosity": "quiet"  // Options: quiet, normal, verbose
  }
}

Example Usage

Architecture Review

User: We should use MongoDB for the new user preferences feature.

Claude: Let me run a reality check on this proposal...

/reality-check "Using MongoDB for user preferences"

## Reality Check: MongoDB for User Preferences

### Assumptions Identified
1. Schema flexibility is needed (Confidence: Unknown)
2. Query patterns suit document model (Confidence: Unverified)
3. Team has MongoDB operational experience (Confidence: Questionable)

### Risks
| Risk | Likelihood | Impact |
|------|------------|--------|
| Data consistency issues | Medium | High |
| Operational overhead | High | Medium |
| Query pattern mismatch | Medium | High |

### Devil's Advocate
"Have you considered that PostgreSQL JSONB provides similar schema flexibility with stronger consistency guarantees and likely existing operational expertise?"

### Verdict: NEEDS WORK
Validate assumptions about schema flexibility requirements and team expertise before proceeding.

Quick Challenge

User: This change is low risk since it's just a config update.

Claude: /challenge "just a config update"

## Challenge: "just a config update"

**Questions:**
- What systems depend on this config?
- Has this exact change been tested in staging?
- What's the rollback procedure?
- How will we know if it broke something?

**Alternative view:** Config changes have caused major outages at many companies. They're often undertested and hard to debug.

**Bottom line:** Config changes deserve the same rigor as code changes.

Philosophy

This plugin embodies these principles:

1. Never agree easily - Find something to challenge
2. Demand evidence - "What data supports this?"
3. Surface assumptions - Make implicit explicit
4. Highlight risks - "What happens if this fails?"
5. Be specific - Generic criticism is useless
6. Respect people - Challenge ideas, not individuals

Contributing

Contributions welcome. Please ensure any additions:

• Provide specific, actionable feedback
• Challenge ideas constructively
• Include examples
• Follow the existing tone

License

MIT