From a799a5721024d2ef3d37f3c03c92e51c44de7b79 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sun, 10 May 2026 22:02:00 -0400 Subject: [PATCH] wip spec for contex composition --- ...-10-context-composition-redesign-design.md | 253 ++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-10-context-composition-redesign-design.md diff --git a/docs/superpowers/specs/2026-05-10-context-composition-redesign-design.md b/docs/superpowers/specs/2026-05-10-context-composition-redesign-design.md new file mode 100644 index 0000000..85bbecb --- /dev/null +++ b/docs/superpowers/specs/2026-05-10-context-composition-redesign-design.md @@ -0,0 +1,253 @@ +# Context Composition Redesign Specification + +## Overview + +Redesign Context Composition in Manual Slop to support sophisticated, layered context management for MMA epics and 1:1 agent discussions. The goal is explicit user control over what context an agent receives at varying granularities. + +## Current State + +- Files & Media and Context Composition are coupled (flags sync visually) +- Context Composition inherits from Files & Media automatically +- No view presets, limited slice visualization +- No context preview before sending + +## Design Goals + +1. **Decouple** Files & Media from Context Composition +2. **Context Composition** = curated selection from project whitelist with view modes +3. **File View Presets** = named combinations of sig/def/full/custom for per-file selection +4. **Directory grouping** for compact, scrollable file lists +5. **Slice visualization** with annotation support +6. **Context Presets** = save/load file+view+slices compositions +7. **Context Preview** = show exactly what will be sent to agent + +--- + +## Phase 1: Decoupling + File Stats + View Selection + +### 1.1 Files & Media = Project Whitelist + +**Purpose:** Define what files exist and belong to the project codebase. + +**Behavior:** +- Raw file list with wildcards (existing) +- Does NOT affect Discussion Context directly +- RAG indexing pulls from this list +- Tool access pulls from this list (via tooling permissions) + +**UI:** +- File listing with path display +- Add/remove files +- Wildcard patterns for bulk add +- Rescan project for new files + +### 1.2 Context Composition = Curated Selection + +**Purpose:** Select which files to include in THIS discussion/epic and HOW. + +**Behavior:** +- Independent from Files & Media (decoupled) +- User manually adds files FROM the project whitelist +- Or user adds ALL from whitelist then removes unwanted +- Each file has view mode and optional custom slices + +**View Modes per file:** +- `full` - raw text (no AST pruning) +- `sig` - signature-only outline (basic) +- `def` - definition outline (includes forwards, full AST) +- `custom` - sig/def + user-defined slices with annotations + +**UI Structure:** +``` +[Preset Selector: ▼ Default ▼] [+ New] [💾 Save] [🗑 Delete] + +[Search/Filter files...] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +📁 base/auxiliary/ + ☑ builder.cpp [View: def ▼] [Inspect] [Slices] + ☑ allocator.cpp [View: sig ▼] [Inspect] [Slices] +📁 core/ + ☑ engine.h [View: full ▼] [Inspect] [Slices] +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + +[Stats Panel] +Files: 3 | Lines: 1,247 | AST Elements: 89 +``` + +### 1.3 Directory Grouping + +**Compact display:** +- Files grouped by common relative directory prefix +- Directory header collapsible +- Reduces scrolling, eliminates horizontal scroll +- Format: `📁 relative/path/` + +### 1.4 File Stats + +**Per-file stats display:** +- Line count +- AST element count (functions, classes, structs, etc.) +- View mode indicator + +**Aggregate stats for selection:** +- Total files, total lines, total AST elements +- Helps user decide: "should I just inject full text or curate?" + +--- + +## Phase 2: Slice Visualization + Annotations + +### 2.1 Slice Inspector (replaces Inspect button) + +**Purpose:** Visualize and edit slices for a file. + +**Opens as popup/modal showing:** +- Full file content with line numbers +- AST-derived slices highlighted (sig elements, def elements) +- User custom slices with annotations +- Line range indicators for each slice + +**Slice types:** +- `sig` - AST signature elements +- `def` - AST definition elements +- `custom` - user-defined line ranges with optional tag/comment + +**Annotation support:** +- Each custom slice can have: + - `tag` - category label (e.g., "performance", "bug", "api") + - `comment` - free-text explanation for agent + +### 2.2 View Presets + +**Named combinations of view settings:** +- Preset defines default view mode + default slices for a file type +- Example: "Debug View" = full text + custom slice at error-prone lines +- Example: "API Surface" = sig + custom slices for public API functions + +**Behavior:** +- Select preset for a file → auto-fills view mode + common slices +- User can override after selecting preset +- Presets are project-scoped (saved in project config) + +--- + +## Phase 3: Context Presets + +### 3.1 Save/Load Context Presets + +**Context Preset contains:** +- List of files with: + - Relative path + - View mode (full/sig/def/custom) + - Custom slices with line ranges, tags, comments +- Preset name +- Preset description (optional) + +**Save behavior:** +- Validate all files exist in project +- If file missing: warn user, offer to: + - Save without missing files + - Cancel and resolve manually +- Save to project config (project_context_presets.toml) + +**Load behavior:** +- On preset select, Context Composition populates with saved state +- If file from preset is missing: highlight in red, warn +- User can remove missing or attempt to re-path + +### 3.2 Context Preview + +**Before sending to agent:** +- Show exactly what will be composed +- For each file, show: + - Which view mode applied + - Line ranges included + - Tags/comments visible to agent + - Total token estimate + +**Preview modes:** +- Collapsed (just file list + view modes) +- Expanded (show actual text/slices that will be sent) + +--- + +## Data Models + +### FileViewPreset +```python +@dataclass +class FileViewPreset: + name: str + description: str + view_mode: str # "full" | "sig" | "def" | "custom" + default_slices: list[dict] # [{start_line, end_line, tag, comment}] +``` + +### ContextPreset +```python +@dataclass +class ContextPreset: + name: str + description: str + files: list[ContextFileEntry] + +@dataclass +class ContextFileEntry: + relative_path: str # relative to project root + view_mode: str + custom_slices: list[dict] # [{start_line, end_line, tag, comment}] +``` + +--- + +## UX Flows + +### Adding Files to Context Composition + +1. User clicks "Add Files" in Context Composition +2. File picker shows project whitelist files, grouped by directory +3. User selects files (multi-select supported) +4. Files added with default view mode (configurable) + +### Creating Custom Slice + +1. User clicks [Slices] on a file +2. Slice editor opens showing file content + AST slices +3. User selects line range via click-drag or input +4. User adds tag and/or comment +5. Slice saved to file entry in Context Composition + +### Saving Context Preset + +1. User curates Context Composition +2. Clicks [💾 Save] +3. Dialog: enter preset name + optional description +4. Validation runs - warns if files missing +5. Preset saved to project + +### Loading Context Preset + +1. User selects preset from dropdown +2. Context Composition cleared +3. Files populated from preset +4. Missing files highlighted with warning +5. User resolves or proceeds + +--- + +## Technical Notes + +- All file paths in presets stored as relative to project root +- FileItem model extended with view_mode, custom_slices +- Context Composition panel completely rewired to be independent of Files & Media +- Aggregate functions updated to respect view modes and slices +- Tool access still uses Files & Media whitelist + +--- + +## Out of Scope + +- RAG configuration changes (handled separately) +- Tool preset changes (already exists) +- MMA track creation (handled by track system) +- Agent behavior when given incomplete views (assumes tooling access)