docs(desktop): plan candidates shortlist v1#203
Merged
Conversation
Reviewer's GuideIntroduces a plan-only specification document for the QuantLab Desktop "Candidates / Shortlist v1" feature, defining entities, persistence format, scope boundaries, UI slice, integration points, and acceptance criteria without changing any runtime code. Sequence diagram for marking a run as candidate and updating local storesequenceDiagram
actor Operator
participant ShellUI
participant RunRegistry
participant CandidatesState
participant LocalStore as LocalJsonStore
Operator->>ShellUI: click Mark_as_candidate on run_id
ShellUI->>RunRegistry: validateRun(run_id)
RunRegistry-->>ShellUI: runExists
alt run exists
ShellUI->>CandidatesState: addCandidate(run_id, note)
CandidatesState->>LocalStore: readStore()
LocalStore-->>CandidatesState: storeJson_or_missing
CandidatesState->>CandidatesState: mergeDefaults_and_updateCandidates
CandidatesState->>LocalStore: writeStore(updatedStoreJson)
LocalStore-->>CandidatesState: write_ok
CandidatesState-->>ShellUI: candidate_added
ShellUI-->>Operator: show_candidate_and_optional_shortlist_badge
else run missing
ShellUI-->>Operator: show_error_run_no_longer_exists
end
Sequence diagram for opening compare from shortlist selectionsequenceDiagram
actor Operator
participant CandidatesTab as CandidatesTabUI
participant CandidatesState
participant RunRegistry
participant CompareView
Operator->>CandidatesTab: select_multiple_shortlisted_runs
Operator->>CandidatesTab: click_Open_compare
CandidatesTab->>CandidatesState: getShortlistSelection()
CandidatesState-->>CandidatesTab: selected_run_ids
CandidatesTab->>RunRegistry: resolveRuns(selected_run_ids)
RunRegistry-->>CandidatesTab: resolved_runs_with_missing_flags
CandidatesTab->>CompareView: openCompare(resolved_runs)
CompareView-->>Operator: show_side_by_side_comparison
ER diagram for Candidates, Shortlist, Baseline, and RunserDiagram
Run {
string run_id PK
}
Candidate {
string run_id FK
string note
datetime added_at
boolean shortlisted
}
Shortlist {
string shortlist_id PK
datetime updated_at
}
ShortlistEntry {
string shortlist_entry_id PK
string shortlist_id FK
string run_id FK
int ordinal
}
Baseline {
string baseline_id PK
string run_id FK
datetime marked_at
}
CandidatesStore {
string schema_version
datetime updated_at
string baseline_run_id
}
Run ||--o{ Candidate : has_candidates
Run ||--o{ ShortlistEntry : may_appear_in
Run ||--o{ Baseline : may_be
Shortlist ||--o{ ShortlistEntry : ordered_entries
CandidatesStore ||--o{ Candidate : persists
CandidatesStore ||--o{ Shortlist : persists
CandidatesStore ||--o{ Baseline : persists
Class diagram for planned candidates shortlist data structuresclassDiagram
class CandidateRecord {
string run_id
string note
datetime added_at
boolean shortlisted
}
class CandidatesStoreData {
string schema_version
datetime updated_at
string baseline_run_id
CandidateRecord[] candidates
}
class CandidatesStoreHelpers {
+CandidatesStoreData readStore(string file_path)
+void writeStore(string file_path, CandidatesStoreData data)
+CandidatesStoreData normalizeDefaults(CandidatesStoreData data)
+CandidatesStoreData guardMissingFile(string file_path)
}
class ShellCandidatesState {
+CandidatesStoreData store
+void loadFromDisk(string file_path)
+void addCandidate(string run_id, string note)
+void removeCandidate(string run_id)
+void toggleShortlist(string run_id, boolean shortlisted)
+void setBaseline(string run_id)
+CandidateRecord[] getCandidates()
+CandidateRecord[] getShortlist()
}
class RunRegistry {
+boolean runExists(string run_id)
+object getRun(string run_id)
}
class CandidatesTabUI {
+void showSummary(int total_candidates, int shortlist_count, string baseline_run_id)
+void showCandidates(CandidateRecord[] candidates)
+void onMarkCandidate(string run_id, string note)
+void onToggleShortlist(string run_id)
+void onSetBaseline(string run_id)
+void onOpenCompare(string[] run_ids)
+void onOpenArtifacts(string run_id)
}
CandidatesStoreHelpers --> CandidatesStoreData : reads_writes
ShellCandidatesState --> CandidatesStoreHelpers : uses
ShellCandidatesState --> CandidatesStoreData : manages
ShellCandidatesState --> RunRegistry : validates_run_ids
CandidatesTabUI --> ShellCandidatesState : interacts_with
RunRegistry <.. CandidatesTabUI : opens_runs_from_registry
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The
Shortlistentity is defined as an ordered list ofrun_ids, but the persistence example uses ashortlisted: trueflag on candidates with no explicit ordering; consider aligning the spec by either adding an orderedshortlistarray in the JSON or removing the ordering requirement. - The
Baselineentity requiresrun_idandmarked_at, but the JSON shape only includesbaseline_run_id; clarify whethermarked_atis needed in v1 and, if so, add it to the persistence example for consistency. - You mention that candidates should only apply to runs that exist in the current registry and that missing runs should be shown explicitly; it may help to specify in the plan how missing candidates are represented in the UI (e.g., a dedicated status or section) to avoid ad-hoc implementations later.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The `Shortlist` entity is defined as an ordered list of `run_id`s, but the persistence example uses a `shortlisted: true` flag on candidates with no explicit ordering; consider aligning the spec by either adding an ordered `shortlist` array in the JSON or removing the ordering requirement.
- The `Baseline` entity requires `run_id` and `marked_at`, but the JSON shape only includes `baseline_run_id`; clarify whether `marked_at` is needed in v1 and, if so, add it to the persistence example for consistency.
- You mention that candidates should only apply to runs that exist in the current registry and that missing runs should be shown explicitly; it may help to specify in the plan how missing candidates are represented in the UI (e.g., a dedicated status or section) to avoid ad-hoc implementations later.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR:
Candidates / Shortlist v1underdocs/desktop-candidates-shortlist-v1.mdlaunch -> inspect -> compare -> decideWhy
This slice matters because:
#196, we needed a clear contract for entities, persistence, UI shape, acceptance criteria, and non-goalsScope
This PR does not:
Validation
Validated with:
git show --stat e65196fdocs/desktop-candidates-shortlist-v1.mdNotes
plan-onlyPR.#196by fixing the scope before code is written.outputs/desktop/candidates_shortlist.jsonand explicitly leaves Stepbit out of this first version.Related to #196
Summary by Sourcery
Document the initial plan for a minimal Candidates / Shortlist decision layer in QuantLab Desktop, defining its scope, entities, persistence model, UI surface, and integration points without implementing any code changes.
Documentation: