wip spec for contex composition
This commit is contained in:
@@ -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)
|
||||
Reference in New Issue
Block a user