manual_slop/docs/superpowers/specs/2026-05-10-context-composition-redesign-design.md

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

@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

@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)