Second Opinion

A Claude Code plugin that stress-tests your AI-generated plans before you start building. Five dynamically chosen expert reviewers -- each with deep domain knowledge -- tear apart your plan, grade every finding by severity, and verify the fixes. All from a single command.

No configuration. No external dependencies. No API keys.

Version: 2.1.0 | License: MIT

---

Table of Contents

• Why Second Opinion?
• Installation
• How to Use It
• What You Get
• Under the Hood
• Architecture
• Troubleshooting
• Contributing
• License

---

Why Second Opinion?

When Claude reviews its own plan, it tends to miss the same things it missed the first time. Asking it to "review this" produces shallow, generic feedback -- "consider error handling", "think about edge cases."

Second Opinion fixes this by forcing Claude into 5 distinct expert perspectives, each constructed with its own mindset, non-negotiable rules, and pointed questions about YOUR specific plan. The result is feedback that names exact parts of your plan and explains exactly how they'll break.

What makes it work:

• Dynamic expertise -- every plan gets a unique review panel. A REST API gets Security Engineer + API Designer. A game gets UX Expert + Performance Engineer. A legal document gets Compliance Counsel + Opposing Counsel. No fixed roster, no generic reviewers.

• Deep personas -- each reviewer isn't just a label. Claude internally builds a mindset (how the expert thinks), 3 prime directives (rules they'd reject a plan over), and 5 evaluation questions specific to your plan. This is what produces "the WebSocket authenticates once on connect -- what prevents hijacking if the JWT expires while the socket is open?" instead of "consider authentication."

• Adversarial pressure -- 2 of the 5 reviewers are adversarial. They assume your plan is broken and construct step-by-step scenarios proving how it fails -- from trigger to consequence.

• Severity grading -- every finding is ‼ (plan will fail as written, must fix) or • (real issue, your call). Two tiers, no debates, with tallies after each round.

• Two-pass verification -- Claude revises the plan prioritizing critical findings, then the same 5 reviewers verify the revision. A before/after delta shows what improved.

---

Installation

One-line install

git clone https://github.com/charleschenai/second-opinion.git \
  ~/.claude/plugins/marketplaces/second-opinion \
  && bash ~/.claude/plugins/marketplaces/second-opinion/install.sh

The installer clones the repo, verifies the file structure, and adds the required entries to ~/.claude/settings.json. If settings.json already exists, it merges non-destructively (requires python3).

Manual install

1. Clone into Claude Code's plugin directory:

git clone https://github.com/charleschenai/second-opinion.git \
  ~/.claude/plugins/marketplaces/second-opinion

2. Add to ~/.claude/settings.json:

{
  "enabledPlugins": {
    "second-opinion@second-opinion": true
  },
  "extraKnownMarketplaces": {
    "second-opinion": {
      "source": {
        "source": "directory",
        "path": "/home/YOUR_USER/.claude/plugins/marketplaces/second-opinion"
      }
    }
  }
}

Replace /home/YOUR_USER with your actual home directory path.

3. Restart Claude Code. Skills are cached at session start.

Updating

cd ~/.claude/plugins/marketplaces/second-opinion && git pull

Then restart Claude Code.

Common mistakes

Problem	Fix
Wrong clone location	Must be ~/.claude/plugins/marketplaces/second-opinion
/so doesn't appear	Add "second-opinion@second-opinion": true under enabledPlugins
Plugin not detected	Add extraKnownMarketplaces entry pointing to the plugin directory
Stale behavior after update	Restart Claude Code to reload SKILL.md

---

How to Use It

When to run /so

/so works inside Claude Code's plan mode. The typical workflow:

1. You ask Claude to plan something -- "plan a REST API for user management", "design a caching layer for the search service", "plan the database migration"
2. Claude drafts a plan -- architecture decisions, data flow, implementation steps
3. You iterate -- ask questions, request changes, refine the scope, push back on decisions
4. You run /so -- when the plan looks solid and you're thinking about approving it, type /so to stress-test it before building
5. Review the results -- Claude presents 5 expert reviews with severity-graded findings, revises the plan addressing critical issues, then the same experts verify the revision

That's it. /so is the quality gate between "plan looks good to me" and "start writing code." One command, fully automatic.

What happens when you type /so

1. Claude reads and summarizes the active plan
2. Picks 5 domain-specific expert reviewers (3 constructive + 2 adversarial)
3. Each reviewer critiques the plan with severity-graded findings
4. All reviews are presented with a tally of criticals and issues
5. Claude revises the plan, addressing critical (‼) findings first
6. The same 5 reviewers verify the revision, with a before/after delta

No third pass. If new issues surface in the re-review, they're left for you to decide on.

---

What You Get

Here's a full sample of what /so produces on a REST API plan (abbreviated -- real reviews are longer):

───────────────────────────────────────
 SECOND OPINION — 5 Claude personas

 API Designer        contracts
 Database Reviewer   queries
 Security Engineer   auth
 ⚠ Saboteur         breaks it
 ⚠ Red Team         exploits
───────────────────────────────────────

╭──────────────────────────────────────────╮
│  API Designer -- contracts               │
╰──────────────────────────────────────────╯

‼ POST /users returns the full user object including
  password hash -- response schema needs explicit field
  filtering

• PATCH /users/{id} accepts partial updates but the plan
  doesn't specify merge semantics -- does null mean "delete
  field" or "no change"?

• No versioning strategy -- breaking changes will strand
  existing clients with no migration path

╭──────────────────────────────────────────╮
│  Database Reviewer -- queries            │
╰──────────────────────────────────────────╯

‼ N+1 query in the user list endpoint -- fetching roles
  per user in a loop will choke at 10K users

‼ No index on created_at despite ORDER BY in 3 queries
  -- full table scan on every list request

• The soft-delete plan uses a deleted_at column but no
  queries filter on it -- every SELECT returns deleted
  records

╭──────────────────────────────────────────╮
│  Security Engineer -- auth               │
╰──────────────────────────────────────────╯

‼ No rate limiting on login endpoint -- brute force is
  trivial at ~1000 attempts/sec

‼ JWT secret rotation not addressed -- a compromised key
  gives permanent access until manual intervention

• Session tokens stored in localStorage -- any XSS
  vulnerability exfiltrates every active session

╭──────────────────────────────────────────╮
│  ⚠ Saboteur -- breaks it                │
╰──────────────────────────────────────────╯

‼ The /api/upload endpoint has no size limit

Scenario: OOM via payload bombing
1. Attacker sends a 50MB JSON payload to /api/upload
2. Server attempts to parse entire body into memory
3. Node.js process exceeds heap limit and crashes
→ Impact: Service down for all users until pod restarts

• The plan says "pagination" but specifies no max page
  size -- requesting page_size=1000000 dumps the entire
  database into one response

╭──────────────────────────────────────────╮
│  ⚠ Red Team -- exploits                 │
╰──────────────────────────────────────────╯

‼ The file upload accepts user-provided filenames with no
  sanitization -- directory traversal via ../../etc/passwd

Scenario: Account takeover via password reset
1. Attacker hits POST /auth/reset with victim's email
2. No rate limit -- enumerate valid emails by timing
   difference (200ms for valid, 50ms for invalid)
3. Reset token is 6 digits, no expiry mentioned in plan
4. Brute force 000000-999999 in ~15 minutes
→ Impact: Full account takeover of any user

• Admin endpoints use the same JWT -- no privilege
  separation between user and admin tokens

─── 7 critical (‼) · 5 issues (•) ───

After Claude revises the plan and the re-review runs, you see the delta:

─── Round 1: 7‼ 5• → Round 2: 1‼ 3• ───

Review depth scales to plan complexity -- a 5-line CSS fix gets lighter reviews, a distributed systems redesign gets full failure scenario tracing.

---

Under the Hood

Dynamic Reviewer Selection

Every plan gets a unique panel. Claude analyzes the plan's domain, technologies, and risk areas, then invents 5 experts that maximize coverage with minimal overlap. 3 are constructive (find real issues, suggest improvements) and 2 are adversarial (assume it's broken, prove it).

Example panels:

Plan	Possible Reviewers
REST API	API Designer, Database Reviewer, Security Engineer, Saboteur, Red Team
Game	Game Designer, UX Expert, Performance Engineer, Chaos Agent, Rage Quitter
Deployment pipeline	SRE, Security Engineer, Architect, Reliability Engineer, Chaos Engineer
Legal document	Compliance Lawyer, Plain-Language Editor, Privacy Specialist, Accessibility Expert, Opposing Counsel

Deep Persona Construction

For each reviewer, Claude internally generates (not shown to the user):

• Mindset -- how the expert thinks, what they obsess over, what they notice first
• 3 Prime Directives -- non-negotiable rules they'd reject a plan over
• 5 Evaluation Questions -- specific to THIS plan, concretely phrased

This internal preparation is what drives the depth of the reviews. A reviewer with "every trust boundary must have explicit validation" as a prime directive will find the missing auth check that a generic reviewer glosses over.

Severity System

Every finding is graded:

Marker	Meaning
‼	Critical -- plan will fail as written. Must fix.
•	Issue -- real problem, fix at your discretion.

Two tiers only. When Claude revises the plan, it addresses ‼ findings first and calls out which ones it's fixing.

Adversarial Scenarios

Adversarial reviewers don't just say "this could fail." They construct structured scenarios showing exactly how it fails:

Scenario: Account takeover via password reset
1. Attacker hits POST /auth/reset with victim's email
2. No rate limit -- enumerate valid emails by response timing
3. Reset token is 6 digits, no expiry in plan
4. Brute force 000000-999999 in ~15 minutes
→ Impact: Full account takeover of any user

Trigger → propagation → consequence. Every time.

---

Architecture

The entire plugin is a single SKILL.md file -- a prompt that tells Claude how to conduct the review. No servers, no Python, no external dependencies.

second-opinion/
├── README.md
├── LICENSE
├── install.sh                         # Installer script
├── .claude-plugin/
│   └── marketplace.json               # Marketplace metadata
└── plugin/
    ├── .claude-plugin/
    │   └── plugin.json                # Plugin version
    └── skills/
        └── so/
            └── SKILL.md               # The entire plugin

---

Troubleshooting

Symptom	Cause	Fix
/so says "nothing to review"	No active plan	Start planning with Claude first, then run /so
/so not appearing as a command	Plugin not enabled	Check enabledPlugins in ~/.claude/settings.json
Plugin not detected at all	Missing marketplace entry	Check extraKnownMarketplaces in ~/.claude/settings.json
Stale behavior after update	Skills cached at session start	Restart Claude Code
Reviews feel shallow	Plan is too short	Add more detail to the plan before running /so

---

Contributing

1. Fork the repository
2. Edit plugin/skills/so/SKILL.md -- that's the whole plugin
3. Submit a pull request

The plugin is intentionally a single file. Keep it that way.

---

License

MIT -- see LICENSE.