Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/intent/srcly-ux-review/complete-change-inventory.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: "Changes → Compare: keep the whole change in view"
slug: "srcly-ux-review"
phase: shape
status: proposed
last_updated: "2026-11-22"
---

# Changes → Compare: keep the whole change in view

**Scope:** First slice of [#444](https://github.com/byronwall/srcly/issues/444), not implementation approval. A reviewer should answer “what changed, including the data driving the code?” and inspect the relevant revision without re-entering a range or losing their place.

## Starting point

At current main `5c1b671`, the server's Changes payload for the exact committed range [`bb2eb8e… → f2544ff…`](https://github.com/byronwall/srcly/commit/f2544ffc3ed203cb5cb7ec6441cd99450b87c0b1) gives 11 paths in both Touched and Net and a note that four paths were left out. Git gives 15: the missing paths are `engine/models/{library-models.schema,react,solid}.json` and `engine/test/srcly/__snapshots__/library-readers.txt`. Those four account for 397 of 469 additions in this commit; that is line volume, not a measure of importance. The Nov. 22 browser study also saw 15 in Compare; the post-fix check here was the server payload, not a browser rerun. The clearest witness is the new [`react-router/useParams` row](https://github.com/byronwall/srcly/blob/f2544ffc3ed203cb5cb7ec6441cd99450b87c0b1/engine/models/react.json#L352-L356), a declared URL-read origin absent from the parent. This proves a model-table change, not a change in trace behavior.

[#452](https://github.com/byronwall/srcly/pull/452) already opens Changes hunks at their correct repository, revision, side, path and range, including deleted content from its earlier revision. Keep that handoff, its visible revision label and no working-tree fallback. It does not restore the missing paths.

## Pick the path list, not a bigger graph

| Option | Tradeoff |
| --- | --- |
| Expand what the structural map parses | Makes more tiles immediately visible, but mixes an inventory problem with parser coverage, costs more on big repos, and encourages made-up metrics. |
| **Give Changes a complete changed-path list next to the existing map and carry its selected range/path into Compare** | Keeps the map and existing chunks useful while making non-structural changes findable. Requires an inventory contract and a real return-state handoff, not a layout rewrite. |
| Send reviewers to Compare for the missing files | Reuses Compare now but keeps Changes incomplete, loses Touched-only paths in an endpoint diff, and asks reviewers to reconstruct context. |

Recommend the middle option. One always-reachable **Changed paths** list is the discoverable, keyboard-accessible fallback next to the existing map. Present one result per logical path (show both names for a rename) and distinguish **Changed paths** from **Files with structural metrics**. For JSON and other supported text, show a bounded Git diff and exact historical source without generating structural chunks. Binary, mode-only and unreadable paths remain discoverable with the relevant reason, not an empty successful diff or metric zero. Keep existing map filters, chunk counts, commit rail, Only edits/In repo navigation, and source and diff selection behavior.

## Seams and cut line

1. **Inventory and evidence eligibility.** In `server/app/services/changelens/{hunks,chunks,service}.py`, separate Git change facts from which files the analysis reads. Use the resolved Changes window, scope and first-parent policy. Touched follows its actual included commits; Net uses its effective endpoints. Reuse Compare's NUL-delimited Git name/status handling (`server/app/services/compare/git_refs.py`) where semantics match; don't substitute Compare's two-snapshot result for Touched. Feed a separate inventory through the existing payload rather than giving unparsed paths pretend chunks. Do not widen scan enumeration, structural parsing or its size limits. Keep existing payload fields/counters compatible; label any view counts by what they count.
2. **Evidence and return.** For a selected path, distinguish a whole-window diff from one commit on the rail. Carry the repo, actual base/head or effective comparison endpoints, scope, mode, optional commit, old/new paths, selected side/range and stable return selection through Changes → Compare → source → Back. The cross-view input should carry exact refs, not a mutable branch label or the name of the current checkout. Keep Changes as the owner of its return state and reuse #452's source-locator contract at the evidence boundary. Compare is still an endpoint view; if a selected Touched-only edit was reverted, say that it has no endpoint diff and preserve its Changes receipt instead of picking another file.
3. **Coordinate, don't wait unnecessarily.** [#440](https://github.com/byronwall/srcly/issues/440) owns tracked eligibility for a single repository snapshot. Reuse its path normalization, status vocabulary and coverage contract when available; an exact Git change range can prove this slice independently. If it would create competing path identities, agree on a shared seam before merging the second implementation. Keep the existing [Product Grid batch-run task](../../../pgm/data/projects/srcly-backlog/nodes/task-start-the-data-flow-batch-run-from-the-app.md) for an explicit, progress-visible run; do not create a duplicate or require a batch run to see Git paths.

**Not in this slice:** new layout engine, automatic impact or behavioral-equivalence claims, unchanged-neighbor analysis, responsibility-movement scoring, arbitrary historical whole-program tracing, batch-run UX, or agent provenance. Those are separate shapes after this path-to-source proof. Start with reproducible committed ranges. Existing worktree and upstream-merge views must not regress; if an exact comparison endpoint cannot be expressed in Compare today, state why and keep the existing Changes/source path. Don't silently substitute HEAD for a worktree or the effective base tree.

## Acceptance proofs

- **Historical Git oracle:** For the full-repo range above, compare path sets, not just counts, with `git diff --name-status -z -M <base> <head>`. Changes exposes all 15; the four formerly omitted paths have no invented structural score. Use the keyboard to find the React JSON path, see its actual diff and open the head-side `useParams` row at the exact revision/range. Compare receives the same committed range and selection. Close source and go Back: the same Changes window, mode, scroll/selection and prior diff are available.
- **Falsifying control:** Edit one tracked JSON value, then revert it in a second commit. Both commits produce one logical path with two touches; Net excludes it across the pair. From the first commit alone, the real text diff and exact source remain inspectable without structural metrics. From Touched, Compare names the absent endpoint diff and returns to that selection.
- **Boundary controls:** A mode-only change and a binary file both appear, without a fake text hunk; a rename retains old/new identity and opens the correct side. A neighboring path outside a scoped scan does not leak in. An unavailable old blob yields an explicit historical-source error; no working-copy fallback. A shallow, truncated or excluded-upstream baseline must state the relevant scope/limit, not claim complete history.
- **Preserve and measure:** Re-run existing #452 tests, Changes/Compare source and keyboard smoke, and one measured TypeScript chunk. Do not regress chunk, diff, rail, Only edits/In repo or Compare cancel/progress. Inventory should reuse the existing Git work when possible; capture commands, timing and bytes read on the fixture and a larger repo to detect an accidental per-path read or parse. Do not turn shell timings into user-task speed claims.

**Decision needed only if proposed scope expands:** whether to make a mutable worktree or synthetic upstream-adjusted tree a first-class portable Compare endpoint, or place rows without structural metrics on the graph itself. Neither is needed to prove the committed first slice. The recommended default is an explicit unavailable state for unmatched endpoints and a single path list for non-structural rows.
59 changes: 59 additions & 0 deletions docs/intent/srcly-ux-review/evidence-first-trace.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: "Evidence-first trace explanations — workstream shape"
slug: "srcly-ux-review"
phase: shape
status: draft
last_updated: "2026-11-22"
---

# Keep the developer’s question visible

**Outcome:** A developer tracing one field can tell what actually carries its value, where the trace loses that precision, and which source supports each answer.

**Primary flow:** Select `title` in source → ask where it comes from → read a short answer and its first limit → open a witness → return to the same question.

## Feature scope

```text
Evidence-first trace (#442)
├── PLANNED ADDITIONS
│ ├── One question header: selected expression, direction, scope and trace mode
│ ├── Compact answer: proven field steps, the first widening, and named stops
│ └── Expand context/source in place without changing the selected question
├── EVALUATE BEFORE COMMITTING
│ └── Whether one named handoff needs a narrow proof hook beyond existing data
└── LATER POSSIBILITIES
└── Separately prove initialization, ongoing subscriptions and scheduled work
```

## Behavior

| Situation | Expected result |
| --- | --- |
| A path carries the selected field | Put it in the answer only when that field’s identity is supported. Open the particular expression, not just its enclosing function. |
| The path widens to an object or an activation condition | Name the handoff where field precision changes; keep sibling values or activation evidence under expandable **Context**, not **Sources of title**. A useful context step can be proven without being field carriage. |
| An edge depends on a model, an assumption or a missing link | Preserve `proven`, `modelled`, and `assumed` independently of the relationship label. If evidence cannot connect to the next step, stop with a reason, not “no source.” Do not turn budget limits into absence or an old result into a new answer. |
| The question uses a route instead of a source anchor | Label **Selected route origin** or **Source expression**. Route field lineage and its edge witnesses apply within the selected route/origin; anchor traces walk a bounded expression slice. Share words, not guarantees. Switching modes is a new query; do not silently substitute one answer for the other. Source return keeps repository, analyzed generation, span and mode; a changed generation asks for refresh. |

## Examples

**Proposed review artifact, not an observed screen:** One pinned source/answer card using a tiny synthetic title/tags fixture, with the exact selected span and the expandable widening witness.

> **Where does `title` come from?** · Source expression · Backward
> **Proven for `title`:** the argument reads `record.title`. [Open witness]
> **Stops being field-specific:** `record` crossed a resource/component/store handoff. The object path is known; the earlier producer of this field is not proved. [Open handoff]
> **Context (1):** `tags` shares the container; it is not shown to supply this title.

## Decisions and boundaries

**Appetite:** One compact, source-backed explanation on the existing inspector. Keep the full view and its navigation available.

**Key decision:** Start with an inspector projection, not a new graph or a label-only fix. Reuse routeGraph/routePath field witnesses and anchorGraph proofs/stops as available. Build on existing field lineage, [proof strength](../../../pgm/data/projects/srcly-backlog/nodes/task-send-proof-strength-to-the-client-through-the-contract.md) and [graph/ledger agreement](../../../pgm/data/projects/srcly-backlog/nodes/task-ledger-and-graph-agree-on-every-shared-expression.md); don't add parallel tasks. If anchor evidence cannot locate a widening, state where exact proof ends and test one narrow boundary proof before expanding scope.

**Boundary:** No workspace, general field/path sensitivity, graph/ledger redesign or full framework scheduler. A later Solid `untrack` control must show initial value carriage without a live subscription; contrast a genuinely tracked read and a separately scheduled callback. Async Effects remains an independent activation witness, not a subscription claim.

**First proof:** **Try:** replay S06/S07/S12 using a synthetic title/tags fixture; add a positive variant that explicitly derives title from tags and a named-stop control. **Observe:** capture one browser walkthrough and a structured expected/actual table: title provenance, marked widening, clickable source, exact-query return, route/anchor search limits. Preserve S05 input → render and save, S11 generic HOC → heading, and S10 request → await → after-await/timer distinctions. **Decide:** proceed only if incidental tags never appears as exact ancestry, explicit tags-derived title stays discoverable, unknowns remain named, and the positive controls hold. Any false exact claim, lost control or invented witness blocks the slice; prefer a narrower partial explanation over an engine rewrite.

Study anchor: UX-004 and UX-014; source checked at [`5c1b671`](https://github.com/byronwall/srcly/commit/5c1b671355d0f4eb1d75ac25fe3660919219463c), not rerun here.

[Intent](intent-brief.md) · [Study crosswalk](study-crosswalk.md) · [Workstream #442](https://github.com/byronwall/srcly/issues/442)
47 changes: 35 additions & 12 deletions docs/intent/srcly-ux-review/initiative-map.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@
"title": "Srcly UX review follow-through",
"slug": "srcly-ux-review",
"scale": "program",
"current_phase": "intent",
"current_phase": "shape",
"last_updated": "2026-11-22",
"summary": "Preserve source-backed investigation while fixing trust defects and separating analysis scope, revision identity, and provenance.",
"status": "planned",
"next_action": "Verify and land narrow fixes. Shape the linked workflows independently starting with a falsifiable user-visible proof."
"status": "active",
"next_action": "Review the two independent proof-sized shapes. Start with complete Changes inventory and retain the separate trace explanation proof. No broader implementation approval is recorded."
},
"artifacts": {
"intent_brief": {
Expand All @@ -23,8 +23,8 @@
},
"shape_brief": {
"path": "shape-brief.md",
"status": "not-created",
"updated_at": null
"status": "current",
"updated_at": "2026-11-22"
},
"implementation_plan": {
"path": "implementation-plan.md",
Expand Down Expand Up @@ -119,13 +119,30 @@
"selected_option": null
},
"shape": {
"status": "not-started",
"appetite": null,
"problem": null,
"recommended_shape": null,
"success_moves": [],
"first_proof": null,
"rabbit_holes": [],
"status": "current",
"appetite": "Two narrow first slices, each with an exact before/after proof.",
"problem": "Srcly can silently omit changed paths or make context look like exact field ancestry.",
"recommended_shape": {
"primary": "Complete the Git-backed Changes footprint and preserve exact revision identity through source and Back.",
"independent": "Project a compact field evidence summary in the existing trace inspector."
},
"success_moves": [
"Show all 15 changed paths and honest metric gaps on the historical fixture.",
"Open the exact added model row at its head revision and return to the same selection.",
"Keep Touched and Net distinct for a metadata-only edit reverted within the range.",
"Distinguish actual title carriage from incidental tags and keep trace limits visible."
],
"first_proof": {
"question": "Can the tool expose the complete change footprint and explain a focused field trace without losing source identity or inventing evidence?",
"artifact": "Two tiny fixture walkthroughs with an expected/actual table and same-revision source witnesses.",
"decision_rule": "Proceed only when all paths, revision selection, Touched/Net and both title/tags positive and negative controls hold."
},
"rabbit_holes": [
"Unify Changes and Compare into a new workspace",
"Infer quality from complexity deltas",
"Treat subscriptions as the same as value provenance",
"Infer agent attribution or collect receipts in either slice."
],
"open_decisions": []
},
"implementation": {
Expand All @@ -145,6 +162,12 @@
"event": "created",
"phase": "intent",
"note": "Summarized the UX review and mapped findings to independent issues or small PR lanes without pre-approving the candidate shapes."
},
{
"date": "2026-11-22",
"event": "shape-drafted",
"phase": "shape",
"note": "Captured proposed first proofs for #444 and #442. The remaining product choices stay separate and this does not approve broad implementation."
}
]
}
42 changes: 42 additions & 0 deletions docs/intent/srcly-ux-review/shape-brief.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: "Srcly UX review follow-through: inventory and evidence"
slug: "srcly-ux-review"
phase: shape
status: current
last_updated: "2026-11-22"
---

# Make the missing pieces visible

**Outcome:** A developer can tell what changed, reach the exact source, and see what a trace does and does not establish without starting the investigation over.

**Primary flow:** Choose a change range → see the whole Git footprint → open a row at the selected revision → return to the same selection. Separately, ask where a field comes from → see the first place the evidence gets less precise → open its witness and return to the question.

## Feature scope

```text
Two independent, proof-sized workstreams
├── PLANNED ADDITIONS: Changes/Compare
│ ├── Include every Git-changed path, not only structurally analyzed files
│ └── Carry the revision, side, path and selection through source and Back
├── PLANNED ADDITIONS: evidence-first trace
│ ├── Keep the field, direction and trace mode visible
│ └── Separate exact field paths, context, and the first named limit
└── EVALUATE LATER
├── Responsibility movement and behavior comparisons
└── Initialization, live subscriptions, and scheduling evidence
```

## Decisions and boundaries

**Recommendation:** Start with the [complete change inventory shape](complete-change-inventory.md). The historical-source handoff fix [#452](https://github.com/byronwall/srcly/pull/452) is on main, so this can be tested without rebuilding Changes. The [shared source inventory defect](https://github.com/byronwall/srcly/issues/440) is related but is not a prerequisite: the changed-file footprint comes from the selected Git revisions, not the working-tree source inventory.

The [trace explanation shape](evidence-first-trace.md) is independent. Start in the existing inspector. Reuse established proof and edge-witness data; if a mode cannot support a precise explanation, show its limit instead of assigning provenance based on adjacency.

**First proof:** Show one small before/after replay for each slice, with a result table and the exact source witnesses.

- **Try:** On the 15-path historical change, open the added `useParams` model row at the head revision and return to the same row. Separately, trace title through the title/tags fixture and repeat with a variant where tags really do supply title.
- **Observe:** Compare with Git's complete path list and the exact historical revision, then record which title steps actually carry the field, which only supply context, and how the trace explains its first material limit.
- **Decide:** Move a slice to planning only if the positive and negative controls pass. No invisible changed paths, invented metrics, tip-of-branch fallback, false exact lineage, or loss of the existing successful traces. Narrow the question if a proof requires a general engine change.

No broad redesign, new search default, agent data collection, or implementation is approved by this document. The draft UI choices for [#443](https://github.com/byronwall/srcly/issues/443) and [#445](https://github.com/byronwall/srcly/issues/445) stay separate. The [intent](intent-brief.md) and [crosswalk](study-crosswalk.md) retain the full intake.
Loading