0008: Application documents: resume, cover letter and selection criteria in page ranges¶
- Date: 2026-11-10
- Status: proposed
Problem¶
Kairos tailors a resume (decision 0004) but writes nothing else an application needs.
The cover letter and selection criteria for the Geely role (job 5683ec14) were written
by hand in a chat. The evidence came from reading two repositories, because the resume
holds only a fraction of it. Three things that run was missing:
- Facts that are checked. Nothing checked the evidence, and several items in it were wrong or unverified. One document said "4 regions" when there are three plus a demo; two documents disagree on whether there are 48 or 49 endpoints.
- Page lengths that are enforced. Every length was a guess.
- A single source for repeated facts. Each document repeated the visa position and the contact details. There were placeholders in four places.
The owner wants one command that writes any of the three documents within these page ranges:
- a cover letter or selection criteria response: from half a page to one page;
- a one-page resume: from half a page to one page;
- a two-page resume: from one and a half pages to two pages.
Research: how selection criteria are answered in Australia¶
| Practice | What the sources say |
|---|---|
| Structure | STAR (situation, task, action, result) is the default. CAR (context, action, result) and SAO are shorter forms of it. Give one example per criterion, and end with the result. JobAccess; Australian Embassy, Jordan |
| First sentence | A claim that you meet the criterion, in the criterion's own words. Cover every part of the criterion. emb |
| Length | A limit in the ad is followed exactly; 100, 150 or 200 words per criterion are common. Without a limit, write 2–3 paragraphs or about 250 words, and never more than one A4 page per criterion. ja; Careerfaqs |
| Layout | The criterion is the heading and the answer sits under it. Paragraphs are short, with bullets only where they help. ja |
| Essential and desirable | Every essential criterion must be answered: a panel cannot recommend a candidate who misses one. Careerfaqs |
| Newer formats | Some APS agencies ask for a statement of claims instead. The National Archives caps it at 1,000 words and suggests building it on 3–4 capabilities. A one-page, 750-word "pitch" appears only on a mirror site and is unverified. |
| Common mistakes | Answering only part of a criterion, making a claim without evidence, leaving out the result, and vague language. emb |
The JobAccess and embassy pages were read in full. The APSC and NSW PSC pages could not be fetched (a timeout and a 403); points that only they make are left out.
The owner's rule is one page at most, and that holds even when an ad lists the criteria. One page fits about 600 words, while the sources suggest about 250 words a criterion, so both cannot be met. Kairos keeps the page rule and makes each answer shorter: a one-sentence claim, then CAR. When the essential criteria cannot all fit on one page at the minimum length (70 words each, see 2), it reports an error. It does not drop a criterion.
Choice¶
1. The command¶
kairos generate JOB writes the resume by default. -d/--doc picks the documents and
can be repeated; --all writes all three.
Usage: kairos generate [OPTIONS] JOB
Write application documents for a job from your base resume and evidence library:
a tailored resume (default), a cover letter, a selection criteria response, or all
three. Every number and name must come from your own material or the job ad; one
that does not fails the checks. Each document is fitted to its page range; one that
cannot be fitted is not written, and the command exits 3.
JOB is a job id or its first characters. The job is analysed first if it has not been.
Page ranges (A4, measured on the rendered page):
resume --pages 1 0.5 - 1 page
resume --pages 2 1.5 - 2 pages
cover letter 0.5 - 1 page
selection criteria 0.5 - 1 page
Arguments:
JOB Job id or prefix [required]
Documents:
-d, --doc [resume|cover-letter|criteria|all]
Document to write; repeatable [default: resume]
-a, --all Same as --doc all
Resume:
--pages [1|2] [default: the API's [resume] pages]
--intensity [light|standard|strong]
[default: the API's [resume] intensity]
--from-tailored ID Reuse a tailored resume instead of tailoring again
Cover letter:
--to TEXT Addressee, e.g. "Vicky Q., Overseas Recruiting Manager"
[default: Hiring Manager]
Selection criteria:
--criteria-file PATH The ad's criteria, one per line; "(desirable)" marks a
desirable one. Without it they are read from the ad
--max-criteria INTEGER When read from the ad [default: 5; 3-8]
--word-limit INTEGER Words per criterion set by the ad, followed exactly;
lifts the half-page minimum, never the one-page
maximum [50-500]
--char-limit INTEGER Characters per criterion set by an online form; same
rule [200-5000]
Content:
--language [en|zh] [default: the API's [resume] language, else the base
resume's]
--note TEXT A fact of yours to work in, e.g. "referred by Lin Tang";
repeatable
--work-rights [auto|state|omit]
auto states it when the job's region is in
[profile.fit] needs_sponsorship_in; state needs a
visa held in that region [default: auto]
Output:
-f, --format [pdf|md] Repeatable [default: pdf]
-o, --out DIR [default: this machine's [documents] out_dir/
<company>-<role>/]
--preview Print the text; write no files
--force Write over an earlier run's files
Exit status:
0 every document written within its range
1 error: API, LLM, job not found, a missing profile fact
3 a document could not be fitted; the others were still written
kairos evidence import FILE and kairos evidence list manage the evidence library.
2. Page ranges¶
- What is measured. Pages used = (pages − 1) + the last page's fill. Fill is how far
down the page's content box the lowest line reaches, divided by the content box's
height. In WeasyPrint the page box's height is already the content height, so a full
page reads about 0.99 and half a page about 0.5.
pages_used()inkairos/render/pages.pyreplaceslast_page_fill, and real-layout tests pin it. - One definition.
kairos.core.documentsholds, as data: - the document kinds;
- each kind's range in pages used (resume 1: 0.5–1.0; resume 2: 1.5–2.0; letter and criteria: 0.5–1.0);
- the minimum and maximum words per criterion (70 and 130).
The CLI's choices and help text, the API's validation, the fitter and the generated
CLI reference all read it. Nothing restates a number.
- Retired keys. [resume] max_pages and [resume] min_last_page_fill are retired,
and [resume] pages (1 or 2) replaces them. A config validator moves the old values
across, the way _move_legacy_llm_settings does:
- a max_pages of 1 or 2 is kept;
- 3 or 4 becomes 2, with a warning;
- min_last_page_fill is dropped, with a warning.
PageBudget(max_pages, min_last_page_fill) becomes PageRange(min, max) in pages
used. The "cut a barely used last page" step of decision 0004 is removed; a page range
takes its place. Files that change: core/config.py (model and template),
render/__init__.py, render/pdf_fit.py, tests/test_render/test_page_fit.py,
docs/guide/tailor.md and skills/kairos/SKILL.md.
3. Formats¶
All three documents use kairos/render/themes/default.css and the same header (name and
contact line), which is parsed from the base resume's preamble by
kairos.core.rendering.header.
- Resume. This is the existing design (decision 0003), cut by the existing
page_cutsorder. - Cover letter (about 280–380 words):
- The header, date, addressee and
Re: <role> (<location>). - An opening: the role, and one reason that is specific to this company, taken from the ad.
- The ad's top 2–3 requirements, each matched to one result with a number.
- Fit.
- Logistics: work rights (see 5), location and notice period.
- A request for a conversation, then the sign-off.
- Selection criteria (about 600 words at most):
- A title and a one-line introduction.
- Per criterion: the criterion as the heading, marked essential or desirable; one sentence claiming it; then CAR, where the result carries a number or a verifiable outcome.
- Essential criteria come first.
- Without
--criteria-file, the criteria are read from the ad's responsibilities and requirements text, not from the skill list (which split Geely's ad into 11 fragments). They are stored on the job's analysis, so the cover letter and the criteria response draw on the same list.
4. Evidence library¶
- The file. The owner keeps a Markdown file of stories. Each story has
## Title, thenTags:,Situation:,Action:,Result:andSource:lines. - Import.
kairos evidence importreplaces the library with the file and records the file's path and SHA-256. The file stays the source; the database copy is never edited.kairos evidence listwarns when the file has changed since it was imported. - Checks on import. Each story must have a
Source:line. A story that holds a host name on an internal domain (.internal,.local,.lan,.corp,.ts.net), a private IP address or an email address is refused, because employer-internal details must not reach a public document. Public domains such as github.com are fine. A currency amount gets a warning, not a refusal: a personal project's own cost, such as US$0.85 a run, is fair to cite, but an employer's prices are not. - The first batch. It is drafted from the Geely run's research. The owner reviews it line by line before import. Items that are not verified (the region count, the endpoint count) are fixed or dropped first.
5. Sources of truth¶
The API runs in Docker on henry-linux; the CLI may run elsewhere. Every fact below is read
on the API's host from the API's config.toml, except out_dir, which belongs to the
machine that writes the files. The CLI sends only the options the user typed. The API fills
in the defaults and returns the values it used, so the CLI never reads its own copy of a
server fact.
| Fact | Owner | Read by |
|---|---|---|
| Name and contact line | Base resume preamble | Header of all three documents. [profile] name stays as the CLI's display name, but kairos generate fails when it is set and differs from the preamble's name, so the two cannot drift |
| Needs sponsorship in a region | [profile.fit] needs_sponsorship_in (exists) |
Fit scoring; the work-rights sentence |
| Visas held | [profile.visas.<CODE>], new: name and optional expires, one per region where the candidate holds a visa or pass (for example AU: subclass 485, to 2027-06; HK: Top Talent Pass) |
The work-rights sentence |
| Notice period | [profile] notice_period, new |
Cover letter |
| Sign-off | [documents] signoff, new (API host) |
Cover letter |
| Output folder | [documents] out_dir, new (the CLI's host) |
File paths |
| Document kinds, page ranges, per-criterion words | kairos.core.documents.kinds |
CLI, API, fitter, CLI reference |
| Words per page per kind | kairos.render.pages, beside the theme it measures |
The fitter's word targets |
| Resume page count | [resume] pages (API host) |
Fitter, and the default when --pages is not given |
| A job's criteria | jd_analyses.criteria, new, derived once |
Criteria response; cover letter |
| Evidence stories | The owner's Markdown file | Library (a replaced copy); generation |
| Allowed facts | One function: the base resume, evidence library, ad text and --to/--note. Numbers may come only from the resume, the library and --note |
Fact check for all three documents |
| Style | themes/default.css |
All three renders |
| Exit statuses | exit_code() beside DocumentStatus in kairos.core.documents.kinds |
CLI exit code; API result per document |
| Export formats, default addressee | DocumentFormat (with its media type) and DEFAULT_ADDRESSEE in kinds |
Export route and service, CLI choices, letter frame |
| Tailoring levels, document languages | Intensity, Language in kairos.core.config |
Config, API requests, CLI help and checks, prompts (one rule set per level, pinned by a test) |
| Option ranges | MaxCriteria, WordLimit, CharLimit in generated_document.py |
API request and DocumentOptions |
The work-rights sentence is generated, never typed, for a job in region R:
- If R is in
needs_sponsorship_in, the sentence says employer sponsorship is needed. Whenvisas.Rexists, it adds the visa held now and its expiry. Holding a temporary visa while needing sponsorship for a new employer is consistent, so nothing has to check one against the other. - If R is not in that list and
visas.Rexists, the sentence names it, for example the Top Talent Pass in HK. autowrites the sentence only in the first case, so it never fails.statewith neither case true is an error that names the missing[profile.visas.R].
New keys go into the config API's allow-list (api/routes/config.py) so they can be set
remotely, and into the config template. A test now fails when a model field is missing
from the template. The [tracking] section from decision 0006 is missing from the
template today and is added in the same change.
6. Fitting loop¶
Each kind has a ladder: a finite list of content states ordered from shortest to longest. The fitter finds, by binary search, the longest state whose pages used are at or below the maximum. It then checks that state against the minimum. Because the order is monotone, the search ends within ⌈log₂(ladder length)⌉ + 1 renders. No pass can overshoot in the other direction, because states are picked, not edited.
| Kind | Ladder (shortest → longest) | Below the minimum at the longest state |
|---|---|---|
| Resume | The existing page_cuts order, read from most cuts to none |
Error: the base resume is too short for this page count |
| Cover letter | The number of evidence paragraphs (2, 3 or 4), then the word target in steps of 10% of a page | Error: add stories that match the ad's top requirements |
| Criteria | Desirable criteria are added one by one, after all essentials; then the words per criterion rise from 70 to 130 in steps of 10 | Error: add stories for the thinnest criteria |
- Above the maximum at the shortest state is an error too. For criteria, the shortest state is every essential criterion at 70 words, and the message gives the computed need: 70 × essentials ÷ words per page, against 1 page.
- Generating a state. The LLM writes each state at its word target, from a fixed set of stories chosen once per document, so the facts do not change between states. The writer caches each state's text, so a state is generated at most once.
- The ad's limits. With
--word-limitor--char-limit, the words per criterion are capped at the limit, and the half-page minimum is lifted, because the ad's rule is followed exactly. The one-page maximum still holds.
The ladders and the in-range check are pure functions, tested without WeasyPrint. CI installs pango, so the real-layout tests run instead of skipping.
--format md writes the fitted text; the page check still runs on the PDF layout, so
WeasyPrint is required either way.
7. Architecture and storage¶
- API.
POST /api/v1/jobs/{id}/documentstakes{kinds, options}and returns 202 with one document id per kind. The documents are written in parallel, as a background task.GET /api/v1/documents/{id}returns a document's status (running,written,too_long,too_shortorfailed). When it is done, it also returns the pages used, the values the API defaulted, the gaps and the claims to prepare.GET /api/v1/documents/{id}/export?format=pdf|mdrenders one document.- The database keeps the fitted content, not files.
- Files. The API may run on another host (it runs in Docker on henry-linux), so the
CLI writes the files: it calls export and saves into
out_diron the machine where it runs. - Storage.
- Every document of a run gets a row in a new
generated_documentstable, which holds its status, pages used and options. A cover letter or criteria row holds its content. A resume row holds onlytailored_resume_id, because resume text stays intailored_resumesand is never stored twice. - The evidence library is one
evidence_librariesrow per owner, with the stories as JSONB. It is a copy that an import replaces whole, so its stories are never queried or edited one by one. jd_analysesgets acriteriacolumn.- LLM services.
CoverLetterWriterandCriteriaWritersit next toTailor, behind the sameLlmClientport. - CLI. It polls each document every few seconds and prints each result as it finishes, then exports and saves the written documents. No HTTP request stays open longer than an ordinary call.
8. Delivery¶
Three pull requests, each one shippable:
- The evidence library and the profile facts (
visas,notice_period), with the config-template check, the allow-list entries and the[tracking]template fix. kairos generatewith the resume and cover letter,pages_used(), the ladder fitter, the 202-and-poll API and the[resume] pagesmigration.- Selection criteria, with criteria taken from the ad,
--criteria-file,--word-limitand--char-limit.
Module layout¶
The layers are those of CLAUDE.md: core has no infrastructure, ports live in
core/interfaces, adapters in llm, render and db, orchestration in
api/services, and the CLI reaches everything through the API. Each new file holds one
concept; (moved) marks code taken out of an existing file so that the new documents
reuse it instead of copying it.
src/kairos/
core/
documents/ one owner for the documents' rules (pure)
kinds.py DocumentKind, PageRange (and its steps), the range per
kind and resume page count, criterion word bounds,
DocumentStatus and exit_code(), DocumentFormat,
DEFAULT_ADDRESSEE
ladder.py Ladder and pick(): binary search for the longest
state within the maximum, then the minimum check
work_rights.py the work-rights sentence from needs_sponsorship_in,
visas and the mode
allowed_facts.py FactCorpus: the terms and numbers a document may use
story_selection.py the evidence story each criterion cites, chosen once
criteria_list.py --criteria-file text -> criteria ("(desirable)" marks)
evidence_parser.py evidence Markdown -> stories, plus the import checks
entities/
evidence.py EvidenceStory, EvidenceLibrary (source path, sha256)
criterion.py Criterion (text, essential)
cover_letter.py LetterFrame (filled from facts), CoverLetterBody
(written), CoverLetterBrief
criteria_response.py CriteriaFrame (filled from facts), CriterionAnswer and
WrittenAnswers (written), CriteriaResponse, CriteriaBrief
generated_document.py GeneratedDocument (row: kind, status, pages, content
or tailored_resume_id), DocumentOptions and the one
home of the option ranges (MaxCriteria, WordLimit,
CharLimit)
interfaces/
evidence_repository.py
document_repository.py
criteria_extractor.py ad text -> criteria (port)
cover_letter_writer.py CoverLetterWriter (port)
criteria_writer.py CriteriaWriter (port)
rendering/header.py (exists) the header parsed from the preamble
config.py ProfileConfig.visas and notice_period, DocumentsConfig,
ResumeConfig.pages and the legacy-key migration
llm/
fact_check.py (moved from validation.py) banned phrases, scope words,
number and term checks against a FactCorpus
validation.py tailoring's section rules, now calling fact_check
criteria_extractor.py CriteriaExtractor
cover_letter_writer.py CoverLetterWriter
criteria_writer.py CriteriaWriter
prompts/
criteria_extraction.py
cover_letter.py
selection_criteria.py
render/
pages.py (moved from pdf_fit.py) layout_html(), pages_used(),
in_print_slot() (the one bound on concurrent renders),
and the letter's calibrated words per page and frame
pages (properties of the CSS, so they live beside it)
header_html.py (moved from resume_html.py) the header block
page_html.py the HTML page shell (lang, title, CSS) all three share
resume_html.py the resume page, calling header_html and page_html
cover_letter_html.py the letter body, calling header_html and page_html
criteria_html.py the criteria body, calling header_html and page_html
document_pdf.py a letter or criteria response -> measured pages or PDF
document_markdown.py the letter and criteria as Markdown (--format md)
pdf_fit.py the resume ladder over page_cuts, using pages and
core.documents.ladder
themes/default.css (exists) gains the letter and criteria classes
db/
models.py EvidenceLibraryModel (stories as JSONB),
GeneratedDocumentModel, JdAnalysisModel.criteria
repositories/
evidence_repo.py
document_repo.py
jd_analysis_repo.py (exists) gains save_criteria
api/
services/
job_analysis.py (moved from routes/analysis.py) analyse and store a job,
shared by the analyze route and a generate run
llm_usage.py one LLM call -> one llm_usage row, shared by fit
scoring, mail sync and documents
documents/
run.py start a run: one row per kind, background tasks,
statuses; at API start, fail the rows a stopped
API left running
outcome.py how one document ended, and the length message
inputs.py gather one run's inputs: job, analysis, criteria,
resume, evidence, corpus, work-rights sentence
resume_doc.py the resume through tailoring and the resume ladder
checked_writing.py one draft -> facts check -> one rewrite -> refuse;
records every LLM call (letter and criteria share it)
dates.py the date line as documents print it
options.py the caller's options, the rest from the API's config
export.py a written document -> PDF or Markdown file; a resume
from the base it was tailored from
cover_letter_doc.py the letter ladder: states, writer, render, pick
criteria_doc.py the criteria ladder: states, writer, render, pick
routes/
documents.py POST /jobs/{id}/documents, GET /documents/{id},
GET /documents/{id}/export (HTTP only)
evidence.py PUT /evidence, GET /evidence
config.py (exists) allow-list gains the new keys
cli/
api_client.py (exists) the one API base URL and request helpers
choices.py a Literal's or enum's values as help text
errors.py an API error printed escaped; call_or_exit and
download_or_exit, shared by every command
document_files.py out_dir and file names on the CLI's machine
commands/
generate.py kairos generate: options, polling, exit codes
evidence.py kairos evidence import | list
alembic/versions/018_create_evidence_libraries.py (PR 1)
alembic/versions/019_create_generated_documents.py (PR 2: and jd_analyses.criteria)
How the pieces call each other:
kairos generatesendsPOST /jobs/{id}/documents.documents/run.pywrites one row per kind and starts a background task per kind.- Each task calls
inputs.py, which runs theCriteriaExtractoronce if the job has no criteria yet and saves them tojd_analyses.criteria. - The kind's module builds its ladder and calls
core.documents.ladder.pick(). - To measure a state it uses the writer port (LLM), then
fact_check.check(content, corpus), then the kind's HTML module andrender.pages. - The resume module reuses tailoring and
pdf_fit. - The status, pages used and content go to
document_repo. - The CLI polls
GET /documents/{id}, then calls export and saves throughdocument_files.py.
What keeps the pieces apart:
- Rules have one home. Ranges, word bounds and statuses live only in
kinds.py; words per page only inrender/pages.py. The CLI help text is built from them, and the CLI reference is generated from the help. - No layer reaches past its neighbour.
renderknows nothing of LLMs.llmknows nothing of pages.- The ladder in
coretakes a measure function and does not know what it measures. - Routes only translate HTTP.
- Nothing is copied.
- The header HTML, fact rules and page measurement each move once, and the resume and new documents share them.
- Shared helpers go in a module of their own rather than into a second command
(
api_clientalready plays that role for HTTP).
Known limits¶
- A number from the ad, such as "2+ years", cannot be quoted, because numbers may come only from the owner's own material. Otherwise a figure from the ad could be passed off as the candidate's.
- The words-per-page constants only set each state's word target. Whether a state fits is decided by measuring its render, so a constant that is off costs extra renders, not a document out of range.
Not in scope¶
- DOCX output.
- Writing to or submitting through an application portal.
- Chinese-style selection criteria. The format is Australian, so
-d criteriawith--language zhis refused.