From 42e8cb9226381ae98d8d87eccdf6e740cdfaa9e4 Mon Sep 17 00:00:00 2001 From: jeda Date: Mon, 2 Mar 2026 02:43:37 +0000 Subject: [PATCH] docs: add 10 intelligence features with mockups 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 --- docs/plan.md | 513 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 508 insertions(+), 5 deletions(-) diff --git a/docs/plan.md b/docs/plan.md index c6aa512..1be4d11 100644 --- a/docs/plan.md +++ b/docs/plan.md @@ -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 { │ +│ 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. ---