# design: Clew-Bot (Context-Aware Code Reviewer)

**Status**: PROPOSED
**Type**: Reference Implementation / Demo

## 1. What is Clew-Bot?
Clew-Bot is a **Reference Implementation** of an AI Agent that uses the Clew Universal MCP to perform a high-value software engineering task: **Context-Aware Code Review**.

It is not just a "demo" in the sense of a toy; it is a **Blueprint** for how future agents (e.g., in IDEs or CI pipelines) should interact with the codebase.

### The Problem with Current LLM Reviews
Most LLM-based PR reviewers (e.g., GitHub Copilot PR Summary, Codium) are **Context-Blind**.
- They see the diff: `+ function foo()`.
- They comment on syntax or local style.
- They **FAIL** to catch architectural issues: "This function duplicates logic from `utils.legacy_foo` which is deprecated."

### The Solution: Graph-Augmented Review
Clew-Bot uses the **Clew Engine** to traverse the dependency graph *before* reviewing the code.
1.  **See Change**: `src/auth.py` modified.
2.  **Ask Clew**: `explore_module("src/auth.py")`.
3.  **Receive Context**:
    -   *Incoming*: Used by `APIKeyMiddleware`.
    -   *Outgoing*: Imports `legacy_hashing` (DEPRECATED).
4.  **Review**: "Warning: You are importing a deprecated hashing module in the critical Auth path."

## 2. User Experience

### As a CLI Tool
```bash
# Analyze current staged changes
clew-bot review --staged

# Analyze a specific PR (GitHub)
clew-bot review --pr https://github.com/org/repo/pull/123
```

### Output
A structured Markdown report containing:
1.  **Summary**: High-level impact analysis.
2.  **Architectural Context**:
    -   **Visual Graph**: A Mermaid diagram showing what the changed files touch (Dependencies & Dependents).
    -   **Critical Paths**: "This change affects `CheckoutFlow`, which is High Risk."
3.  **Code Review Comments**: Specific line-item feedback backed by the graph context.

## 3. How an Agent Uses It
The inputs and outputs of Clew-Bot are designed for Agents.

### Agent Workflow (Pseudo-Code)
```python
# 1. Get the Diff
diff = git.get_diff()

# 2. Identify Targets
files = parse_diff(diff)

# 3. Gather Context (The "Clew" Magic)
context_buffer = []
for file in files:
    # Call the Universal MCP Tool
    analysis = await mcp.call_tool("explore_module", path=file)
    context_buffer.append(analysis)

# 4. Reason (The LLM)
prompt = f"""
You are a Senior Architect. Review this Diff given the Architectural Context.
DIFF:
{diff}

CONTEXT (from Clew Engine):
{context_buffer}

Task:
- Identify breaking changes to callers (listed in USAGE).
- Flag new dependencies (listed in DEPENDENCIES).
- visualize the impact with Mermaid.
"""
review = llm.generate(prompt)
```

## 4. Technical Implementation

### Components
1.  **`clew-bot` Script**: A Python CLI tool.
2.  **Universal MCP Client**: Connects to the local Engine or Remote Platform (auto-detects).
3.  **LLM Integration**: Uses `ell` (or `litellm`) to drive the reasoning.

### Deliverables (Stream 3)
1.  `clew-engine/examples/clew_bot.py`: The script.
2.  Dependencies: `typer` (CLI), `model` (LLM abstraction).

## 5. Why Build This? (The "Wow")
This proves that **Graph RAG > Vector RAG** for code.
-   **Vector RAG** might find similar code, but misses the *caller* relationship.
-   **Clew-Bot** will explicitly say "This change breaks `Service B` because `Service B` calls this function," which is impossible without the graph.
