generated from coulomb/repo-seed
New workplan for sophisticated visual exploration of dependencies
This commit is contained in:
249
workplans/RREG-WP-0010-dependency-visualization-exploration.md
Normal file
249
workplans/RREG-WP-0010-dependency-visualization-exploration.md
Normal file
@@ -0,0 +1,249 @@
|
||||
---
|
||||
id: RREG-WP-0010
|
||||
type: workplan
|
||||
title: "Dependency Visualization And Exploration"
|
||||
domain: capabilities
|
||||
repo: repo-scoping
|
||||
status: active
|
||||
owner: codex
|
||||
topic_slug: foerster-capabilities
|
||||
created: "2026-05-03"
|
||||
updated: "2026-05-03"
|
||||
state_hub_workstream_id: "da974de8-8ef2-4df5-a357-c323f525bb2e"
|
||||
---
|
||||
|
||||
# Dependency Visualization And Exploration
|
||||
|
||||
This workplan deepens the dependency graph visualization introduced in
|
||||
RREG-WP-0008. The goal is to make dependency exploration useful for real
|
||||
curation work: reviewers should be able to inspect graph structure, emphasize
|
||||
or de-emphasize characteristic classes, hide noisy areas, preserve useful
|
||||
perspectives as named view profiles, and understand facts, evidence, features,
|
||||
capabilities, abilities, and scope as distinct layers.
|
||||
|
||||
The current Cytoscape graph is a good first slice: it exposes graph data, full
|
||||
view, impact view, selected-path view, node styling, edge styling, and selection
|
||||
details. The next step is to make it navigable at scale and expressive enough
|
||||
for repeated curator workflows.
|
||||
|
||||
## Feature Model
|
||||
|
||||
The visualization should support three display states:
|
||||
|
||||
- `show`: node or edge is fully visible with normal styling and labels.
|
||||
- `blur`: node or edge remains visible but appears light gray and omits
|
||||
descriptions/labels until hover or selection.
|
||||
- `hide`: node or edge is removed from the active graph view.
|
||||
|
||||
Display states should be produced by a deterministic merge of view profile
|
||||
rules, current mode, and manual overrides. Manual overrides should be reversible
|
||||
and should be savable into a view profile when desired.
|
||||
|
||||
View profiles are named saved exploration perspectives. A profile should be able
|
||||
to hold filter rules, manual node/edge overrides, mode defaults, and optional
|
||||
description text. Profiles should belong to a repository first; later work can
|
||||
decide whether global/shareable profiles are worth adding.
|
||||
|
||||
## Evidence Layer Model
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "65ac4acd-e61c-4211-94b8-142fc93209bc"
|
||||
```
|
||||
|
||||
Refine the dependency graph model so evidence is consistently represented as a
|
||||
layer between facts and features where applicable, rather than appearing only as
|
||||
a sibling input to capabilities.
|
||||
|
||||
Acceptance criteria:
|
||||
- Graph serialization includes stable `layer` metadata for facts, evidence,
|
||||
features, capabilities, abilities, and scope.
|
||||
- Evidence can bridge facts to features and facts to capabilities without losing
|
||||
existing approved evidence semantics.
|
||||
- Existing impact propagation behavior remains compatible with the refined
|
||||
graph.
|
||||
- Documentation explains when evidence points to a feature versus directly to a
|
||||
capability.
|
||||
|
||||
## Layered Layout And Same-Layer Edges
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "e952bf83-efc3-4cb7-8abc-ac7ae00ba8e8"
|
||||
```
|
||||
|
||||
Improve graph layout and edge rendering for layered dependency exploration.
|
||||
|
||||
Acceptance criteria:
|
||||
- Default layout presents layers in order: facts, evidence, features,
|
||||
capabilities, abilities, scope.
|
||||
- Same-layer edges use bent or curved arrows so they are visually distinct from
|
||||
upward dependency arrows.
|
||||
- Same-layer edges remain flagged as normalization signals in both data and UI.
|
||||
- Edge labels/tooltips expose dependency type, strength, and source.
|
||||
|
||||
## Graph Metadata Enrichment
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T03
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "a3929bce-a2e3-4e2d-9c99-e4cc0ad2d325"
|
||||
```
|
||||
|
||||
Enrich graph nodes and edges with the metadata needed for filtering,
|
||||
inspection, and stable profile storage.
|
||||
|
||||
Acceptance criteria:
|
||||
- Nodes expose stable keys, kind, layer, name, description, primary class,
|
||||
attributes, confidence, freshness state, ownership, and source references
|
||||
where available.
|
||||
- Edges expose stable keys, dependency type, strength, source, same-layer flag,
|
||||
freshness/impact state, and source/target metadata.
|
||||
- Fact nodes expose kind, path, name, value, and useful metadata-derived
|
||||
attributes.
|
||||
- Payload remains Cytoscape-compatible and covered by tests.
|
||||
|
||||
## Filter Rule Engine
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T04
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "2d51f5f5-a1e5-48ec-b297-a7376c97445c"
|
||||
```
|
||||
|
||||
Define and implement rule-based graph filtering with `show`, `blur`, and `hide`
|
||||
actions.
|
||||
|
||||
Acceptance criteria:
|
||||
- Rules can match node/edge kind, layer, primary class, attributes, confidence,
|
||||
freshness state, ownership, dependency type, strength, same-layer flag, path,
|
||||
and text search.
|
||||
- Rule precedence is deterministic and documented.
|
||||
- Hide removes elements from the active view; blur keeps elements visible in
|
||||
light gray with labels/descriptions suppressed until hover or selection.
|
||||
- Connected-edge behavior is explicit when a node is hidden or blurred.
|
||||
- Rules can be represented as JSON for persistence and API exchange.
|
||||
|
||||
## Manual Visibility Overrides
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T05
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "320065c7-934d-4350-9a29-3f9cac35a6db"
|
||||
```
|
||||
|
||||
Allow users to manually select nodes and edges and mark them as shown, hidden,
|
||||
or blurred for the current exploration session.
|
||||
|
||||
Acceptance criteria:
|
||||
- Users can apply show, blur, or hide to selected nodes and edges.
|
||||
- Users can reset manual overrides without resetting filter rules.
|
||||
- Manual overrides are distinguishable from rule-derived display states.
|
||||
- Selected hidden items can still be recovered from a profile/editor list.
|
||||
|
||||
## View Profile Persistence
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T06
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "95f2d2e5-b6b1-4ae3-b286-eab228372f2b"
|
||||
```
|
||||
|
||||
Persist named dependency graph view profiles.
|
||||
|
||||
Acceptance criteria:
|
||||
- Repository-scoped profiles can be created, listed, loaded, updated, duplicated,
|
||||
and deleted.
|
||||
- Profiles store name, optional description, default graph mode, filter rules,
|
||||
manual visibility overrides, and timestamps.
|
||||
- Profile storage has migrations and API coverage.
|
||||
- Profiles are stable across app restarts and repository reanalysis unless
|
||||
referenced graph keys disappear, in which case orphaned overrides are surfaced.
|
||||
|
||||
## View Profile UI
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T07
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "5f0f680f-1401-4c55-be27-cf7216efee0b"
|
||||
```
|
||||
|
||||
Expose view profile management in the dependency graph UI.
|
||||
|
||||
Acceptance criteria:
|
||||
- Users can select a profile, save current view as a profile, edit profile name
|
||||
and description, duplicate a profile, and delete a profile.
|
||||
- Filter rules can be edited in a structured UI without requiring raw JSON for
|
||||
common cases.
|
||||
- A profile summary shows active rules, manual overrides, and orphaned
|
||||
references.
|
||||
- URL parameters can open a graph directly with a selected profile.
|
||||
|
||||
## Exploration Interaction Polish
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T08
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "9da7e01a-d192-403a-b217-4dbed6d87892"
|
||||
```
|
||||
|
||||
Improve interactive exploration ergonomics for larger graphs.
|
||||
|
||||
Acceptance criteria:
|
||||
- Hover temporarily reveals blurred labels and descriptions.
|
||||
- Selection side panel distinguishes visible, blurred, hidden-by-rule, and
|
||||
hidden-by-manual-override states.
|
||||
- Users can focus on selected node neighborhoods by depth.
|
||||
- Users can clear focus without losing profile or manual override state.
|
||||
- Empty and over-filtered states explain what happened and how to recover.
|
||||
|
||||
## API And Contract Coverage
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T09
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "4c5f69e7-878e-40a5-8997-277e232a761b"
|
||||
```
|
||||
|
||||
Add stable API support and tests for dependency visualization and profiles.
|
||||
|
||||
Acceptance criteria:
|
||||
- Graph endpoint supports profile selection and optional ad hoc rule payloads or
|
||||
query parameters where appropriate.
|
||||
- Profile CRUD endpoints are documented in OpenAPI.
|
||||
- Contract snapshot tests include profile endpoints.
|
||||
- Service tests cover filter evaluation, rule precedence, and orphaned override
|
||||
behavior.
|
||||
- UI tests cover profile selection, saving, manual overrides, and blur behavior
|
||||
where feasible.
|
||||
|
||||
## Documentation And Examples
|
||||
|
||||
```task
|
||||
id: RREG-WP-0010-T10
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "6524fced-02bf-47df-a808-505fe702d7aa"
|
||||
```
|
||||
|
||||
Document dependency visualization concepts and provide example view profiles.
|
||||
|
||||
Acceptance criteria:
|
||||
- Documentation defines layer, display state, filter rule, manual override, and
|
||||
view profile.
|
||||
- Example profiles include at least: "Scope Impact", "Hide Tooling Noise",
|
||||
"Evidence Audit", and "Same-Layer Normalization Review".
|
||||
- Documentation explains cautions around hiding evidence and interpreting
|
||||
blurred context.
|
||||
- The ADR for Cytoscape remains linked from visualization docs.
|
||||
Reference in New Issue
Block a user