diff --git a/docs/intent/srcly-ux-review/candidate-shapes.md b/docs/intent/srcly-ux-review/candidate-shapes.md new file mode 100644 index 00000000..540e1f1f --- /dev/null +++ b/docs/intent/srcly-ux-review/candidate-shapes.md @@ -0,0 +1,36 @@ +--- +title: "Srcly UX review — candidate shapes" +slug: "srcly-ux-review" +phase: intent +status: candidate +last_updated: "2026-11-22" +--- + +# Candidate shapes for review + +These are starting shapes, not implementation authorization. Fix existing trust breaks before adding interpretation. + +```text +Srcly UX review +├── Trust floor +│ ├── Caller-owned effects and truthful uncertainty +│ ├── Shared repository inventory (#440) and supported React demand parity (#441) +│ └── Correct source/target identity through navigation and invalid/empty inputs +├── Question → source +│ ├── Preserve field scope, proof kind and unknowns (#442) +│ └── Search scope, visible actions, narrow viewport and keyboard (#443) +├── Change → evidence +│ ├── Complete changed-file footprint and revision-preserving handoff (#444) +│ └── Responsibility movement and before/after behavior, after the first slice +└── Optional local provenance (#445) + └── Explicit receipts only; unknown is a valid result +``` + +| Workstream | First visible proof | Cut line | +| --- | --- | --- | +| Evidence-first trace | Ask where the title comes from. Show exact carriage and point to the first handoff where only whole-object context is known. Continue honoring a named partial result. | No persistent workspace or general field/path sensitivity first. Distinguish Solid `untrack` initialization and actual subscriptions in a separate proof. | +| Question to source | Find `SearchPage` despite its absence from the loaded graph; land on its source at laptop zoom without losing Back. Expose one high-value source action and label count scope. | Reuse current index and symbols search. No new search backend, layout rewrite or formal conformance claim. | +| Change to evidence | In `f2544ff^..f2544ff`, list all 15 Git paths (11 structurally visible in the study) and carry one omitted model path into same-range Compare and historical source. | No invented metrics, generic quality score, or arbitrary historical tracing first. Keep batch job and responsibility explanation as later slices. | +| Provenance | Given a known local receipt, a mixed human/agent history and a no-receipt control, show only what each source supports. | No publishing logs, no inferred authorship, no second adapter until one can preserve unknowns. | + +**Open decisions for shaping:** vocabulary and scope transitions in traces; whether search fallback is one surface with scopes or explicit separate actions; owner of cross-view revision state; what a receipt can carry without exposing source/session details. The concepts from the study are candidates and not evidence that those interactions already exist. diff --git a/docs/intent/srcly-ux-review/initiative-map.json b/docs/intent/srcly-ux-review/initiative-map.json new file mode 100644 index 00000000..8cc9c217 --- /dev/null +++ b/docs/intent/srcly-ux-review/initiative-map.json @@ -0,0 +1,150 @@ +{ + "schema_version": "0.5.0", + "initiative": { + "title": "Srcly UX review follow-through", + "slug": "srcly-ux-review", + "scale": "program", + "current_phase": "intent", + "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." + }, + "artifacts": { + "intent_brief": { + "path": "intent-brief.md", + "status": "current", + "updated_at": "2026-11-22" + }, + "brainstorm": { + "path": "brainstorm.md", + "status": "not-requested", + "updated_at": null + }, + "shape_brief": { + "path": "shape-brief.md", + "status": "not-created", + "updated_at": null + }, + "implementation_plan": { + "path": "implementation-plan.md", + "status": "not-created", + "updated_at": null + } + }, + "sources": [ + { + "id": "maintainer-intent", + "type": "conversation", + "location": "November 22 maintainer follow-through request (private; not embedded)", + "anchor": "Separate focused bugs from projects that need shaping; land initial intent.", + "authority": "user" + }, + { + "id": "study", + "type": "doc", + "location": "November 22 Srcly UX evaluation package (private; repository-safe synthesis in study-crosswalk.md)", + "anchor": "S01–S20, UX-001–UX-018, R01–R10.", + "authority": "research" + }, + { + "id": "source-pin", + "type": "repo", + "location": "https://github.com/byronwall/srcly/commit/a4d2a8e04b4b4f1a346695c3daa56240e6a57716", + "anchor": "Pinned evaluated development revision.", + "authority": "repo" + }, + { + "id": "triage", + "type": "repo", + "location": "https://github.com/byronwall/srcly/issues/442", + "anchor": "Project scope and acceptance in #440–#446.", + "authority": "repo" + } + ], + "intent": { + "claims": [ + { + "id": "C1", + "type": "decision", + "statement": "Land initial intent and independently verified bug fixes; shape larger projects before implementation.", + "commitment": "explicit", + "importance": "core", + "status": "active", + "time_horizon": "now", + "sources": [ + "maintainer-intent" + ] + }, + { + "id": "C2", + "type": "requirement", + "statement": "Make source identity and evidence limits visible. Preserve unknowns rather than implying false certainty.", + "commitment": "derived", + "importance": "core", + "status": "active", + "time_horizon": "near-term", + "sources": [ + "study", + "source-pin" + ] + }, + { + "id": "C3", + "type": "proposal", + "statement": "Withhold receipt-based provenance, general behavioral comparison and persistent question workspaces from the initial implementation slice.", + "commitment": "tentative", + "importance": "supporting", + "status": "active", + "time_horizon": "later", + "sources": [ + "study", + "triage" + ] + } + ], + "themes": [ + "evidence and scope", + "stable source identity", + "complete change inventory", + "explicit provenance" + ], + "conflicts": [], + "human_questions": [] + }, + "brainstorm": { + "status": "not-requested", + "requested_count": 7, + "options": [], + "selected_option": null + }, + "shape": { + "status": "not-started", + "appetite": null, + "problem": null, + "recommended_shape": null, + "success_moves": [], + "first_proof": null, + "rabbit_holes": [], + "open_decisions": [] + }, + "implementation": { + "status": "not-started", + "repository_snapshot": { + "revision": "a4d2a8e04b4b4f1a346695c3daa56240e6a57716" + }, + "dependencies": [], + "fast_local_loop": null, + "milestones": [], + "cut_line": [], + "open_decisions": [] + }, + "history": [ + { + "date": "2026-11-22", + "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." + } + ] +} diff --git a/docs/intent/srcly-ux-review/intent-brief.md b/docs/intent/srcly-ux-review/intent-brief.md new file mode 100644 index 00000000..bd1e2877 --- /dev/null +++ b/docs/intent/srcly-ux-review/intent-brief.md @@ -0,0 +1,34 @@ +--- +title: "Srcly UX review follow-through" +slug: "srcly-ux-review" +phase: intent +status: current +last_updated: "2026-11-22" +--- + +# Srcly UX review follow-through + +## My read + +A developer can ask a focused question about a repository or a change, reach source-backed evidence, and tell what the evidence does and does not establish. The UX review found that Srcly is especially useful when the graph assembles evidence that would otherwise take several manual searches. Preserve that advantage; don't add another way to make a hairball. + +## What matters most + +Turn the November 22 UX evaluation and its artifacts into coherent work. Fix independently verifiable defects in focused PRs. Capture intent for larger changes, link actionable issues, and let those projects go through the usual shaping process. This intake doesn't approve the speculative redesigns or a release. + +## Boundaries + +The study ran 20 expert walkthroughs at [`a4d2a8e`](https://github.com/byronwall/srcly/commit/a4d2a8e04b4b4f1a346695c3daa56240e6a57716): 3 completed cleanly, 7 with substantial friction, 7 partial, 3 blocked by defects. This is a demanding benchmark, not a user success rate. Keep these distinctions: + +- **Incorrect vs. uncovered:** A caller-owned mutation incorrectly shown as Closed is a correctness defect. A partial trace that names an actual unknown is useful, not necessarily a failure. Reproduce demand/eager disagreement separately. +- **Inventory vs. analysis:** A tracked path can exist even if a view can't structurally analyze it. Don't turn an exclusion, missing metric or unknown receipt into zero or absence. +- **Source identity vs. view:** Repo, ref, side, file and range belong together. Historical source, inline diffs and Back should not move the user into a different interpretation. +- **Measured vs. inferred:** A metric delta, changed-file set or declared coauthor isn't a conclusion about quality, behavioral equivalence or per-line agent authorship. + +## What seems settled + +Preserve the notes input-to-render/save path (S05), generic HOC (S11), async effects and assumptions (S10), hotspot-to-source witnesses (S14), source+Back navigation (S04/S20), and Changes windows, Touched/Net, commit rail, correct diff and In repo selection (S16/S18/S19). Build first proofs around the same small fixture/target and a failing control, not just a more polished picture. No human timing, formal accessibility or performance claim follows from this study. + +## Next step after confirmation + +Land the independently verified fixes when required checks pass. Shape one larger workflow at a time using a concrete before/after proof. The full private source package is intentionally not checked in. The [study crosswalk](study-crosswalk.md) records the finding IDs, public issues and regression witnesses. [Candidate shapes](candidate-shapes.md) outlines starting points, not chosen UI. diff --git a/docs/intent/srcly-ux-review/study-crosswalk.md b/docs/intent/srcly-ux-review/study-crosswalk.md new file mode 100644 index 00000000..f7ca9ebb --- /dev/null +++ b/docs/intent/srcly-ux-review/study-crosswalk.md @@ -0,0 +1,35 @@ +--- +title: "Srcly UX review — implementation intake" +slug: "srcly-ux-review" +phase: intent +status: current +last_updated: "2026-11-22" +--- + +# Implementation intake + +This is a handoff and evidence crosswalk, not a parallel backlog. Use the linked GitHub issues for acceptance/discussion and Product Grid (`pgm/data`, `srcly-backlog`) for open execution tasks when shaped. Follow the existing field-lineage, proof-strength, trace controls, batch-run and alias-resolution nodes rather than recreating them. Update actual PR/issue evidence as it lands; retire planning documents using repo conventions once the work is absorbed. + +| Study finding | Disposition and proof | +| --- | --- | +| UX-001 · P0 | Focused ownership fix; S15/E028: caller-visible alias sort is not Closed, local copy sort is the negative control. Unknown ownership must not assert closure. | +| UX-002 · P1 | [#440](https://github.com/byronwall/srcly/issues/440) repository inventory; S02/S13 / E005/E032: tracked-ignored helper is visible to tree, Imports and Symbols; ignored-untracked and non-code controls. | +| UX-003 · P1 | [#441](https://github.com/byronwall/srcly/issues/441) demand/eager parity; S09: cold callback-to-state/render matches supported eager result; truly unresolved case remains partial. | +| UX-004 · P1 | [#442](https://github.com/byronwall/srcly/issues/442) field precision, scope and evidence; S06/S07/S12: title does not silently acquire tags as exact ancestry. | +| UX-005 · P1 | Focused revision handoff fix; S18/S19 / E043: deleted function opens base source while correct inline diff and open selection survive. Compare is the positive control. | +| UX-006 · P2 | Focused frontier action fix; S12: a synthetic display ID is never sent as a program anchor; failed query is not displayed with stale success data. | +| UX-007 · P2 | [#446](https://github.com/byronwall/srcly/issues/446) repository-state repair; S04/S08: repo/route ownership is explicit; switching roots cannot request an old route or show both empty and error. Keep URL/Back restoration. | +| UX-008/009/010/018 · P2/P3 | [#443](https://github.com/byronwall/srcly/issues/443) search scope, visible actions, keyboard/narrow viewport and counts. Start with existing search and inspector; keep the working 20→92→28 drill-down. | +| UX-011 · P2 | Focused Effects selection/API fix; S08/S09 / E022: no line-zero request when opening the whole file, controlled API validation, valid function positive control. | +| UX-012/013/015 · P2 | [#444](https://github.com/byronwall/srcly/issues/444) complete change footprint first; responsibility and behavioral comparison later. Use the existing batch-run task and Compare backend hooks. | +| UX-014 · P2 | [#442](https://github.com/byronwall/srcly/issues/442) later explicit framework evidence slice; S08: initialization, subscription and timing are different relationships. | +| UX-016 · P2 | [#445](https://github.com/byronwall/srcly/issues/445) receipt-based local provenance; S17/S19: no session/per-edit attribution guessed from a trailer. | +| UX-017 · P3 | Bounded checker feedback improvement; S12: present the actionable failure reason without dumping arbitrary stderr; ignored input is not itself a product failure. | + +## Proof ladder + +1. Reproduce failures on current main and lock in narrow controls. Treat source inspection as distinct from browser/runtime execution. +2. Run applicable engine/client/server checks and browser checks for affected interactions as documented in `AGENTS.md`. Follow survey gate guidance for analysis changes. No release bump or tag. +3. Use S02/S09/S12/S15/S18 as a minimal trust smoke run. Before workflow-wide rollout, rerun relevant tasks with opt-in/absent evidence, keyboard and constrained viewport. Track completion and detours without converting shell runtimes to people’s task times. + +Minimum proof before shape advances: one observable outcome and one falsifying case per issue. Build each slice so it can be reverted without losing existing workflows. Original examples and tiny study fixtures should be reconstructed or derived from public repository sources; do not commit the whole research archive.