diff --git a/Packs/pai-council-skill/README.md b/Packs/pai-council-skill/README.md index ed8e1dd06..9c22b87be 100755 --- a/Packs/pai-council-skill/README.md +++ b/Packs/pai-council-skill/README.md @@ -1,14 +1,14 @@ --- name: PAI Council Skill -pack-id: danielmiessler-pai-council-skill-v2.3.0 -version: 2.3.0 +pack-id: danielmiessler-pai-council-skill-v2.5.0 +version: 2.5.0 author: danielmiessler -description: Multi-agent debate system where specialized agents discuss topics in rounds, respond to each other's points, and surface insights through intellectual friction. +description: Multi-agent debate system where specialized agents discuss topics in rounds, respond to each other's points, and surface insights through intellectual friction. Now with adaptive rounds, file-first output, and recovery mode. type: skill -purpose-type: [decision-making, collaboration, multi-agent, debate, synthesis] +purpose-type: [decision-making, collaboration, multi-agent, debate, synthesis, recovery, resilience] platform: claude-code dependencies: [pai-core-install] -keywords: [council, debate, multi-agent, perspectives, synthesis, decision, architect, designer, engineer, researcher] +keywords: [council, debate, multi-agent, perspectives, synthesis, decision, architect, designer, engineer, researcher, recovery, adaptive, patchlist] ---
@@ -25,11 +25,15 @@ keywords: [council, debate, multi-agent, perspectives, synthesis, decision, arch ## What This Pack Provides -- **Multi-Agent Debate System** - Structured 3-round debates between specialized agents +- **Multi-Agent Debate System** - Structured 2-3 round debates between specialized agents +- **Adaptive Rounds** - Round 3 runs only when needed based on convergence detection +- **File-First Output** - Session state persists to `~/.claude/MEMORY/` for resilience +- **Recovery Mode** - Resume interrupted sessions from checkpoint - **Quick Consensus Check** - Fast single-round perspective gathering - **Council Members** - Architect, Designer, Engineer, Researcher (with optional Security, Intern, Writer) - **Visible Transcripts** - Full conversation history showing intellectual friction -- **Synthesis Engine** - Convergence detection and recommendation generation +- **Output Modes** - Deliberative (conversational) or Patchlist (structured changes) +- **Model Tiering** - Automatic model selection per round for cost efficiency ## Key Differentiator @@ -44,20 +48,23 @@ keywords: [council, debate, multi-agent, perspectives, synthesis, decision, arch ``` Council Skill ├── SKILL.md # Main entry point and routing +├── Config.md # Default settings, model tiering, output modes ├── CouncilMembers.md # Agent roles, perspectives, voices -├── RoundStructure.md # 3-round debate structure +├── RoundStructure.md # Round structure and timing ├── OutputFormat.md # Transcript format templates └── Workflows/ - ├── Debate.md # Full 3-round structured debate - └── Quick.md # Fast single-round check + ├── Debate.md # Full 2-3 round structured debate (adaptive) + ├── Quick.md # Fast single-round check + └── Recovery.md # Resume interrupted sessions ``` ## Workflows | Workflow | Purpose | Rounds | Output | |----------|---------|--------|--------| -| **DEBATE** | Full structured discussion | 3 | Complete transcript + synthesis | +| **DEBATE** | Full structured discussion | 2-3 (adaptive) | Complete transcript + synthesis | | **QUICK** | Fast perspective check | 1 | Initial positions only | +| **RECOVERY** | Resume interrupted session | Remaining | Continue from checkpoint | ## Default Council Members @@ -68,25 +75,33 @@ Council Skill | **Engineer** | Implementation reality, tech debt | Marcus Webb | | **Researcher** | Data, precedent, external examples | Ava Chen | -## Three-Round Debate Structure +## Adaptive Round Debate Structure -1. **Round 1 - Initial Positions**: Each agent states their perspective -2. **Round 2 - Responses & Challenges**: Agents respond to each other's points -3. **Round 3 - Synthesis**: Identify convergence, disagreements, final recommendations +1. **Round 1 - Initial Positions**: Each agent states their perspective (sonnet) +2. **Round 2 - Responses & Challenges**: Agents respond to each other's points (haiku) +3. **Round 3 - Synthesis** (conditional): Only runs if low convergence or blocking issues (sonnet) -**Total Time:** 30-90 seconds for full debate (parallel execution within rounds) +**Convergence Check:** After Round 2, the orchestrator evaluates whether agents have reached consensus. Round 3 is skipped if 3+ agents agree and no blocking issues remain. + +**Total Time:** 20-60 seconds (2 rounds) or 30-90 seconds (3 rounds) ## Usage Examples ``` "Council: Should we use WebSockets or SSE?" --> Invokes DEBATE workflow -> 3-round transcript +-> Invokes DEBATE workflow -> 2-3 round transcript "Quick council check: Is this API design reasonable?" -> Invokes QUICK workflow -> Fast perspectives "Council with security: Evaluate this auth approach" -> DEBATE with Security agent added + +"Council (patchlist): Review these specifications" +-> DEBATE with structured output format + +"Council recovery: Resume session 20260202-143052-a1b2c3d4" +-> RECOVERY workflow -> Continue from checkpoint ``` ## What's Included @@ -94,11 +109,13 @@ Council Skill | Component | File | Purpose | |-----------|------|---------| | Main Skill | src/skills/Council/SKILL.md | Entry point and workflow routing | +| Configuration | src/skills/Council/Config.md | Default settings, model tiering, output modes | | Council Members | src/skills/Council/CouncilMembers.md | Agent roles and voice mapping | | Round Structure | src/skills/Council/RoundStructure.md | Debate timing and phases | | Output Format | src/skills/Council/OutputFormat.md | Transcript templates | -| Debate Workflow | src/skills/Council/Workflows/Debate.md | Full 3-round debate | +| Debate Workflow | src/skills/Council/Workflows/Debate.md | Full 2-3 round adaptive debate | | Quick Workflow | src/skills/Council/Workflows/Quick.md | Fast consensus check | +| Recovery Workflow | src/skills/Council/Workflows/Recovery.md | Resume interrupted sessions | ## Integration @@ -115,6 +132,15 @@ Council Skill ## Changelog +### 2.5.0 - 2026-02-02 +- **Adaptive Rounds** - Round 3 now conditional based on convergence detection +- **File-First Output** - Session state persists to `~/.claude/MEMORY/` for resilience against context compaction and rate limits +- **Recovery Workflow** - Resume interrupted sessions with partial or full rerun options +- **Config.md** - Centralized configuration for rounds, agents, output modes, and model tiering +- **Output Modes** - Added `patchlist` mode for structured specification reviews +- **Model Tiering** - Automatic model selection (sonnet/haiku) per round for cost efficiency +- **Scope Limits** - Guidance on max items per council to prevent token explosion + ### 2.3.0 - 2026-01-14 - Initial public release - Complete debate and quick workflows diff --git a/Packs/pai-council-skill/src/skills/Council/Config.md b/Packs/pai-council-skill/src/skills/Council/Config.md new file mode 100644 index 000000000..91fc32af9 --- /dev/null +++ b/Packs/pai-council-skill/src/skills/Council/Config.md @@ -0,0 +1,126 @@ +# Council Configuration + +Default configuration for Council debates. These values can be overridden per-session by specifying config inline with the council request. + +## Debate Settings + +| Setting | Default | Description | +|---------|---------|-------------| +| `rounds` | 2-3 (adaptive) | Round 3 runs only if convergence is low after Round 2 | +| `agents` | 4 | Default: Architect, Designer, Engineer, Researcher | +| `output_mode` | `deliberative` | Options: `deliberative` (conversational), `patchlist` (structured changes) | +| `file_output` | `true` | Write each round to `~/.claude/MEMORY/` | + +## Model Tiering + +| Phase | Model | Rationale | +|-------|-------|-----------| +| Round 1 | sonnet | Initial positions need nuance | +| Round 2 | haiku | Responses are shorter, more constrained | +| Round 3 | sonnet | Synthesis needs quality | +| Final Synthesis | sonnet | Orchestrator synthesis | + +To use a specific model, add `model: "haiku"` or `model: "sonnet"` to the Task call. + +## Adaptive Round 3 + +Round 3 is **conditional**. After Round 2, the orchestrator evaluates: + +**Run Round 3 if ANY of these are true:** +1. Agents express explicit disagreement in Round 2 +2. Round 2 responses identify BLOCKING issues +3. The topic involves security, compliance, or irreversible decisions +4. User explicitly requested 3 rounds + +**Skip Round 3 if ALL of these are true:** +1. High convergence detected (majority of agents agree on core recommendation) +2. No BLOCKING items identified +3. No unresolved contradictions +4. Topic is exploratory, not normative + +When skipping Round 3, output: +```markdown +**Round 3 skipped:** High convergence detected. Proceeding to synthesis. +``` + +## Output Modes + +### Deliberative (default) +Conversational format for architectural debates, design decisions, exploratory discussions. + +```markdown +### Round N: [Phase Name] + +**🏛️ Architect (Serena):** +[Prose response, 50-150 words] +``` + +### Patchlist +Structured format for TaskSpec reviews, document improvements, code changes. + +```markdown +### Round N: [Phase Name] + +**🏛️ Architect (Serena):** + +**BLOCKING:** +- B1: [issue] → [proposed change] | Affects: [specs] + +**HIGH:** +- H1: [issue] → [proposed change] + +**MEDIUM/LOW:** +- M1: [issue] +``` + +To invoke patchlist mode: `"Council (patchlist): Review these TaskSpecs..."` + +## File Output Location + +When `file_output` is enabled (default), rounds are written to: + +``` +~/.claude/MEMORY/STATE/council-sessions/{session-id}/ +├── metadata.json # Topic, members, timing, config +├── round-1.md # All Round 1 responses +├── round-2.md # All Round 2 responses +├── round-3.md # Round 3 (if run) +└── convergence.json # Convergence assessment after Round 2 +``` + +After synthesis, the final output is archived to: +``` +~/.claude/MEMORY/RESEARCH/YYYY-MM/ +└── YYYY-MM-DD-HHMMSS_COUNCIL_{topic-slug}.md +``` + +This enables: +- **Recovery** from interrupted sessions (partial round data preserved) +- **Cross-session context** (prior council findings available) +- **Resistance to context compaction** (durable external state) + +## Scope Limits + +To prevent token explosion and rate-limit issues: + +| Limit | Value | Rationale | +|-------|-------|-----------| +| Max items per council | 5 | TaskSpecs, documents, or topics | +| Max agents | 7 | Diminishing returns beyond this | +| Max words per response | 150 | Prevents verbose agents | + +For larger reviews, run multiple councils with a shared context preamble. + +## Recovery Mode + +If a council session is interrupted (rate limit, timeout, crash), use the Recovery workflow: + +``` +"Council recovery: Resume session {session-id}" +``` + +See `Workflows/Recovery.md` for details. + +--- + +**Last Updated:** 2026-02-02 diff --git a/Packs/pai-council-skill/src/skills/Council/SKILL.md b/Packs/pai-council-skill/src/skills/Council/SKILL.md index 06d018bb2..1fbbb93c3 100755 --- a/Packs/pai-council-skill/src/skills/Council/SKILL.md +++ b/Packs/pai-council-skill/src/skills/Council/SKILL.md @@ -12,13 +12,20 @@ science_cycle_time: meso If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults. +## Configuration + +Load `Config.md` for default settings: +- **Adaptive rounds:** 2-3 based on convergence +- **File output:** Enabled by default (writes to `~/.claude/MEMORY/`) +- **Model tiering:** sonnet for Round 1/3, haiku for Round 2 +- **Output modes:** `deliberative` (default) or `patchlist` + # Council Skill Multi-agent debate system where specialized agents discuss topics in rounds, respond to each other's points, and surface insights through intellectual friction. **Key Differentiator from RedTeam:** Council is collaborative-adversarial (debate to find best path), while RedTeam is purely adversarial (attack the idea). Council produces visible conversation transcripts; RedTeam produces steelman + counter-argument. - ## Voice Notification **When executing a workflow, do BOTH:** @@ -50,42 +57,53 @@ Running the **WorkflowName** workflow from the **Council** skill... | Trigger | Workflow | |---------|----------| -| Full structured debate (3 rounds, visible transcript) | `Workflows/Debate.md` | +| Full structured debate (2-3 rounds, visible transcript) | `Workflows/Debate.md` | | Quick consensus check (1 round, fast) | `Workflows/Quick.md` | +| Resume interrupted session | `Workflows/Recovery.md` | | Pure adversarial analysis | RedTeam skill | ## Quick Reference | Workflow | Purpose | Rounds | Output | |----------|---------|--------|--------| -| **DEBATE** | Full structured discussion | 3 | Complete transcript + synthesis | +| **DEBATE** | Full structured discussion | 2-3 (adaptive) | Complete transcript + synthesis | | **QUICK** | Fast perspective check | 1 | Initial positions only | +| **RECOVERY** | Resume interrupted session | Remaining | Continue from last checkpoint | ## Context Files | File | Content | |------|---------| +| `Config.md` | Default settings, model tiering, output modes | | `CouncilMembers.md` | Agent roles, perspectives, voice mapping | -| `RoundStructure.md` | Three-round debate structure and timing | +| `RoundStructure.md` | Adaptive 2-3 round structure and timing | | `OutputFormat.md` | Transcript format templates | ## Core Philosophy **Origin:** Best decisions emerge from diverse perspectives challenging each other. Not just collecting opinions - genuine intellectual friction where experts respond to each other's actual points. -**Speed:** Parallel execution within rounds, sequential between rounds. A 3-round debate of 4 agents = 12 agent calls but only 3 sequential waits. Complete in 30-90 seconds. +**Speed:** Parallel execution within rounds, sequential between rounds. A 2-round debate of 4 agents = 8 agent calls but only 2 sequential waits. Complete in 20-60 seconds. + +**Resilience:** File-first output means session state survives context compaction and rate limits. ## Examples ``` "Council: Should we use WebSockets or SSE?" --> Invokes DEBATE workflow -> 3-round transcript +-> Invokes DEBATE workflow -> 2-3 round transcript "Quick council check: Is this API design reasonable?" -> Invokes QUICK workflow -> Fast perspectives "Council with security: Evaluate this auth approach" -> DEBATE with Security agent added + +"Council (patchlist): Review these specifications" +-> DEBATE with structured output format + +"Council recovery: Resume session 20260202-143052-a1b2c3d4" +-> RECOVERY workflow -> Continue from checkpoint ``` ## Integration @@ -101,7 +119,9 @@ Running the **WorkflowName** workflow from the **Council** skill... 2. Add domain-specific experts as needed (security for auth, etc.) 3. Review the transcript - insights are in the responses, not just positions 4. Trust multi-agent convergence when it occurs +5. Use patchlist mode for specification reviews +6. For large reviews (5+ items), run multiple councils with shared context --- -**Last Updated:** 2025-12-20 +**Last Updated:** 2026-02-02 diff --git a/Packs/pai-council-skill/src/skills/Council/Workflows/Debate.md b/Packs/pai-council-skill/src/skills/Council/Workflows/Debate.md index e6db22fc4..a88b31394 100755 --- a/Packs/pai-council-skill/src/skills/Council/Workflows/Debate.md +++ b/Packs/pai-council-skill/src/skills/Council/Workflows/Debate.md @@ -1,14 +1,43 @@ # Debate Workflow -Full structured multi-agent debate with 3 rounds and visible transcript. +Full structured multi-agent debate with 2-3 adaptive rounds, file-first output, and visible transcript. ## Prerequisites - Topic or question to debate - Optional: Custom council members (default: architect, designer, engineer, researcher) +- Optional: Output mode (`deliberative` or `patchlist`) + +## Configuration + +Load settings from `Config.md`. Key defaults: +- **Rounds:** 2-3 (adaptive based on convergence) +- **File output:** Enabled (writes to `~/.claude/MEMORY/`) +- **Model tiering:** Round 1 sonnet, Round 2 haiku, Round 3/Synthesis sonnet ## Execution +### Step 0: Initialize Session + +Generate a session ID and create session directory: + +```bash +SESSION_ID=$(date +%Y%m%d-%H%M%S)-$(openssl rand -hex 4) +mkdir -p ~/.claude/MEMORY/STATE/council-sessions/$SESSION_ID +``` + +Write `metadata.json`: +```json +{ + "session_id": "{SESSION_ID}", + "topic": "{topic}", + "started_at": "{ISO timestamp}", + "members": ["Architect", "Designer", "Engineer", "Researcher"], + "output_mode": "deliberative", + "rounds_planned": "adaptive" +} +``` + ### Step 1: Announce the Council Output the debate header: @@ -16,13 +45,15 @@ Output the debate header: ```markdown ## Council Debate: [Topic] +**Session ID:** {SESSION_ID} **Council Members:** [List agents participating] -**Rounds:** 3 (Positions → Responses → Synthesis) +**Rounds:** 2-3 (adaptive based on convergence) +**Output:** ~/.claude/MEMORY/STATE/council-sessions/{SESSION_ID}/ ``` ### Step 2: Round 1 - Initial Positions -Launch 4 parallel Task calls (one per council member). +Launch 4 parallel Task calls (one per council member). Use `model: "sonnet"`. **Each agent prompt includes:** ``` @@ -47,6 +78,12 @@ Your perspective focuses on: [agent's domain] - **engineer**: Implementation reality, tech debt, maintenance burden, practical constraints - **researcher** (ClaudeResearcher): Data, precedent, external examples, what others have done +**Write Round 1 to file:** +```bash +# Write combined Round 1 output to session directory +echo "[Round 1 content]" > ~/.claude/MEMORY/STATE/council-sessions/$SESSION_ID/round-1.md +``` + **Output each response as it completes:** ```markdown ### Round 1: Initial Positions @@ -66,7 +103,7 @@ Your perspective focuses on: [agent's domain] ### Step 3: Round 2 - Responses & Challenges -Launch 4 parallel Task calls with Round 1 transcript included. +Launch 4 parallel Task calls with Round 1 transcript included. Use `model: "haiku"`. **Each agent prompt includes:** ``` @@ -89,6 +126,11 @@ Now respond to the other council members: The value is in genuine intellectual friction—engage with their actual arguments. ``` +**Write Round 2 to file:** +```bash +echo "[Round 2 content]" > ~/.claude/MEMORY/STATE/council-sessions/$SESSION_ID/round-2.md +``` + **Output:** ```markdown ### Round 2: Responses & Challenges @@ -106,9 +148,36 @@ The value is in genuine intellectual friction—engage with their actual argumen [Response referencing others' points] ``` -### Step 4: Round 3 - Synthesis +### Step 3.5: Convergence Check (Adaptive Round 3) + +After Round 2, evaluate whether Round 3 is needed. + +**Run Round 3 if ANY of these are true:** +- Agents express explicit disagreement ("I disagree with...", "I challenge...") +- BLOCKING issues identified (security, compliance, irreversible decisions) +- Topic requires normative decision (not just exploratory) +- User explicitly requested 3 rounds + +**Skip Round 3 if ALL of these are true:** +- High convergence (majority of agents agree on core recommendation) +- No BLOCKING items identified +- No unresolved contradictions +- Topic is exploratory + +Write convergence assessment: +```bash +# Example: high convergence, skipping Round 3 +echo '{"converged": true, "reason": "4/4 agents agree on core recommendation", "proceed_to_round3": false}' > ~/.claude/MEMORY/STATE/council-sessions/$SESSION_ID/convergence.json +``` + +If skipping Round 3: +```markdown +**Round 3 skipped:** High convergence detected. Proceeding to synthesis. +``` + +### Step 4: Round 3 - Synthesis (Conditional) -Launch 4 parallel Task calls with Round 1 + Round 2 transcripts. +If Round 3 is needed, launch 4 parallel Task calls with Round 1 + Round 2 transcripts. Use `model: "sonnet"`. **Each agent prompt includes:** ``` @@ -130,6 +199,11 @@ Final synthesis from your perspective: Be honest about remaining disagreements—forced consensus is worse than acknowledged tension. ``` +**Write Round 3 to file:** +```bash +echo "[Round 3 content]" > ~/.claude/MEMORY/STATE/council-sessions/$SESSION_ID/round-3.md +``` + **Output:** ```markdown ### Round 3: Synthesis @@ -155,7 +229,7 @@ After all rounds complete, synthesize the debate: ### Council Synthesis **Areas of Convergence:** -- [Points where 3+ agents agreed] +- [Points where majority of agents agreed] - [Shared concerns or recommendations] **Remaining Disagreements:** @@ -166,6 +240,31 @@ After all rounds complete, synthesize the debate: [Based on convergence and weight of arguments, the recommended approach is...] ``` +### Step 6: Archive to RESEARCH + +After synthesis, archive the complete session: + +```bash +TOPIC_SLUG=$(echo "[topic]" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | cut -c1-50) +TIMESTAMP=$(date +%Y-%m-%d-%H%M%S) +MONTH=$(date +%Y-%m) +mkdir -p ~/.claude/MEMORY/RESEARCH/$MONTH +# Explicit file ordering (round-3.md may not exist if skipped) +cat ~/.claude/MEMORY/STATE/council-sessions/$SESSION_ID/round-1.md \ + ~/.claude/MEMORY/STATE/council-sessions/$SESSION_ID/round-2.md \ + ~/.claude/MEMORY/STATE/council-sessions/$SESSION_ID/round-3.md 2>/dev/null \ + > ~/.claude/MEMORY/RESEARCH/$MONTH/${TIMESTAMP}_COUNCIL_${TOPIC_SLUG}.md +``` + +Update metadata.json with completion status (merge with existing): +```json +{ + "completed_at": "2026-02-02T23:55:39Z", + "rounds_completed": 2, + "archived_to": "~/.claude/MEMORY/RESEARCH/2026-02/2026-02-02-235539_COUNCIL_example-topic.md" +} +``` + ## Custom Council Members If user specifies custom members, adjust accordingly: @@ -177,25 +276,58 @@ If user specifies custom members, adjust accordingly: ## Agent Type Mapping -| Council Role | Task subagent_type | Personality Reference | -|--------------|-------------------|----------------------| -| Architect | Architect | Serena Blackwood | -| Designer | Designer | Aditi Sharma | -| Engineer | Engineer | Marcus Webb | -| Researcher | PerplexityResearcher | Ava Chen | -| Security | Pentester | Rook Blackburn | -| Intern | Intern | Dev Patel | -| Writer | (use Intern with writer prompt) | Emma Hartley | +| Council Role | Task subagent_type | Model | Personality Reference | +|--------------|-------------------|-------|----------------------| +| Architect | Architect | sonnet | Serena Blackwood | +| Designer | Designer | sonnet | Aditi Sharma | +| Engineer | Engineer | sonnet | Marcus Webb | +| Researcher | PerplexityResearcher | sonnet | Ava Chen | +| Security | Pentester | sonnet | Rook Blackburn | +| Intern | Intern | haiku | Dev Patel | +| Writer | (use Intern with writer prompt) | haiku | Emma Hartley | ## Timing - Round 1: ~10-20 seconds (parallel) - Round 2: ~10-20 seconds (parallel) -- Round 3: ~10-20 seconds (parallel) +- Convergence check: ~1 second +- Round 3 (if needed): ~10-20 seconds (parallel) - Synthesis: ~5 seconds -**Total: 30-90 seconds for full debate** +**Total: 20-60 seconds** (2 rounds) or **30-90 seconds** (3 rounds) + +## Output Modes + +### Deliberative (default) +Standard conversational format. Use for architectural debates, design decisions, exploratory discussions. + +### Patchlist +Structured format for specification reviews. Invoke with: `"Council (patchlist): Review..."` + +In patchlist mode, instruct agents to structure responses as: + +```markdown +**BLOCKING:** +- B1: [issue] → [proposed change] + +**HIGH:** +- H1: [issue] → [proposed change] + +**MEDIUM/LOW:** +- M1: [issue] +``` + +## Interruption Handling + +If the council is interrupted (rate limit, timeout): +1. Session state is preserved in `~/.claude/MEMORY/STATE/council-sessions/{SESSION_ID}/` +2. Use Recovery workflow to resume: `"Council recovery: Resume session 20260202-235539-a1b2c3d4"` (replace with your actual session ID) +3. See `Workflows/Recovery.md` for details ## Done -Debate complete. The transcript shows the full intellectual journey from initial positions through challenges to synthesis. +Debate complete. The transcript is archived to `~/.claude/MEMORY/RESEARCH/` and shows the full intellectual journey from initial positions through challenges to synthesis. + +--- + +**Last Updated:** 2026-02-02 diff --git a/Packs/pai-council-skill/src/skills/Council/Workflows/Recovery.md b/Packs/pai-council-skill/src/skills/Council/Workflows/Recovery.md new file mode 100644 index 000000000..5e0b102c7 --- /dev/null +++ b/Packs/pai-council-skill/src/skills/Council/Workflows/Recovery.md @@ -0,0 +1,189 @@ +# Recovery Workflow + +Resume an interrupted Council session or rerun with partial prior results. + +## When to Use + +- Session was interrupted by rate limit, timeout, or context compaction +- Partial round outputs were saved before interruption +- You want to continue without re-running completed work + +## Prerequisites + +- Session ID or session directory path +- Prior round outputs (partial or complete) +- Knowledge of which agents completed / which didn't + +## Recovery Modes + +### Full Rerun + +Re-run all agents for all remaining rounds. Ignores prior partial outputs. + +**Use when:** +- Only 1-2 agents completed before interruption +- Significant time has passed (context may have drifted) +- User explicitly prefers fresh run + +**Invoke:** `"Council recovery (full rerun): {topic}"` + +### Partial Rerun + +Keep completed agent outputs, only rerun missing agents. + +**Use when:** +- 3+ agents completed Round 1 +- Interruption happened mid-round +- Time-sensitive and want to preserve progress + +**Invoke:** `"Council recovery (partial): Resume session {session-id}"` + +## Execution + +### Step 1: Load Session State + +**Session ID validation:** Before using a session ID in file paths, validate it matches the expected format `YYYYMMDD-HHMMSS-[hex]` (e.g., `20260202-235539-a1b2c3d4`). Reject IDs containing path traversal characters (`/`, `\`, `..`). + +Read the session directory: +``` +~/.claude/MEMORY/STATE/council-sessions/{session-id}/ +├── metadata.json # Topic, members, config +├── round-1.md # Partial or complete +├── round-2.md # Partial or complete (if exists) +└── convergence.json # (if exists) +``` + +Parse `metadata.json` to determine: +- Which round was interrupted +- Which agents completed that round +- Which agents need to be re-run + +### Step 2: Announce Recovery + +```markdown +## Council Recovery: [Topic] + +**Session ID:** {session-id} +**Mode:** [Full Rerun | Partial Rerun] +**Prior Progress:** +- Round 1: [Complete | Partial - {N}/4 agents] +- Round 2: [Complete | Partial | Not started] +- Round 3: [Complete | Partial | Not started] + +**Recovery Plan:** +- [List of agents to rerun] +- [Rounds to complete] +``` + +### Step 3a: Full Rerun + +If full rerun mode: + +1. Archive prior session state to `~/.claude/MEMORY/RESEARCH/` with `_INTERRUPTED` suffix +2. Start fresh session with new session ID +3. Follow standard Debate workflow from Round 1 + +### Step 3b: Partial Rerun + +If partial rerun mode: + +1. Load completed agent outputs from prior round +2. Launch only the missing agents with this context: + +``` +You are [Agent Name], [brief role description]. + +COUNCIL RECOVERY - ROUND {N}: [PHASE NAME] + +Topic: [The topic being debated] + +Context: This is a recovery from an interrupted session. The following agents already completed Round {N}: + +[Prior agent outputs from this round] + +Your task: +- Provide your Round {N} response +- You may reference the prior agents' points +- Stay consistent with the established discussion +- [Standard round instructions] +``` + +3. Merge recovered outputs with new outputs +4. Continue to next round + +### Step 4: Resume Normal Flow + +After recovery round completes: +- Update session state files +- Continue with next round (or synthesis if Round 3 complete) +- Follow standard adaptive Round 3 logic + +### Step 5: Mark Recovery Complete + +After synthesis: +```markdown +**Recovery Complete:** Session resumed from Round {N}. Full transcript archived. +``` + +Archive final output to: +``` +~/.claude/MEMORY/RESEARCH/YYYY-MM/YYYY-MM-DD-HHMMSS_COUNCIL_{topic-slug}_RECOVERED.md +``` + +## Diff-Only Mode (Partial Rerun Optimization) + +For partial reruns where 3+ agents completed, instruct recovered agents: + +``` +You are joining a council session in progress. The following perspectives have already been shared: + +[Prior agent outputs] + +Your task is to add NET-NEW insights only: +- Do not repeat points already made +- Focus on what the prior agents missed +- State your unique perspective +- If you agree with prior points, briefly acknowledge and move on +``` + +This reduces token usage while preserving the intellectual friction value. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| Session directory not found | Ask user for session ID or start fresh | +| metadata.json corrupted | Start fresh, note what was lost | +| Round files missing | Treat as partial, rerun missing rounds | +| All agents completed but synthesis missing | Skip to synthesis step | + +## Example Recovery Flow + +``` +User: "Council recovery: Resume session abc123" + +System reads: ~/.claude/MEMORY/STATE/council-sessions/abc123/ +- metadata.json shows: Round 1 interrupted, 1/4 agents complete +- round-1.md contains: Aditi (Designer) completed + +System response: +## Council Recovery: [Topic from metadata] + +**Session ID:** abc123 +**Mode:** Partial Rerun +**Prior Progress:** +- Round 1: Partial - 1/4 agents (Aditi complete) +- Round 2: Not started + +**Recovery Plan:** +- Rerun Round 1 for: Architect (Serena), Engineer (Marcus), Researcher (Ava) +- Complete Round 2 +- Evaluate for Round 3 +- Synthesize + +Proceeding with recovery... +``` + +--- + +**Last Updated:** 2026-02-02