# Tool Manual: reflect

The `reflect` tool is a high-level cognitive utility designed to provide multi-perspective analysis for complex, ambiguous, or high-risk tasks. Instead of a single-stream thought process, it triggers three independent "expert" personas to analyze a given situation simultaneously.

## Purpose

The primary goal of `reflect` is to break confirmation bias and identify blind spots before execution. It is used to:
- Validate a plan before committing resources.
- Identify hidden risks in a proposed architecture.
- Find the simplest path for a complex implementation.
- Spot missing requirements or edge cases in a user request.

## The Three Personas

When `reflect` is called, it generates three distinct viewpoints:

### 1. The Critic
**Focus:** Risk, flaws, and assumptions.
- **Role:** Challenges the user's (or the agent's) underlying assumptions.
- **Goal:** To find why a plan might *fail*.
- **Key Questions:** "What if this assumption is wrong?", "Where is the single point of failure?", "Is this approach inherently flawed?"

### 2. The Pragmatist
**Focus:** Efficiency, simplicity, and execution.
- **Role:** Strips away unnecessary complexity and focuses on the most direct route to the goal.
- **Goal:** To find the *fastest/easiest* way to succeed.
- **Key Questions:** "What is the Minimum Viable Path?", "Can we achieve 80% of the result with 20% of the effort?", "Is there a simpler tool or method?"

### 3. The Detailer
**Focus:** Completeness, edge cases, and precision.
- **Role:** Scrutinizes the requirements for gaps, technical constraints, and overlooked details.
- **Goal:** To ensure *nothing is forgotten*.
- **Key Questions:** "What happens if the input is empty?", "Are the permissions correct?", "Are all dependencies accounted for?", "What are the boundary conditions?"

## Usage Guidelines

### When to use `reflect`
- **Before Planning:** Use it when you are about to use `todo` to set a complex plan.
- **When Stuck:** Use it if a tool call fails repeatedly or an approach is hitting a wall.
- **Ambiguity:** Use it when a user request is vague or could be interpreted in multiple ways.

### When NOT to use `reflect`
- **Simple Tasks:** Do not use it for single-step operations.
- **Routine Actions:** Do not use it for standard file reads, writes, or simple searches.
- **Before Basic Fact Gathering:** Do not use it as a substitute for checking connected MCP knowledge servers, docs, files, tool schemas, or obvious command output.

### The Importance of `assumptions`
The most critical input to the `reflect` tool is the `assumptions` parameter. 
- **Never leave it empty.**
- **Be brutally honest.** List everything you are taking for granted (e.g., "I assume the user has sudo access", "I assume the file exists in the workspace directory").
- **The act of listing assumptions often reveals the solution to the problem itself.**

## Autonomy Rule

If reflection finds missing information, resolve it through available sources first:
- connected MCP knowledge servers exposed by the active profile
- project docs or manuals
- memory for personal user facts
- source files and tool schemas
- command output
- web research when current external facts matter

Ask the user only when the missing decision is genuinely theirs to make or cannot be recovered from available sources.

## Example Input/Output Flow

**Input:**
- **Situation:** "I am planning to automate the deployment of a Docker container to a remote server using SSH, but I'm worried about security and connectivity."
- **Assumptions:** ["The server is reachable via SSH", "The user has the necessary keys configured", "The Docker daemon is running"]

**Output:**
- **Critic:** "You haven't mentioned how you will handle credential rotation or whether the SSH key is protected by a passphrase."
- **Pragmatist:** "Instead of a full automation script, use the existing deployment command if the project docs define one."
- **Detailer:** "Check whether the remote user has Docker permissions and whether the required network port is open before changing deployment logic."