planz

What this skill does

# Inference Planz Skill

This skill enables a sophisticated multi-agent workflow for understanding user prompts, gathering clarifications, and producing production-grade implementation plans.

## How It Works

### Pipeline Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                    INFERENCE PLANZ PIPELINE                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 0: INPUT NORMALIZATION                                      │
│ - Trim whitespace, remove trigger prefix                         │
│ - Detect language and tone                                       │
│ - Extract: entities, constraints, objectives, deliverables       │
│ - Create structured context object                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 1: RESEARCH AGENT                                           │
│ Purpose: Deep research and thinking on user intent               │
│ Output:                                                          │
│   - Intent summary                                               │
│   - Assumptions inferred                                         │
│   - Key unknowns                                                 │
│   - Constraints detected                                         │
│   - Approach options (A, B, C with tradeoffs)                    │
│   - Risks and mitigations                                        │
│   - Success criteria                                             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 2: SURVEY AGENT                                             │
│ Purpose: Generate clarification questions                        │
│ Inputs: Original prompt + Research synthesis                     │
│ Output: Multiple-choice survey (5-10 questions)                  │
│   - Each question: 3-7 options (A, B, C, D, etc.)               │
│   - Include "Other" when appropriate                             │
│   - Covers: goal, user, format, scope, constraints, timeline     │
│   - Final confirmation question                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 3: PLAN AGENT                                               │
│ Purpose: Create actionable roadmap                               │
│ Inputs: Original prompt + Research + Survey questions            │
│ Output (provisional until survey answered):                      │
│   - Project overview                                             │
│   - Milestones and phases                                        │
│   - Detailed task breakdown                                      │
│   - Interfaces and contracts                                     │
│   - Data structures                                              │
│   - Failure modes and recovery                                   │
│   - Test plan                                                    │
│   - Definition of Done                                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ FINAL OUTPUT COMPOSITION                                         │
│ 1. Inference Planz Summary                                       │
│ 2. Research Synthesis                                            │
│ 3. Clarification Survey                                          │
│ 4. Provisional Roadmap Plan                                      │
│ 5. Proceed Question                                              │
└─────────────────────────────────────────────────────────────────┘
```

## Agent Specifications

### Research Agent

**Objective**: Perform deep research and thinking on what the user is truly asking

**Prompt Template**:
```
You are a Research Agent analyzing a user's request. Your job is to deeply understand their intent and provide structured analysis.

User Request: {user_prompt}

Analyze this request and provide:

1. **Intent Summary**: What is the user truly trying to accomplish?

2. **Assumptions Inferred**: What assumptions can we reasonably make?

3. **Key Unknowns**: What critical information is missing?

4. **Constraints Detected**: What limitations or requirements are implied?

5. **Recommended Approaches**:
   - **Option A**: [Description] - Tradeoffs: [pros/cons]
   - **Option B**: [Description] - Tradeoffs: [pros/cons]
   - **Option C**: [Description] - Tradeoffs: [pros/cons]

6. **Risks and Mitigations**: What could go wrong and how to prevent it?

7. **Success Criteria**: How do we know when this is done well?

Be concise but thorough. Focus on actionable insights.
```

### Survey Agent

**Objective**: Generate targeted multiple-choice questions for INTERACTIVE clarification with CZ (Confidenz) score integration

## CRITICAL REQUIREMENT: USE AskUserQuestion TOOL WITH CZ SCORING 

**The Survey Agent generates JSON. YOU MUST then CALL the `AskUserQuestion` tool.**

❌ **NEVER** output text-based surveys like "Type 1C 2D 3A..."
❌ **NEVER** display A) B) C) D) options as plain text
ALWAYS read CZ score from `.claude/confidenz-latest.json` first
ALWAYS display CZ status line before each question batch
ALWAYS call `AskUserQuestion` tool to render interactive clickable options

**Output Format**: The Survey Agent outputs structured JSON that MUST BE PARSED and used to CALL `AskUserQuestion` tool for an interactive user experience.

**CZ (Confidenz) Score Integration**:
- Read CZ First: Read `.claude/confidenz-latest.json` before presenting questions
- CZ at Bottom: Output `CZ: XX% [level] confidence` before EVERY question batch
- **CZ-Colored Labels**: Use emoji matching CZ score: (90+), (70-89),  (<70)
- CZ at Bottom: Output CZ score after question


**Interactive Survey Features**:
- Accept All: First question MUST be "Accept All Recommended" with CZ badge
- Recommended Answers: Mark best option with (Recommended) and color with CZ ANSI
- CZ Color Coding: ANSI color indicates confidence (green=high, yellow=moderate, red=low)
- Clickable Options: Users select options via buttons/chips instead of typing "1B 2D 3A"
- Descriptions: Each option includes explanation
- Batched Questions: Questions presented in groups of 4 (AskUserQuestion tool limit)
- Other Option: Automatically provided for custom user input

**Accept All Feature** (MUST be presented FIRST before any other questions):

First, output CZ status line:
```
CZ: XX% [level] confidence
```

Then call AskUserQuestion with CZ-colored recommended option:
```json
{
  "question": "Research complete! Would you like to accept all recommended defaults or review each question?",
  "header": "Quick Start",
  "multiSelect": false,
  "options": [
    { "label": "Accept All Recommended", "description": "Skip survey, use intelligent defaults based on research synthesis " },
    { "label": "Review each question", "description": "Answer questions individually to customize the plan" }
  ]
}
```
**CRITICAL**:
- The emoji must match CZ score: (90+), (70-89),  (<70)
- Put recommended option first with (Recommended) suffix
- Include `(CZ: XX% - [level] confidence)` in description
If user selects "Accept All Recommended": Skip remaining questions, auto-select all recommended options, proceed to Plan Agent.

**Prompt Template**:
```
You are a Survey Agent creating clarification quest