jedarden/FABRIC
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add 10 intelligence features with mockups

Browse source 
1. Stuck & Loop Detection - catch spinning workers
2. Live Inline Diff View - see actual code changes
3. Cross-Reference Hyperlinking - navigate by clicking entities
4. Worker Collision Detection - prevent conflicts early
5. Session Replay - scrub through past sessions
6. Smart Error Grouping - contextualized error analysis
7. Command Palette (Ctrl+K) - universal search/command interface
8. Cost & Token Tracking - budget awareness and projections
9. Task Dependency DAG - visualize task relationships
10. File Activity Heatmap - see where work is happening

Updated implementation phases to include all features.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jeda 2026-03-02 02:43:37 +00:00
parent 9f14a6b226
commit 42e8cb9226
1 changed files with 508 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

513
docs/plan.md
View file

@ -253,6 +253,487 @@ Features:
└─────────────────────────────────────────────────────────────────────────────────┘
```
## Intelligence Features
FABRIC goes beyond simple log display with these intelligent features:
### 1. Stuck & Loop Detection
Automatically detect when a worker is spinning its wheels:
- No meaningful progress for N minutes
- Repeating the same tool calls (Read → Edit → Read → Edit on same file)
- Retrying failed operations repeatedly
Surfaces problems immediately without users having to watch logs constantly.
```
┌─────────────────────────────────────────────────────────────────────┐
│ ⚠️ STUCK DETECTED │
│ │
│ w-alpha appears stuck (same file edited 4x in 6 minutes) │
│ │
│ Pattern detected: │
│ 14:31:07 Edit src/auth.ts → "add validation" │
│ 14:33:12 Edit src/auth.ts → "fix validation" │
│ 14:35:18 Edit src/auth.ts → "update validation" │
│ 14:37:24 Edit src/auth.ts → "refactor validation" │
│ │
│ Suggestion: Worker may be in a fix-break cycle │
│ [Inspect] │
└─────────────────────────────────────────────────────────────────────┘
```
**Loop Detection Patterns:**
- Same file edited 3+ times in 5 minutes
- Same Grep/Glob pattern executed repeatedly
- Alternating Read/Edit on same file without progress
- Retry count exceeding threshold
---
### 2. Live Inline Diff View
When a worker calls `Edit`, render the actual diff inline with syntax highlighting:
```
14:32:07 w-alpha INFO Edit src/auth/login.ts
┌─────────────────────────────────────────────────────────────────────┐
│ @@ -12,7 +12,9 @@ │
│ │
│ import { User } from './types'; │
│ │
│ - function login() { │
│ + async function login(): Promise<User> { │
│ const user = await authenticate(); │
│ - return user; │
│ + if (!user) throw new AuthError('Invalid credentials'); │
│ + return sanitizeUser(user); │
│ } │
└─────────────────────────────────────────────────────────────────────┘
```
**Implementation:**
- Parse `old_string` and `new_string` from Edit tool call logs
- Generate unified diff format
- Syntax highlight based on file extension
- Collapsible in log stream, expandable on click
---
### 3. Cross-Reference Hyperlinking
Every entity in logs becomes a clickable/navigable link:
| Entity | Action |
|--------|--------|
| Bead ID (`bd-1847`) | Show all events across all workers for this bead |
| File path (`src/auth.ts`) | Show all operations on this file |
| Worker name (`w-alpha`) | Jump to worker detail view |
| Timestamp | Anchor link for sharing/bookmarking |
| Error code | Show all occurrences of this error |
```
Activity Stream
┌─────────────────────────────────────────────────────────────────────┐
│ 14:32:07 [w-alpha] INFO Edit [src/auth/login.ts] for [bd-1847] │
│ ───────── ──── ─────────────────── ───────── │
│ clickable tool clickable clickable │
│ │
│ Clicking bd-1847 shows: │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ All events for bd-1847 "Implement auth flow" │ │
│ │ │ │
│ │ 14:29:00 w-alpha Assigned task │ │
│ │ 14:29:05 w-alpha Glob **/*.ts │ │
│ │ 14:30:12 w-alpha Read src/auth/types.ts │ │
│ │ 14:31:47 w-alpha Read src/auth/login.ts │ │
│ │ 14:32:07 w-alpha Edit src/auth/login.ts │ │
│ │ ... │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
**TUI:** Tab/Enter to follow links, Backspace to go back
**Web:** Standard hyperlinks with browser history
---
### 4. Worker Collision Detection
Real-time detection when workers operate on overlapping concerns:
```
┌─────────────────────────────────────────────────────────────────────┐
│ ⚡ COLLISION DETECTED │
│ │
│ w-alpha and w-bravo are both modifying: │
│ │
│ ┌───────────────────┬──────────────────┬──────────────────┐ │
│ │ File │ w-alpha │ w-bravo │ │
│ ├───────────────────┼──────────────────┼──────────────────┤ │
│ │ src/auth/login.ts │ Edit (line 45) │ Edit (line 52) │ │
│ │ src/auth/types.ts │ Read │ Edit (line 12) │ │
│ │ src/api/routes.ts │ - │ Edit (line 88) │ │
│ └───────────────────┴──────────────────┴──────────────────┘ │
│ │
│ Risk: Merge conflicts, duplicated work │
│ Duration: Overlapping for 2m 34s │
│ │
│ [View w-alpha] [View w-bravo] [View Diff] [Dismiss] │
└─────────────────────────────────────────────────────────────────────┘
```
**Detection Logic:**
- Track file → worker mapping in memory
- Alert when same file has Edit from multiple workers within time window
- Severity levels: Read/Read (info), Read/Edit (warn), Edit/Edit (critical)
---
### 5. Session Replay
Record sessions and play them back with timeline scrubbing:
```
┌─ FABRIC REPLAY ─────────────────────────────────────────────────────┐
│ │
│ Session: 2026-03-02_14-20-00 (duration: 25m 34s) │
│ │
│ ◀◀ ◀ ▶▶ ▶▶▶ ━━━━━━━━━━━━━●━━━━━━━━━━━━━━━━━━━ [2x] │
│ rew play pause ff ↑ speed │
│ 14:32:07 │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Workers at 14:32:07 │ │
│ │ │ │
│ │ ● w-alpha Running bd-1847 (2m 34s elapsed) │ │
│ │ ● w-bravo Running bd-1852 (1m 12s elapsed) │ │
│ │ ○ w-charlie Idle - (completed bd-1845) │ │
│ │ ● w-delta Starting bd-1849 (just assigned) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Events at this moment: │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ▶ 14:32:07 w-alpha Edit src/auth/login.ts │ │
│ │ 14:32:05 w-bravo Read src/validators/index.ts │ │
│ │ 14:32:04 w-delta Starting task bd-1849 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ [j/k] Frame step [Space] Play/Pause [←/→] Seek [q] Exit │
└─────────────────────────────────────────────────────────────────────┘
```
**Features:**
- Playback speeds: 0.5x, 1x, 2x, 5x, 10x
- Click timeline to jump to any point
- Frame-by-frame stepping (j/k or arrow keys)
- Keyboard shortcuts for common actions
- Export replay as shareable link or file
**Implementation:**
- Events are already timestamped in logs
- Replay = render events progressively based on timestamps
- No additional storage needed
---
### 6. Smart Error Grouping
Don't scatter errors through the log stream. Group and contextualize them:
```
┌─ Errors (3 unique, 5 total) ───────────────────────────────────────┐
│ │
│ ┌─ API Rate Limit ──────────────────────────────────────────────┐ │
│ │ Occurrences: 2 │ │
│ │ Workers: w-alpha, w-bravo │ │
│ │ First: 14:31:07 Last: 14:31:12 (5s span) │ │
│ │ │ │
│ │ Context: │ │
│ │ Both workers were making parallel Grep calls during │ │
│ │ search phase. Hit rate limit on Anthropic API. │ │
│ │ │ │
│ │ Similar past error: 2026-03-01 09:15 │ │
│ │ Resolution: Added 500ms delay between API calls │ │
│ │ │ │
│ │ [View Events] [View Context] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ FileNotFoundError ───────────────────────────────────────────┐ │
│ │ Occurrences: 2 │ │
│ │ Workers: w-charlie │ │
│ │ File: src/legacy/old-utils.ts │ │
│ │ │ │
│ │ Context: │ │
│ │ File was deleted by w-alpha 2m before this error. │ │
│ │ w-charlie's task bd-1845 had stale file reference. │ │
│ │ │ │
│ │ [View Events] [View Context] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ TypeScript Compile Error ────────────────────────────────────┐ │
│ │ Occurrences: 1 │ │
│ │ Worker: w-delta │ │
│ │ File: src/api/handlers.ts:47 │ │
│ │ │ │
│ │ Error: Property 'userId' does not exist on type 'Request' │ │
│ │ │ │
│ │ Context: │ │
│ │ Edit at 14:30:22 changed Request type definition │ │
│ │ but handlers.ts wasn't updated to match. │ │
│ │ │ │
│ │ [View Events] [View Context] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
**Features:**
- Group by error signature (type + message pattern)
- Show occurrence count and time span
- Auto-detect likely cause from preceding events
- Link to similar past errors (if pattern matching enabled)
- One-click to see full stack trace and surrounding context
---
### 7. Command Palette (Ctrl+K / Cmd+K)
Universal search and command interface:
```
┌─────────────────────────────────────────────────────────────────────┐
│ > auth login_ │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Files │
│ 📄 src/auth/login.ts (18 operations) │
│ 📄 src/auth/login.test.ts (4 operations) │
│ │
│ Beads │
│ 📋 bd-1847 "Implement auth login flow" │
│ 📋 bd-1823 "Fix login validation bug" │
│ │
│ Log entries │
│ 14:32:07 w-alpha Edit src/auth/login.ts │
│ 14:31:47 w-alpha Read src/auth/login.ts │
│ 14:28:12 w-bravo Grep "login" in src/ │
│ │
│ Commands │
│ 🔧 Filter: Show only login-related events │
│ 🔧 Jump to first mention of "login" │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
**Available Commands:**
| Command | Description |
|---------|-------------|
| `>worker alpha` | Jump to w-alpha detail view |
| `>bead 1847` | Show all events for bd-1847 |
| `>file auth.ts` | Show all operations on matching files |
| `>errors` | Jump to error panel |
| `>filter level:error` | Filter to errors only |
| `>filter worker:alpha` | Filter to one worker |
| `>filter last:5m` | Filter to last 5 minutes |
| `>goto 14:30` | Jump to timestamp |
| `>theme dark` | Switch color theme |
| `>replay` | Enter replay mode |
| `>export` | Export current view |
**Features:**
- Fuzzy matching on all inputs
- Recent commands history
- Keyboard-first (arrow keys to navigate, Enter to select)
- Context-aware suggestions
---
### 8. Cost & Token Tracking
Real-time visibility into API usage:
```
┌─ Cost Dashboard ────────────────────────────────────────────────────┐
│ │
│ Session Cost $4.23 / $50.00 daily budget │
│ ████████░░░░░░░░░░░░░░░░░░░░░░░░ 8.5% │
│ │
│ ┌─ Per Worker (this session) ──────────────────────────────────┐ │
│ │ │ │
│ │ w-alpha $1.82 ████████████████░░░░░░░░ ~68k tokens │ │
│ │ ├─ Input: 52k tokens ($0.78) │ │
│ │ └─ Output: 16k tokens ($1.04) │ │
│ │ │ │
│ │ w-bravo $1.15 ██████████░░░░░░░░░░░░░░ ~43k tokens │ │
│ │ ├─ Input: 35k tokens ($0.53) │ │
│ │ └─ Output: 8k tokens ($0.62) │ │
│ │ │ │
│ │ w-charlie $0.78 ███████░░░░░░░░░░░░░░░░░ ~29k tokens │ │
│ │ w-delta $0.48 ████░░░░░░░░░░░░░░░░░░░░ ~18k tokens │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ Per Task ───────────────────────────────────────────────────┐ │
│ │ │ │
│ │ bd-1847 "Implement auth flow" $1.82 (in progress) │ │
│ │ bd-1852 "Fix login validation" $1.15 (in progress) │ │
│ │ bd-1845 "Add user profile endpoint" $0.78 (completed) │ │
│ │ bd-1849 "Add unit tests" $0.48 (in progress) │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ Rate: ~$0.12/min (last 5 min avg) │
│ Projected session total: $8.40 (at current rate) │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
**Features:**
- Real-time token counting from NEEDLE logs
- Cost calculation based on model pricing
- Budget alerts (warning at 80%, critical at 95%)
- Per-worker and per-task breakdowns
- Burn rate and projection
**Budget Alert:**
```
┌─────────────────────────────────────────────────────────────────────┐
│ ⚠️ BUDGET WARNING │
│ │
│ Daily budget 80% consumed ($40.12 / $50.00) │
│ Current burn rate: $0.45/min │
│ Time until budget exhausted: ~22 minutes │
│ │
│ Top consumers: │
│ w-alpha (bd-1847): $12.34 - complex implementation task │
│ w-bravo (bd-1852): $8.92 - debugging loop detected │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
### 9. Task Dependency DAG
Visual directed graph showing task relationships:
```
┌─ Task Dependencies ─────────────────────────────────────────────────┐
│ │
│ ┌──────────────┐ │
│ │ bd-1840 │ │
│ │ Setup DB │ │
│ │ ✅ Complete │ │
│ └──────┬───────┘ │
│ │ │
│ ┌────────┴────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ bd-1847 │ │ bd-1848 │ │
│ │ Auth API │ │ User API │ │
│ │ ● Running │ │ ◌ Blocked │ ← blocked by bd-1847 │
│ │ w-alpha │ │ │ │
│ └──────┬───────┘ └──────────────┘ │
│ │ │ │
│ │ │ │
│ ▼ │ │
│ ┌──────────────┐ │ │
│ │ bd-1849 │◄────────┘ │
│ │ Unit Tests │ │
│ │ ● Running │ │
│ │ w-delta │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ bd-1852 │ │
│ │ Integration │ │
│ │ ○ Pending │ │
│ └──────────────┘ │
│ │
│ Legend: ✅ Complete ● Running ◌ Blocked ○ Pending │
│ │
│ Critical path: bd-1840 → bd-1847 → bd-1849 → bd-1852 │
│ Estimated completion: 12 min (based on similar tasks) │
│ │
│ [Click any node to view details] │
└─────────────────────────────────────────────────────────────────────┘
```
**Features:**
- Visual DAG layout (auto-arranged or manual)
- Color-coded by status
- Click nodes to navigate to task details
- Critical path highlighting
- Blocked task explanation on hover
- Zoom and pan for large graphs
**Web version** uses interactive SVG/Canvas with:
- Drag to pan
- Scroll to zoom
- Click to select
- Hover for details
---
### 10. File Activity Heatmap
Visual representation of where work is happening:
```
┌─ File Activity (last 30 min) ───────────────────────────────────────┐
│ │
│ src/ Operations │
│ ├── auth/ 🔥 Hot zone │
│ │ ├── login.ts ████████████████████████████░░ 28 │
│ │ ├── types.ts ██████████████████░░░░░░░░░░░░ 18 │
│ │ ├── middleware.ts ████████░░░░░░░░░░░░░░░░░░░░░░ 8 │
│ │ └── utils.ts ████░░░░░░░░░░░░░░░░░░░░░░░░░░ 4 │
│ │ │
│ ├── api/ │
│ │ ├── routes.ts ██████████████░░░░░░░░░░░░░░░░ 14 │
│ │ ├── handlers.ts ██████████░░░░░░░░░░░░░░░░░░░░ 10 │
│ │ └── middleware.ts ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 2 │
│ │ │
│ ├── utils/ │
│ │ └── validation.ts ████████████░░░░░░░░░░░░░░░░░░ 12 │
│ │ │
│ └── tests/ │
│ ├── auth.test.ts ██████░░░░░░░░░░░░░░░░░░░░░░░░ 6 │
│ └── api.test.ts ████░░░░░░░░░░░░░░░░░░░░░░░░░░ 4 │
│ │
│ ───────────────────────────────────────────────────────────────── │
│ │
│ Hotspots: │
│ 🔥 src/auth/login.ts 28 ops (w-alpha: 22, w-bravo: 6) │
│ 🔥 src/auth/types.ts 18 ops (w-alpha: 18) │
│ │
│ Unexpected activity: │
│ ⚠️ src/config/db.ts Modified outside of db-related task │
│ │
│ [Click any file to see operations] │
└─────────────────────────────────────────────────────────────────────┘
```
**Features:**
- Tree view matching project structure
- Heat coloring (gray → yellow → orange → red)
- Operation counts per file
- Per-worker breakdown on hover/expand
- Hotspot summary
- Anomaly detection (unexpected files being touched)
- Click to see all operations on that file
**Web version** can use:
- Treemap visualization (rectangles sized by activity)
- Interactive file tree with expandable nodes
- Time-lapse animation showing activity over time
---
## CLI Interface
```bash
@ -300,18 +781,39 @@ fabric logs --worker w-abc123 # Filter by worker
- [ ] Log tailer that watches `~/.needle/logs/`
- [ ] JSON line parser
- [ ] Event emitter for parsed events
- [ ] In-memory event index (by worker, bead, file, timestamp)
### Phase 2: TUI Display
- [ ] Worker list panel
- [ ] Live log stream panel
- [ ] Worker detail panel
- [ ] Keyboard controls and filtering
- [ ] Command palette (Ctrl+K)
### Phase 3: Web Display
- [ ] HTTP server with WebSocket support
- [ ] Real-time event streaming to browser
- [ ] React/Svelte dashboard UI
- [ ] Worker cards and activity feed
- [ ] Command palette (Cmd+K)
### Phase 4: Intelligence Features (Core)
- [ ] Cross-reference hyperlinking (bead, file, worker links)
- [ ] Inline diff view for Edit tool calls
- [ ] File activity heatmap
- [ ] Cost & token tracking dashboard
### Phase 5: Intelligence Features (Detection)
- [ ] Stuck detection (no progress timeout)
- [ ] Loop detection (repeated actions on same file)
- [ ] Worker collision detection (overlapping file edits)
- [ ] Smart error grouping with context
### Phase 6: Advanced Features
- [ ] Session replay with timeline scrubbing
- [ ] Task dependency DAG visualization
- [ ] Budget alerts and projections
- [ ] Anomaly detection (unexpected file activity)
## Technology Options
@ -347,12 +849,13 @@ fabric logs --follow
## Non-Goals
- ❌ Static report generation
- ❌ Storing metrics or historical data
- ❌ Database or persistence layer
- ❌ Alerting system
- ❌ Static report generation (FABRIC is live, not batch)
- ❌ Persistent storage (all state is in-memory, derived from logs)
- ❌ External database (logs are the source of truth)
- ❌ Push notifications (alerts are in-UI only)
- ❌ Worker control (FABRIC is read-only, cannot stop/start workers)
FABRIC is a live display. It shows what NEEDLE is doing right now.
FABRIC is a live display with intelligence. It shows what NEEDLE is doing, detects problems, and helps you understand your workers.
---