Skip to content

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_base is 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_completion loads a job and its jd_analyses row and refuses without both (kairos.api.services.tailor_orchestrator).
  • Rows need a job. tailored_resumes.job_id and generated_documents.job_id are NOT NULL foreign keys to jobs, 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._messages sends 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_stream accepts job, but it does not read it.
  • explain_changes reads the same analysis to give each change a reason (kairos.llm.change_reasons).
  • fit_resume_pdf takes 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

  1. 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.
  2. A synthetic job per role. Add Platform.ROLE, like Platform.MANUAL in 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 by role_key, and has to be excluded from every one of those places. A role is not a posting, and every reader of jobs would need to know that.
  3. A role profile as a second tailoring target. A new role_profiles row 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_resumes and generated_documents point at exactly one of the two.
  4. 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 --title and 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. --job alone builds from exactly those jobs. --skill was 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 its label. 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-file is 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. keep and drop lists 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 with kairos roles edit backend-engineer --keep "Kairos" --drop "Wedding site". A job's run takes them as kairos generate JOB --keep TEXT --drop TEXT, stored in the run's options. kairos roles show and kairos generate --preview list 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 the keep and drop lists of section 3, unique on (owner_id, slug). A job's keep and drop live in generated_documents.options, which is JSONB already.
  • tailored_resumes.job_id becomes nullable, and role_profile_id is added with a foreign key to role_profiles. A CHECK requires 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_documents gets the same treatment. A second CHECK allows a row with a role_profile_id only when kind = '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-profiles builds a profile from jobs or from a skill list, and returns 201 with the profile.
  • GET /api/v1/role-profiles and GET /api/v1/role-profiles/{id}.
  • POST /api/v1/role-profiles/{id}/documents returns 202 with one running document, which is then followed with the same GET /documents/{id} and GET /documents/{id}/export as 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, keep and drop winning over the score, and the heading check passing on the selection.
  • TailorTarget from 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: --role and JOB together or neither, and --role with -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).