Intent-Driven Codebase Understanding for AI-Assisted Developers
ClearCut is a VS Code extension that structures developer-agent interaction so that human judgment is exercised at every step, not bypassed. By representing codebases spatially, ClearCut helps developers rapidly build accurate mental models of AI-generated systems and identify high-risk changes.
The MVP Scope
To validate the core concept of Concentric Consequence Weighting & Spatial Judgment Forcing without premature complexity, the MVP focuses on visual layout transitions and manual tier adjustments. Full AI-driven intent capture is deferred to subsequent phases.
1. Dual Visual Layouts (Implemented & Planned)
Folder Islands (Implemented): The default view where files flock to parent folder clusters to preserve directory hierarchy.
Concentric Intent Rings (Planned): An alternative physics mode arranged in concentric circles representing risk/consequence tiers.
2. Concentric Risk Tiers
Inner Circle (Critical): Core logic, high-consequence files, or files on the current task's critical path.
Middle Circle (Supporting): Supporting utility modules and immediate dependencies of critical path files.
Outer Circle (Cosmetic): Lower-risk, unrelated, or cosmetic files.
3. Mock/Manual Tier Assignment Control
A sidebar control panel allowing the user to select files and manually assign them to a priority tier (Critical, Supporting, or Cosmetic). This simulates the data payload that the AI intent engine will eventually supply.
4. D3 Concentric Layout Transitions
Switch seamlessly between the cluster force-directed layout and the radial concentric circle layout using d3.forceRadial.
Smoothly transition node coordinates and maintain collision repulsion so circles remain readable and non-overlapping.
5. Spatial Judgment Forcing (Drag to Reassign)
The developer can drag nodes between concentric circles.
Repositioning a node explicitly overrides its priority level, providing a physical mechanism for human developer judgment.
Deferrals (Post-MVP Phases)
To ensure rapid validation of the visual and spatial interaction model, the following components are out of scope for the MVP:
AI Intent Capture Engine: Natural language parsing and clarifying conversational loops to automatically map developer intent to a critical path.
MCP Server Interface: Directly piping task context and proposed file changes from AI agents (Cursor, Claude Dev, etc.) into the extension.
Persistent Intent History: Session tracking of file weights across window reloads.
