0009: Role resumes: a general resume per kind of role¶
- Date: 2026-11-10
- Status: accepted
Problem¶
Every document Kairos writes is for one job. kairos generate JOB tailors the base resume
to that job's analysis, and a cover letter and a selection criteria response name its
company (decision 0008). The owner also needs general resumes, one per kind of role:
a Backend Engineer resume, a Full-stack resume, an AI Engineer resume. These go to
recruiters, referrals and career fairs, where there is no ad to tailor to.
Kairos cannot write one today:
- One base resume.
is_baseis exclusive per owner: marking a resume as the base clears the flag on the others (kairos.db.repositories.resume_repo,set_base). - Tailoring needs a job.
tailor_to_completionloads a job and itsjd_analysesrow and refuses without both (kairos.api.services.tailor_orchestrator). - Rows need a job.
tailored_resumes.job_idandgenerated_documents.job_idareNOT NULLforeign keys tojobs, and a tailored resume is unique on(owner_id, base_resume_id, job_id)(kairos.db.models).
Today the only workaround is to write several resumes by hand and switch which one is the base. That skips the tailoring checks (decision 0004) and the page fitting (decision 0008), and the resumes drift apart as the owner edits one of them.
The owner also wants each of these in English and in Chinese. Language is a separate
axis from role. Country is not an axis for the resume. Resumes are split by language
only ([resume] language, en or zh, decision 0004). A job's country is read only by
the work-rights sentence in a cover letter or a criteria response, and by the refusal of
Chinese criteria (decision 0008). There is one theme, and it has no country-specific
layout.
What tailoring reads from a job¶
Tailoring needs less from a job than the schema suggests:
Tailor._messagessends the model the labels of the analysis's required and preferred skills and the section's text. It sends nothing else from the job (kairos.llm.tailor).tailor_streamacceptsjob, but it does not read it.explain_changesreads the same analysis to give each change a reason (kairos.llm.change_reasons).fit_resume_pdftakes sections, a header and a page count. It does not read the job (kairos.render.html_renderer).
So a resume can be tailored to anything that supplies required skills, preferred skills and keywords. It does not have to be a job.
Options¶
- Several hand-written base resumes. Allow more than one base, and let the user pick one per run. This needs no LLM work. But nothing tailors or checks the extra resumes, and the owner has to maintain each one by hand. That is the drift this decision is meant to remove.
- A synthetic job per role. Add
Platform.ROLE, likePlatform.MANUALin decision 0007, and save "Backend Engineer" as a job with a written description. Everything downstream works without a schema change. But the fake job appears in the job list, gets a fit score, can be given an application status, takes part in the cross-board dedupe byrole_key, and has to be excluded from every one of those places. A role is not a posting, and every reader ofjobswould need to know that. - A role profile as a second tailoring target. A new
role_profilesrow holds a name and the skills a kind of role asks for. Tailoring takes a small target value that either a JD analysis or a role profile can supply.tailored_resumesandgenerated_documentspoint at exactly one of the two. - No tailoring: page-fit the base resume only. Render the base resume in the 1-page or 2-page range with nothing tailored. This is cheap, but it gives the same resume for every role. It fits the owner's need only when there is a single role.
Choice¶
Option 3.
1. Role profiles¶
A role profile has name (for example "Backend Engineer"), a kebab-case slug that is
unique per owner, required_skills, preferred_skills and keywords in the
JdSkill shape, source (jobs or manual), the ids of the jobs it was built from,
and built_at.
A profile can be built in one of two ways:
- From saved jobs (the default). Pick the saved jobs whose title matches
--titleand whose analysis names any--skill(each filter only when given), plus any named with--job(an id or its first characters, repeatable), and keep those that have an analysis.--jobalone builds from exactly those jobs.--skillwas added after the first production run: the 74 open "backend" jobs mixed Java, Go and Python stacks, so no skill reached half of them and the profile had no required skill at all, while the 13 Python ones among them gave Python as required and five preferred skills. Then count each skill by itslabel. A skill becomes required when at least half of those jobs require it. It becomes preferred when it appears in at least a quarter of them. At most 15 skills are kept as required and 10 as preferred, and the most frequent are kept first. Each skill's proficiency is the median of the levels the jobs asked for. This step makes no LLM call. With fewer than 3 matching jobs Kairos refuses, and says how many it found and that--skills-fileis the alternative. - By hand from a TOML file of skills. This is for a role the owner has not collected jobs for.
Rebuilding a profile replaces its skills. Resumes already tailored from it keep the text they were written with.
2. One tailoring target¶
kairos.core gains TailorTarget, which holds the label, required skills, preferred
skills and keywords. JdAnalysis and RoleProfile each convert to it.
Tailor.tailor_stream and explain_changes take a TailorTarget instead of a
JdAnalysis, and the unused job argument is removed. The prompts, the checks, the
retry and the fact check stay the same, so a role resume passes the same checks as a job
resume (decision 0004).
3. Choosing which entries a resume shows¶
A Backend resume and an AI Engineer resume should show different work. Tailoring alone
cannot do that: rule 6 of the tailoring prompt keeps every entry, and _headings_kept
fails a section whose ### headings differ from the base's (kairos.llm.validation).
So the two resumes would hold the same entries in a different order.
A selection step runs before tailoring, for a job's resume and for a role's resume alike,
against the same TailorTarget (section 2): the job's analysis or the role profile. It
decides which entries are shown and never writes text.
- What can be left out. Entries (
###headings) in work experience, internships and projects. The owner chose this, accepting that a role left out leaves a gap in the employment timeline that an interviewer may ask about. - How an entry is scored. The entry's own text is matched against the target's
skills with
kairos.core.skill_evidence, the same name-and-alias matching that reports gaps and coverage (decision 0005). A required skill counts 2 points and a preferred skill 1. No LLM is called, so the same base resume and target always give the same choice. - What is kept. An entry that matches no skill of the target is left out. Floors keep every section filled: at least 2 projects and at least 1 role. If too few entries match, the best-scoring others fill up to the floor, and among equal scores the most recent role goes first. Kept roles stay newest first. Kept projects are ordered by score, most relevant first.
- Length. The resume ladder already cuts whole projects from the bottom, keeping
KEEP_PROJECTS(2), and then trims bullets in older roles (kairos.render.page_cuts, decisions 0004 and 0008). Ordering projects by score makes those cuts fall on the least relevant work. Its last rungs used to cut the projects down to one; that rung is removed, so the floor of 2 holds after fitting too. - The owner's word wins.
keepanddroplists of heading substrings override the score. A kept entry is shown even with no match; a dropped one never is, even if that takes a section under its floor. A role profile stores them, set withkairos roles edit backend-engineer --keep "Kairos" --drop "Wedding site". A job's run takes them askairos generate JOB --keep TEXT --drop TEXT, stored in the run's options.kairos roles showandkairos generate --previewlist every entry with its score and whether it is shown, so the owner can see why before running.
Tailoring then runs on the selected sections. The heading check compares against that
selection, so it still fails a heading that was invented or changed. Every word that
remains still comes from the base resume. The document's detail names each entry left
out and why, for example "left out: Wedding site (no Backend skill)".
4. Schema¶
The change is one migration:
role_profiles, as described in section 1, plus thekeepanddroplists of section 3, unique on(owner_id, slug). A job'skeepanddroplive ingenerated_documents.options, which is JSONB already.tailored_resumes.job_idbecomes nullable, androle_profile_idis added with a foreign key torole_profiles. ACHECKrequires exactly one of the two. A second unique key,(owner_id, base_resume_id, role_profile_id), sits beside the existing(owner_id, base_resume_id, job_id). PostgreSQL treats NULLs as distinct, so each key binds only the rows of its own kind and no partial index is needed.generated_documentsgets the same treatment. A secondCHECKallows a row with arole_profile_idonly whenkind = 'resume'.
Rows that already exist keep their job_id, so no data needs to move.
5. Only the resume is general¶
A cover letter names a company and gives one reason specific to it, and selection criteria answer one ad (decision 0008). Neither has a general form. So with a role profile only the resume can be written, and a request for any other kind is refused with 422.
6. Commands and endpoints¶
kairos roles build "Backend Engineer" [--title TEXT] [--skill NAME]... [--job ID]... [--skills-file FILE]
kairos roles list
kairos roles show backend-engineer
kairos roles edit backend-engineer [--keep TEXT] [--drop TEXT]
kairos generate --role backend-engineer [--pages 1|2] [--intensity ...] [-f pdf]
kairos generate JOB [--keep TEXT]... [--drop TEXT]...
kairos generate takes either a JOB argument or --role, and refuses both or neither.
Every other option keeps its meaning, --language included. The files go to
<out_dir>/role-<slug>-<language>/, next to the per-job <company>-<role>/ folders.
Without --language the CLI cannot know the API's choice, so the folder is
role-<slug>/. A
role therefore has at most one English and one Chinese resume, and each language is a
separate run.
--language is passed to the resume's tailoring for a job's run too. Before this
decision a run's --language reached the cover letter and the criteria response, but
the resume read only [resume] language, so one run could write a Chinese letter beside
an English resume. That bug is fixed on its own, ahead of this decision:
tailor_to_completion takes language, and "" still falls back to the config.
POST /api/v1/role-profilesbuilds a profile from jobs or from a skill list, and returns 201 with the profile.GET /api/v1/role-profilesandGET /api/v1/role-profiles/{id}.POST /api/v1/role-profiles/{id}/documentsreturns 202 with onerunningdocument, which is then followed with the sameGET /documents/{id}andGET /documents/{id}/exportas a job's documents.
7. Tests¶
- Building a profile: thresholds, the caps, the median proficiency, refusing with fewer than 3 jobs, and owner scoping.
- Building a profile from
--title, from--job, and from both. - Selection, for a job's target and a role's: scoring, an unmatched entry left out, the
floors of 2 projects and 1 role, the most recent role first among equal scores,
keepanddropwinning over the score, and the heading check passing on the selection. TailorTargetfrom both sources, and the tailor producing the same messages for an analysis as it does today.- The migration's two
CHECKs and the partial unique indexes, against PostgreSQL. kairos generate:--roleandJOBtogether or neither, and--rolewith-d cover-letter.
Not in scope¶
- A cover letter or selection criteria without a job.
- Tailoring a job's resume starting from a role resume instead of the base. Section 2 makes this possible later; it would change what "base" means in decision 0004.
- Building profiles with an LLM or from postings Kairos has not saved.
- Frontend views. The CLI and the API come first, as they did for decision 0008.
- Country-specific resumes, such as a photo or a personal-details block. Nothing in Kairos models them today, and they would need their own theme.
- Translating the sections tailoring does not touch. Only summary, work experience,
internships, projects and technologies are tailored
(
kairos.core.section_mapping). Education, the header and the section headings stay in the base resume's language. So a Chinese resume built from an English base is partly English. Until a later decision closes this, the owner keeps one base resume in each language and marks the matching one as the base before a run.
Decided by the owner¶
- Work experience and internships are selected like projects, for a job's resume and a role's resume, by the target's skills (section 3).
- A profile can name its jobs by id as well as by title (section 1).
- Every resume keeps at least 2 projects (section 3).
- A skill is required when at least half of a profile's jobs require it, and preferred when at least a quarter mention it; a profile needs at least 3 jobs (section 1).