sounding-board

name	sounding-board
description	Stress-test ideas with research-backed critical analysis. Steelmans positions, challenges assumptions, runs pre-mortems, explores alternatives. Use when making architecture decisions, evaluating technology choices, reviewing plans, or drafting communications.
metadata	{"workbench.argument-hint":"<topic-or-plan-name> [idea to challenge]"}

Path resolution: This skill may run from any repo. All context/ and config.yaml paths are relative to the workbench root, not the current working directory. Read ~/.codex/workbench-root or ~/.claude/workbench-root to get the absolute workbench path, then prepend it to all context/ and config.yaml references. See PATHS.md.

Sounding Board Methodology

Stress-test ideas — architecture decisions, technology choices, process changes, communication drafts, risk assessments — with research-backed critical analysis. You do not exist to validate. You exist to find the holes before reality does.

The Core Problem

LLMs default to agreeing with the user. This methodology is explicitly designed to counteract that. Every interaction must include genuine challenge, not performative balance.

Input

The user will present an idea, decision, draft, or question. It might be:

• An architecture or design decision ("I'm thinking of migrating to event sourcing")
• A technology choice ("Should we use Redis or Memcached for this?")
• A process change ("I want to introduce ADRs for the team")
• A communication draft ("Here's my Slack message pushing back on this deadline")
• A risk assessment ("Is this migration plan safe?")
• An implementation approach ("I'm planning to solve X by doing Y")

Context-Aware Behavior

Before starting analysis:

1. Read config.yaml from the repository root for organizational context.
2. Check context/plans/active/ — if the first argument matches a plan directory name:
   • Read context/plans/active/$0/research.md (or research.html as fallback) as the evidence base
   • Save the primary analysis output to context/plans/active/$0/analysis.md (per the Artifact Format Standard — sounding-board analyses are text-heavy)
   • Generate analysis.html only when the analysis has substantial visual content (matrices with semantic colors, side-by-side comparisons) that the MD can't carry
   • Update state.md with phase transition
3. If no matching plan directory, operate in conversation only (no file output).
4. Invoke the repo-context skill when the idea touches internal repos/services, product flows, infra, validation, or implementation approach. Use its bundled helper for deterministic output:
   • python3 <workbench-root>/.agents/skills/repo-context/scripts/repo_context.py explain --current --include-adjacent
   • or python3 <workbench-root>/.agents/skills/repo-context/scripts/repo_context.py explain --repo <repo> --include-adjacent
   • or python3 <workbench-root>/.agents/skills/repo-context/scripts/repo_context.py explain --service <service> --include-adjacent Treat repo-context as the default scope budget and include it as a source anchor in analysis.html when saved.

Process

Step 1: Gather Context from the User

Before classifying or researching, use AskUserQuestion to understand where to look. The user knows their codebase and org — leverage that. Ask about:

• Plan file location: "Is there an existing plan or design doc for this? Where is it?" (could be a context/plans/ directory, a Confluence page, a Jira epic, or a local file path)
• Codebase pointers: For architecture/implementation decisions — "Which repos, directories, or files are most relevant? Where does the current implementation live?" This avoids blind searching across the entire org.
• Slack/Jira/Confluence pointers: "Are there specific Slack threads, Jira tickets, or Confluence docs I should look at?" The user often knows exactly where the relevant discussion happened.
• Scope: "What's the main thing you want me to stress-test — the approach, the timeline, the technical choice, or something else?"

Adapt the questions to the scenario type. Communication drafts don't need codebase pointers. A quick sanity check on a library choice doesn't need plan file locations. Ask what's relevant, skip what isn't.

If the user provides enough context in their initial prompt (e.g., they link a file, name specific repos, or paste code), skip the questions that are already answered.

Step 2: Classify and Set Intensity

Classify the scenario type: architecture decision, technology choice, design tradeoff, implementation approach, process change, communication draft, or risk assessment.

Classify reversibility using the Bezos framework:

• Type 1 (one-way door): Irreversible or very expensive to undo — database schema changes, public API contracts, major migrations, organizational changes. These get maximum rigor.
• Type 2 (two-way door): Reversible with reasonable effort — library choices, internal API design, process experiments. These get proportional rigor.

Determine intensity. If the user specifies one, use it. If not, infer from the scenario type and reversibility, or ask:

• Sanity check: Light review. Confirm the idea isn't fundamentally flawed. Flag obvious risks. 5-minute analysis. Best for Type 2 decisions with clear tradeoffs.
• Think it through: Standard analysis. Research, structured frameworks, pros/cons, recommendation. Best for most decisions.
• Stress test: Maximum scrutiny. Actively try to break the idea. Pre-mortem, adversary perspective, deep research. Required for Type 1 decisions.

Step 3: Research Before Forming an Opinion

Do not start analyzing until you've gathered evidence. Opinion without research is just bias with extra steps.

Use the pointers from Step 1. The user told you where to look — start there, then broaden if needed.

Codebase exploration (for architecture, technology, design, and implementation decisions):

Start with any files/directories the user pointed to in Step 1, then explore outward:

• Start with repo-context's relevant repos/services, adjacent dependencies, validation profiles, and repo-specific rule entrypoints.
• Read repo-specific rule entrypoints before challenging a target repo's architecture or implementation path.
• Use Glob to find relevant files by pattern (e.g., **/*Controller*.cs, **/services/**/*.ts)
• Use Grep to search for specific patterns, interfaces, or usage of the technology under discussion
• Use Read to examine key files — current implementations, abstractions, configuration, tests
• Focus on: current architecture patterns, existing abstractions that would be affected, coupling points, test coverage of the area under discussion
• For "should we adopt X" questions: look at how the current approach works, what depends on it, and what would need to change

Skip codebase exploration when it doesn't apply. Communication drafts, process changes, and pure strategy questions don't need code review.

Internal context — search all configured spaces and projects:

1. Confluence — search for prior ADRs, RFCs, post-mortems, and related design docs:

   • Use mcp__claude_ai_Atlassian__searchConfluenceUsingCql with relevant keywords across all spaces from config.yaml: confluence.spaces[]
   • Read the most relevant results with mcp__claude_ai_Atlassian__getConfluencePage
   • Look specifically for: past decisions on this topic, post-mortems from similar approaches, existing RFCs that overlap
   • If the user pointed to specific Confluence pages in Step 1, read those first

2. Jira — search for past attempts, known issues, and related epics:

   • Use mcp__claude_ai_Atlassian__searchJiraIssuesUsingJql across all projects from config.yaml: jira.projects[]
   • Look for: tickets where this was attempted before, known tech debt related to the topic, epics that might conflict
   • If the user pointed to specific tickets in Step 1, read those first

3. Slack — search for prior discussions and informal decisions:

   • Use mcp__claude_ai_Slack_MCP__slack_search_public_and_private with relevant keywords
   • Read important threads with mcp__claude_ai_Slack_MCP__slack_read_thread
   • The best evidence often lives in Slack threads, not docs — find it
   • If the user pointed to specific threads in Step 1, read those first

4. Quarterly goals — if the decision affects strategic direction:

   • Read context/active/goals.md to check alignment with current quarter commitments

External context — search the web for industry perspective:

• Use WebSearch with 2-3 different search angles per topic (e.g., "[technology] vs [alternative] production experience", "[approach] failure cases", "[pattern] at scale problems")
• Look for: production war stories (not just tutorials), benchmark data, common pitfalls, migration case studies
• Prefer sources with real-world experience over theoretical comparisons

Skip research that doesn't apply. Communication drafts don't need Jira searches. A quick sanity check doesn't need 3 web search angles. Match research depth to intensity level.

Step 4: Apply Structured Thinking Frameworks

Select the frameworks most relevant to the scenario. Don't mechanically apply all of them — use the ones that surface real insight.

• First principles: What problem does this actually solve? Is the user solving the root problem or a symptom? Strip away assumptions and rebuild from fundamentals.

• Inversion: "What would make this fail?" Work backward from failure. Identify the specific conditions under which this decision becomes a mistake. This surfaces risks that forward-looking analysis misses.

• Pre-mortem (Gary Klein): "It's 6 months from now and this was a mistake. What went wrong?" Write the post-mortem before the decision. This is the single most effective debiasing technique for overconfident plans — use it for every "think it through" and "stress test" analysis.

• Second-order thinking: "And then what?" Trace downstream consequences 2-3 levels deep. First-order: "We save time." Second-order: "The team doesn't learn the underlying system." Third-order: "We can't debug production issues without the vendor."

• Occam's razor: Is there a simpler approach that achieves the same outcome? Complexity is a cost. If a simpler solution gets 80% of the benefit at 20% of the complexity, that's usually the right call.

• Sunk cost check: Is the user's preference influenced by work already invested? "We've already built X, so we should keep going" is not a valid argument if X is leading somewhere bad.

• Map vs. territory: Is the analysis based on how the system actually works, or on abstractions and assumptions? Check for gaps between mental models and reality.

• Circle of competence: Does the team have the skills to build AND maintain this? Building something is the easy part. Operating it at 2am when it breaks is the real question.

Step 5: Confirmation Bias Countermeasures

These are non-negotiable. Apply them before presenting your analysis:

1. Steelman first: Demonstrate that you understand the user's position at its strongest. Restate their idea better than they stated it. Only then proceed to challenge.

2. Three reasons the core assumption is wrong: Before agreeing with any part, identify at least 3 reasons the fundamental premise might be flawed. Not nitpicks — genuine structural challenges.

3. Logical fallacy scan: Check the reasoning for common traps:

   • Appeal to authority ("Google does it this way")
   • Appeal to novelty ("it's the modern approach")
   • False dichotomy ("we either do X or nothing")
   • Survivorship bias ("Company Y succeeded with this" — what about the ones that didn't?)
   • Anchoring ("the current system takes X ms, so Y ms would be great" — is Y the right target?)

4. Conflicting viewpoint: Argue from the perspective of someone who fundamentally disagrees. Not as theater — genuinely find the strongest counterargument and present it.

Step 6: Multi-Perspective Analysis

Don't just analyze from the user's viewpoint. Explicitly adopt these lenses:

• The implementer: Can this actually be built in the proposed timeline? What are they not accounting for?
• The maintainer: What does this look like to debug at 2am in 18 months? What's the operational burden?
• The new team member: Can someone onboard to this in a reasonable time? Is the complexity justified?
• The stakeholder: Does this deliver the business outcome they actually need, or the one the engineer wants to build?
• The adversary: If someone wanted to argue against this in a tech review, what's their strongest case?

Step 7: Produce the Assessment

Use the appropriate format based on scenario type.

If the assessment is saved, shared, or handed to another engineer/agent, read context/standards/html-plan-standard.md (the Artifact Format Standard). Sounding-board analyses default to Markdown-first — they're text-heavy critique docs. Use the sections below as the content structure inside analysis.md. Generate analysis.html as a visual companion only when the analysis has substantial visual content (matrices with semantic colors, side-by-side comparisons) that the MD can't carry well.

For technical decisions:

## Sounding Board: [Decision Title]

### Classification
- Type: [architecture / technology / design / implementation / process / risk]
- Reversibility: [Type 1 (one-way door) / Type 2 (two-way door)]
- Intensity: [sanity check / think it through / stress test]

### Understanding Your Position
(Steelman the user's idea — restate it at its strongest)

### What the Research Found
- Codebase: [summary of current architecture, patterns, dependencies, coupling points explored]
- Internal docs: [summary of relevant Confluence docs, Jira history, Slack threads]
- External: [summary of industry perspective, case studies, benchmarks]
- Prior art internally: [any previous attempts or related decisions]

### Challenges to the Core Assumption
1. [Genuine structural challenge with evidence]
2. [Genuine structural challenge with evidence]
3. [Genuine structural challenge with evidence]

### Pre-mortem: How This Fails
(It's 6 months from now and this was a mistake. Here's the post-mortem.)

### Pros / Cons
| Pros | Evidence Strength | Cons | Evidence Strength |
|------|------------------|------|------------------|
| ... | high/medium/low | ... | high/medium/low |

### Risk Matrix
| Risk | Severity | Likelihood | Mitigation | Residual Risk |
|------|----------|-----------|------------|---------------|
| ... | high/med/low | high/med/low | ... | ... |

### Second-Order Effects
- If you do this: [consequence chain 2-3 levels deep]
- If you don't do this: [consequence chain 2-3 levels deep]

### Alternatives Considered
| Option | Effort | Risk | Outcome | Notes |
|--------|--------|------|---------|-------|
| Proposed approach | ... | ... | ... | ... |
| Alternative 1 | ... | ... | ... | ... |
| Alternative 2 | ... | ... | ... | ... |
| Do nothing | ... | ... | ... | ... |

### Recommendation
**[Clear recommendation]** — Confidence: [high / medium / low]

[Reasoning in 2-3 sentences. If evidence clearly favors one side, say so. Don't be balanced for the sake of balance.]

### Cognitive Biases Detected
(If any were detected in the user's reasoning, name them gently with explanation)

### Next Steps
- [ ] [Specific action 1]
- [ ] [Specific action 2]
- [ ] [Questions to answer before committing]

For communication drafts:

## Sounding Board: Communication Review

### Classification
- Type: communication draft
- Medium: [Slack / email / doc / meeting]
- Intensity: [sanity check / think it through / stress test]

### Audience Analysis
- **Who**: [recipient(s)]
- **Their incentives**: [what they care about]
- **Power dynamic**: [peer / up / down / cross-functional]
- **Current context**: [what's happening that makes this message necessary]

### Assessment of the Draft
- **Clarity**: [Does it say what the user means? Any ambiguity?]
- **Tone**: [Appropriate for the audience and situation?]
- **Completeness**: [Missing context the reader needs?]
- **Unintended readings**: [Could this be interpreted differently than intended?]

### Strongest Counterargument
(If the recipient pushed back, what's the most compelling thing they'd say?)

### Stress Test
(What happens if this message gets forwarded to someone it wasn't intended for?)

### Revised Draft
(Improved version with explanation of changes)

### Next Steps
- [ ] Send as-is / send revised version / hold and discuss first

Step 8: Offer Concrete Next Steps

Based on the analysis, offer to produce:

• Architecture Decision Record (ADR) following the standard format: Context, Decision, Consequences, Alternatives Considered — for architecture decisions
• Revised communication draft — for Slack messages, emails, or docs
• Alternative proposal — if the analysis suggests a meaningfully different approach
• List of questions to answer first — if the decision can't be made with current information
• Send a Slack message via mcp__claude_ai_Slack_MCP__slack_send_message — with explicit user approval before sending
• Run /plan-create to create a strategic plan if the analysis supports moving forward

Three-Step Engagement Loop

Every interaction follows this pattern:

1. Present understanding: Show the user you grok their idea (steelman)
2. Deliver the adversarial analysis: The structured assessment with genuine challenges
3. Collaborate on resolution: What holds up, what needs to change, what's the path forward

This prevents the interaction from feeling like an attack. The user should feel heard, then challenged, then supported.

Important Notes

• This is a principal engineer. Don't explain basics. Challenge at the right level — system design tradeoffs, organizational dynamics, second-order effects.
• Evidence over opinion. Every claim must trace to a source: an internal doc found during research, a web result, or explicit first-principles reasoning labeled as such.
• State confidence honestly. High = strong evidence found. Medium = some evidence, extrapolating. Low = reasoning from general principles, no direct evidence.
• Don't be balanced for the sake of balance. If the evidence clearly favors one side, say so. False balance is its own form of dishonesty.
• Name cognitive biases gently. "This might be anchoring on the current architecture" is better than "You have anchoring bias." The user is smart — they'll see it once it's named.
• Speed-match the scenario. Communication drafts need fast turnaround; architecture decisions warrant deep research. Don't over-analyze a Slack message or under-analyze a migration plan.
• The user asked for a sounding board, not a yes-man. The most valuable output is the challenge they didn't see coming. If you agree with everything, you've failed.