# ADR-004: Stream 3 - The "First Wow" Implementation

**Date:** 2026-02-07
**Status:** Accepted

## Context

After completing the core Engine, Platform, and MCP strategy (ADRs 001-003), we needed to demonstrate concrete product value. Stream 3 focused on creating a "First Wow" experience that showcases Clew's unique capabilities beyond simple code search.

## Decision

We implemented three key features:

### 1. Mermaid Diagram Generation
- Added Mermaid `graph TD` output to MCP tool responses
- Visualizes code relationships (IMPORTS, CALLS, DEFINES, CONTAINS)
- Highlights the current node with `:::current` CSS class

### 2. Clew-Bot PR Reviewer (`examples/clew_bot.py`)
- Standalone script that analyzes git diffs using Clew Engine API
- Uses `/search` and `/graph/traverse` endpoints to build context
- Outputs impact analysis (incoming calls) and dependency list

### 3. Zero-Touch Ingestion
- Git `post-commit` hook triggers background ingestion
- `scripts/install_hooks.sh` for easy setup
- Docker-based ingestion service in `docker-compose.yml`

### 4. Path Filtering (Bug Fix)
- Added `path`, `path_contains`, `type` filters to Qdrant adapter
- Enables exact file matching instead of relying only on semantic similarity
- `clew_bot.py` uses `path_contains` filter with fallback to semantic search

## Consequences

### Positive
- Clear demonstration of Clew's value proposition (graph context in PRs)
- Zero manual steps for users after initial setup
- Path filtering improves search accuracy significantly
- Mermaid diagrams render in GitHub, Claude, and other Markdown viewers

### Negative
- Current output is verbose in terminal (designed for Markdown rendering)
- Ingestion is synchronous (blocks on Docker container start)
- No streaming output yet

## Files Changed

| File | Purpose |
|------|---------|
| `examples/clew_bot.py` | PR reviewer script |
| `scripts/install_hooks.sh` | Git hook installer |
| `packages/clew-api/src/adapters/qdrant.py` | Path filter support |
| `docker-compose.yml` | Added ingestion service |

## Next Steps

- Stream 4: Consider GitHub Action integration for automated PR comments
- Improve ingestion to be async (non-blocking)
- Add richer terminal output using `rich` tables
