254 lines
7.3 KiB
Markdown
254 lines
7.3 KiB
Markdown
# 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)
|