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."