0014: The owner picks a run's entries and stories¶
- Date: 2026-11-11
- Status: accepted
Problem¶
Entry selection (decision 0009) shows a role or project when its text shows the
target's skills, and story selection (decision 0008) gives each criterion the story
that shares the most words with it. Both are word counts. The owner often knows better:
a project that names no skill of the ad but is the best story for it, or a story that
matches on words but the wrong way. Today the only way to say so is to look at
kairos roles show, which covers role profiles but not a job, and then guess
--keep / --drop substrings. Stories cannot be chosen at all.
Kioku's retired resume pipeline paused a run, offered the candidate achievements, and
continued with the ones picked (proposal.py at ed10449cb151). An answer naming
something that was not offered was refused, so nothing invented reached the writing
step. Kairos borrows the idea, not the LangGraph pause: a Kairos run is started by one
request and is not resumed.
Options¶
- Pause inside the run. Store the run as waiting, have the CLI answer, resume. This needs a new document status, a resume endpoint, and a timeout for an answer that never comes.
- Ask before the run. The CLI asks the API for the candidates, the owner ticks them, and the CLI starts an ordinary run with the choice in its options.
- Pick through
--keep/--drop. Turn the ticks into heading substrings. A heading that is part of another ("Kairos" and "Kairos v2") cannot be dropped without dropping both.
Choice¶
Option 2, with the choice stored as exact headings and titles.
kairos generate JOB --pick. The CLI first callsPOST /api/v1/jobs/{id}/documents/candidateswith the same body as the run. It reads the run's inputs the way the run does (gather: the job's analysis and criteria, stored for the run to reuse, the base resume and stories after decision 0013's exclusions). It returns:- every role and project with its score, whether it would be shown, and why, after
--keep/--drop; - when the run writes a cover letter or a criteria response, every evidence story with its score: the most words it shares with any one criterion, and that criterion.
- Ticking. The CLI prints both lists numbered and asks for the numbers to use
(
1,3-5,none). Pressing Enter takes the proposal: the shown entries, and the stories with a score above 0. No new dependency; a plain prompt works in any terminal. - The run. The choice is stored in the run's options as
entries(exact headings) andstories(exact titles): - an entry is shown when it was ticked and only then, with the reason "picked by you";
- the floors (2 projects, 1 role) do not apply, because the owner's word wins, as
with
--drop; - story selection and the fact corpus see only the ticked stories, so a letter can neither cite nor state a fact from an unticked one.
A heading or title that is not in the base resume or the library (it was renamed, or
is excluded by decision 0013) fails the run with a 409 that names it. Nothing is
silently dropped.
- Unchanged without --pick. entries and stories default to None, meaning
"choose by score" as before. --pick is refused with --role (kairos roles edit
stores a role's choice) and with --from-tailored (that resume's entries are already
chosen).
Not in scope¶
- Picking in the web UI. The endpoint is there for it, and the CLI comes first.
- Choosing which story answers which criterion. Ticking narrows the stories; matching them to criteria stays with story selection.