Skip to content

Commit 68431bb

Browse files
wyattowalshwyattowalsh
committed
Enhance README with advanced GFM features
- Add responsive banner placeholder (dark/light mode) - Add GitHub callouts ([!TIP], [!NOTE], [!IMPORTANT], [!CAUTION]) - Add collapsible sections (<details>) - Add footnotes for research citations - Enhance mermaid diagrams with subgraphs and styling - Add state machine table - Improve table formatting with alignment - Add centered header with badges and nav links - Create assets/ directory for banner images
1 parent 86cc3ea commit 68431bb

2 files changed

Lines changed: 194 additions & 72 deletions

File tree

‎README.md‎

Lines changed: 187 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,35 @@
1+
<picture>
2+
<source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.png">
3+
<source media="(prefers-color-scheme: light)" srcset="assets/banner-light.png">
4+
<img alt="panel-skill banner" src="assets/banner-dark.png">
5+
</picture>
6+
7+
<div align="center">
8+
19
# panel-skill
210

3-
Expert panel discussions for complex decisions. Claude becomes 3-7 domain experts who debate, challenge each other, and synthesize actionable recommendations.
11+
**Expert panel discussions for complex decisions**
12+
13+
Claude becomes 3-7 domain experts who debate, challenge each other, and synthesize actionable recommendations through [Hegelian dialectic](#philosophical-foundations).
14+
15+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
16+
[![Research-Backed](https://img.shields.io/badge/Research-Backed-green.svg)](#research-foundations)
17+
18+
[Install](#install) • [Usage](#usage) • [How It Works](#how-it-works) • [Research](#research-foundations)
19+
20+
</div>
21+
22+
---
423

524
## Install
625

726
```bash
827
npx skills add wyattowalsh/panel-skill
928
```
1029

30+
> [!TIP]
31+
> After installation, the `/panel` command becomes available in Claude Code.
32+
1133
## Usage
1234

1335
```bash
@@ -18,13 +40,21 @@ npx skills add wyattowalsh/panel-skill
1840

1941
### Options
2042

21-
| Option | Values | Default |
22-
|--------|--------|---------|
23-
| `size` | 3-7 | auto (based on topic breadth) |
24-
| `depth` | quick / standard / deep | standard |
25-
| `style` | collaborative / adversarial / academic | collaborative |
43+
| Option | Values | Default | Description |
44+
|:-------|:-------|:--------|:------------|
45+
| `size` | `3`-`7` | auto | Number of experts (auto-scales with topic breadth) |
46+
| `depth` | `quick` / `standard` / `deep` | `standard` | Discussion rounds: 1 / 2-3 / 4+ |
47+
| `style` | `collaborative` / `adversarial` / `academic` | `collaborative` | Panel interaction tone |
48+
49+
> [!NOTE]
50+
> Low-complexity topics (e.g., "What port does PostgreSQL use?") trigger a warning—multi-agent debate adds overhead without benefit for simple questions.
51+
52+
---
53+
54+
## Example Output
2655

27-
## Example
56+
<details open>
57+
<summary><strong>📋 Microservices Migration Panel</strong></summary>
2858

2959
```
3060
╭─ Panel Discussion: Microservices Migration ───────────────╮
@@ -49,121 +79,206 @@ npx skills add wyattowalsh/panel-skill
4979
• Agreement: Team capability matters more than architecture choice
5080
• Tension: Invest in microservices now vs. extract services later
5181
• Open question: What are our actual scaling bottlenecks?
82+
83+
╭───────────────────────────────────────────────────────────╮
84+
│ [1] Continue [2] Follow-up [3] Redirect [4] Conclude │
85+
╰───────────────────────────────────────────────────────────╯
5286
```
5387

88+
</details>
89+
90+
---
91+
5492
## How It Works
5593

5694
```mermaid
57-
flowchart LR
58-
A[Topic] --> B[Assess Complexity]
59-
B --> C[Generate Diverse Experts]
60-
C --> D[Debate]
61-
D --> E{Converged?}
62-
E -->|Stalled| F[Adjust Panel]
63-
F --> D
64-
E -->|Yes| G[Synthesize]
65-
G --> H[Recommendations]
95+
flowchart TB
96+
subgraph Input
97+
A[🎯 Topic]
98+
end
99+
100+
subgraph Validation
101+
B{Complexity<br/>Score}
102+
B -->|5-7: Low| C[⚠️ Warn User]
103+
C --> D{Proceed?}
104+
D -->|No| E[Direct Answer]
105+
D -->|Yes| F
106+
B -->|8-15| F[✓ Continue]
107+
end
108+
109+
subgraph Panel["Panel Assembly"]
110+
F --> G[Generate Experts]
111+
G --> H{Diversity<br/>≥60?}
112+
H -->|No| G
113+
H -->|Yes| I[🎭 Panel Ready]
114+
end
115+
116+
subgraph Discussion
117+
I --> J[Round N]
118+
J --> K[Cross-Examination]
119+
K --> L[🛡️ Contrarian Check]
120+
L --> M[📋 Synthesis]
121+
M --> N{Converged?}
122+
N -->|No| O{Stalled?}
123+
O -->|Yes| P[Adjust Panel]
124+
P --> J
125+
O -->|No| J
126+
end
127+
128+
subgraph Output
129+
N -->|Yes| Q[📊 Final Report]
130+
end
131+
132+
A --> B
66133
```
67134

68-
The skill screens low-complexity topics (e.g., "What port does PostgreSQL use?") with a warning, since multi-agent debate adds overhead without benefit for simple questions.
135+
### State Machine
136+
137+
| State | Description | Exit Condition |
138+
|:------|:------------|:---------------|
139+
| `COMPLEXITY_CHECK` | Assess if topic warrants panel | Score calculated |
140+
| `EXPERT_GENERATION` | Create diverse personas | Diversity ≥60 |
141+
| `DISCUSSION` | Facilitate debate rounds | Convergence or max rounds |
142+
| `SYNTHESIS` | Generate recommendations | Report complete |
143+
144+
> [!IMPORTANT]
145+
> Every panel **must** include three archetypes: **Contrarian** (challenges consensus), **Synthesizer** (connects perspectives), and **Specialist** (provides domain depth).
69146
70147
---
71148

72149
## Research Foundations
73150

74-
This skill is grounded in peer-reviewed multi-agent debate research. The design synthesizes findings from multiple 2024-2025 publications into actionable principles.
151+
This skill synthesizes findings from peer-reviewed multi-agent debate research[^1].
75152

76153
### Core Findings
77154

78155
| Finding | Source | Implementation |
79-
|---------|--------|----------------|
80-
| Diversity is the dominant driver of debate quality | [Wu et al. 2025](https://arxiv.org/abs/2511.07784) | Diversity score ≥60 required before proceeding |
81-
| Majority pressure suppresses independent correction | [Wu et al. 2025](https://arxiv.org/abs/2511.07784) | Contrarian protection protocol |
82-
| Heterogeneous agents outperform homogeneous | [A-HMAD 2025](https://link.springer.com/article/10.1007/s44443-025-00353-3) | Max 30% same-archetype rule |
83-
| MAD helps complex tasks, not simple ones | [ICLR 2025 Analysis](https://d2jud02ci9yv69.cloudfront.net/2025-04-28-mad-159/blog/mad/) | Complexity classifier (5-15 scale) |
84-
| Confidence weighting improves synthesis | [CISC, ACL 2025](https://aclanthology.org/2025.findings-acl.1030/) | Weight positions by expertise + confidence |
85-
| 3 agents × 2 rounds is effective baseline | [Du et al. ICML 2024](https://arxiv.org/abs/2305.14325) | Default: 4-5 experts, 2-3 rounds |
86-
| Stability detection improves stopping | [Adaptive MAD 2025](https://arxiv.org/abs/2510.12697) | Early termination + stall detection |
87-
| Dynamic composition beats static | [A-HMAD 2025](https://link.springer.com/article/10.1007/s44443-025-00353-3) | Mid-discussion panel adjustment |
156+
|:--------|:-------|:---------------|
157+
| Diversity is THE dominant driver | Wu et al. 2025[^2] | Diversity score ≥60 required |
158+
| Majority pressure suppresses correction | Wu et al. 2025[^2] | Contrarian protection protocol |
159+
| Heterogeneous > homogeneous agents | A-HMAD 2025[^3] | Max 30% same-archetype |
160+
| MAD helps complex, not simple tasks | ICLR 2025[^4] | Complexity classifier |
161+
| Confidence weighting improves synthesis | CISC 2025[^5] | Weighted aggregation |
162+
| 3 agents × 2 rounds is effective | Du et al. 2024[^6] | Default configuration |
88163

89-
### Key Research
164+
<details>
165+
<summary><strong>📚 Detailed Research Summaries</strong></summary>
90166

91-
#### Du et al. (ICML 2024) — "Improving Factuality and Reasoning through Multiagent Debate"
167+
#### Du et al. (ICML 2024)
168+
> "Improving Factuality and Reasoning through Multiagent Debate"
92169
93-
The foundational paper establishing that multiple LLM instances debating over rounds significantly improves reasoning. Key findings:
170+
The foundational paper establishing that multiple LLM instances debating over rounds significantly improves reasoning:
94171
- Cross-examination reduces hallucinations
95-
- Performance scales with agent count and debate rounds
96-
- 3 agents × 2 rounds is a cost-effective baseline
97-
98-
**Link**: https://arxiv.org/abs/2305.14325
99-
100-
#### Wu et al. (Nov 2025) — "Can LLM Agents Really Debate?"
101-
102-
Critical analysis revealing that **group diversity is THE dominant driver** of debate quality—more important than structural parameters like speaking order or confidence visibility. Also found that majority pressure suppresses correction, leading to conformity cascades.
103-
104-
**Implementation**: Required diversity scoring, contrarian protection protocol, explicit dissent solicitation before synthesis.
105-
106-
**Link**: https://arxiv.org/abs/2511.07784
172+
- Performance scales with agent count and rounds
173+
- 3 agents × 2 rounds is cost-effective baseline
107174

108-
#### A-HMAD (Nov 2025) — Adaptive Heterogeneous Multi-Agent Debate
175+
#### Wu et al. (Nov 2025)
176+
> "Can LLM Agents Really Debate?"
109177
110-
Demonstrates that heterogeneous specialized agents significantly outperform homogeneous teams. Simple majority voting underperforms quality-weighted aggregation.
178+
Critical analysis revealing **group diversity is THE dominant driver**—more important than speaking order or confidence visibility. Majority pressure suppresses correction, leading to conformity cascades.
111179

112-
**Implementation**: Mandatory archetype heterogeneity (Contrarian + Synthesizer + Specialist), no more than 30% same-archetype, adaptive moderation.
180+
#### A-HMAD (Nov 2025)
181+
> Adaptive Heterogeneous Multi-Agent Debate
113182
114-
**Link**: https://link.springer.com/article/10.1007/s44443-025-00353-3
183+
Heterogeneous specialized agents significantly outperform homogeneous teams. Simple majority voting underperforms quality-weighted aggregation.
115184

116-
#### CISC (ACL 2025) — Confidence Improves Self-Consistency
185+
#### CISC (ACL 2025)
186+
> Confidence Improves Self-Consistency
117187
118-
Shows that prioritizing high-confidence reasoning paths reduces required samples by 40%+ while maintaining accuracy. Confidence signals correlate with correctness.
188+
Prioritizing high-confidence reasoning paths reduces required samples by 40%+ while maintaining accuracy.
119189

120-
**Implementation**: Expert confidence signals (high/medium/low), domain expertise weighting, confidence-weighted synthesis.
121-
122-
**Link**: https://aclanthology.org/2025.findings-acl.1030/
190+
</details>
123191

124192
### Anti-Patterns Avoided
125193

126-
Research identifies failure modes that this skill actively prevents:
127-
128-
1. **Conformity Cascade** — LLMs tend toward majority positions, entrenching early errors.
129-
*Mitigation*: Required contrarian, explicit disagreement triggers.
130-
131-
2. **Devil's Advocate Overuse** — Pure adversarial debate reduces accuracy.
132-
*Mitigation*: Synthesizer required, ~90% collaborative tone.
133-
134-
3. **False Consensus** — Averaging positions loses nuance.
135-
*Mitigation*: Context-dependent synthesis, "CONTESTED" labeling when warranted.
194+
> [!CAUTION]
195+
> Research identifies these failure modes—panel-skill actively prevents them:
136196
137-
4. **Overhead on Simple Tasks** — MAD adds cost without benefit on easy questions.
138-
*Mitigation*: Complexity classifier screens topics before spawning panel.
197+
| Anti-Pattern | Problem | Mitigation |
198+
|:-------------|:--------|:-----------|
199+
| **Conformity Cascade** | LLMs drift toward majority, entrenching errors | Required contrarian + disagreement triggers |
200+
| **Devil's Advocate Overuse** | Pure adversarial debate reduces accuracy | Synthesizer required, ~90% collaborative |
201+
| **False Consensus** | Averaging positions loses nuance | Context-dependent synthesis, "CONTESTED" labels |
202+
| **Simple Task Overhead** | MAD adds cost without benefit | Complexity classifier screens topics |
139203

140204
### Philosophical Foundations
141205

142206
The synthesis mechanism uses **Hegelian dialectic**:
143-
- **Thesis**: Initial expert position
144-
- **Antithesis**: Challenging perspective
145-
- **Synthesis**: Higher-order integration (not compromise, but emergence)
146207

147-
Each round's synthesis becomes the next round's thesis, enabling progressive refinement.
208+
```mermaid
209+
flowchart LR
210+
T[Thesis<br/><i>Initial position</i>] --> A[Antithesis<br/><i>Challenge</i>]
211+
A --> S[Synthesis<br/><i>Emergence</i>]
212+
S -.->|"becomes next"| T2[New Thesis]
213+
214+
style T fill:#4a9eff,color:#fff
215+
style A fill:#ff6b6b,color:#fff
216+
style S fill:#51cf66,color:#fff
217+
style T2 fill:#4a9eff,color:#fff,stroke-dasharray: 5 5
218+
```
219+
220+
Each round's synthesis becomes the next round's thesis, enabling **progressive refinement** rather than simple compromise.
148221

149222
---
150223

151224
## Architecture
152225

153226
```
154227
panel-skill/
155-
├── SKILL.md # Execution instructions for Claude (~150 lines)
156-
├── references/ # Deep-dive documentation
228+
├── SKILL.md # Entry point (~150 lines)
229+
├── AGENTS.md # AI agent instructions
230+
├── CLAUDE.md # → symlink to AGENTS.md
231+
├── references/
157232
│ ├── research-foundations.md
158233
│ ├── expert-generation.md
159234
│ ├── turn-taking.md
160235
│ ├── synthesis-patterns.md
161236
│ └── output-formats.md
162-
└── examples/ # Sample discussions
237+
└── examples/
238+
├── architecture-decision.md
239+
├── business-strategy.md
240+
└── security-implementation.md
163241
```
164242

165-
The skill follows **progressive disclosure**: SKILL.md contains lean execution logic; reference files provide depth when needed.
243+
> [!NOTE]
244+
> The skill uses **progressive disclosure**: `SKILL.md` contains lean execution logic; reference files are loaded on-demand for depth.
245+
246+
---
247+
248+
## Contributing
249+
250+
See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
251+
252+
<details>
253+
<summary><strong>Quick Test Commands</strong></summary>
254+
255+
```bash
256+
# Install locally
257+
npx skills add ./
258+
259+
# Test complexity rejection
260+
/panel "What port does PostgreSQL use?"
261+
262+
# Test standard panel
263+
/panel "Redis vs Memcached?"
264+
265+
# Test deep panel
266+
/panel depth:deep "Microservices migration strategy"
267+
```
268+
269+
</details>
270+
271+
---
166272

167273
## License
168274

169-
MIT
275+
[MIT](LICENSE)
276+
277+
---
278+
279+
[^1]: Full citations in [references/research-foundations.md](references/research-foundations.md)
280+
[^2]: Wu et al. "Can LLM Agents Really Debate?" [arXiv:2511.07784](https://arxiv.org/abs/2511.07784)
281+
[^3]: A-HMAD "Adaptive Heterogeneous Multi-Agent Debate" [Springer](https://link.springer.com/article/10.1007/s44443-025-00353-3)
282+
[^4]: ICLR 2025 MAD Analysis [Blog](https://d2jud02ci9yv69.cloudfront.net/2025-04-28-mad-159/blog/mad/)
283+
[^5]: CISC "Confidence Improves Self-Consistency" [ACL 2025](https://aclanthology.org/2025.findings-acl.1030/)
284+
[^6]: Du et al. "Improving Factuality through Multiagent Debate" [arXiv:2305.14325](https://arxiv.org/abs/2305.14325)

‎assets/.gitkeep‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Assets
2+
3+
Place banner images here:
4+
- banner-dark.png
5+
- banner-light.png
6+
7+
See README.md for image generation prompt.

0 commit comments

Comments
 (0)