Skip to content

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() in kairos/render/pages.py replaces last_page_fill, and real-layout tests pin it.
  • One definition. kairos.core.documents holds, 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_cuts order.
  • 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, then Tags:, Situation:, Action:, Result: and Source: lines.
  • Import. kairos evidence import replaces 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 list warns 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. When visas.R exists, 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.R exists, the sentence names it, for example the Top Talent Pass in HK.
  • auto writes the sentence only in the first case, so it never fails.
  • state with 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-limit or --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}/documents takes {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_short or failed). 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|md renders 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_dir on the machine where it runs.
  • Storage.
  • Every document of a run gets a row in a new generated_documents table, which holds its status, pages used and options. A cover letter or criteria row holds its content. A resume row holds only tailored_resume_id, because resume text stays in tailored_resumes and is never stored twice.
  • The evidence library is one evidence_libraries row 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_analyses gets a criteria column.
  • LLM services. CoverLetterWriter and CriteriaWriter sit next to Tailor, behind the same LlmClient port.
  • 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:

  1. The evidence library and the profile facts (visas, notice_period), with the config-template check, the allow-list entries and the [tracking] template fix.
  2. kairos generate with the resume and cover letter, pages_used(), the ladder fitter, the 202-and-poll API and the [resume] pages migration.
  3. Selection criteria, with criteria taken from the ad, --criteria-file, --word-limit and --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:

  1. kairos generate sends POST /jobs/{id}/documents.
  2. documents/run.py writes one row per kind and starts a background task per kind.
  3. Each task calls inputs.py, which runs the CriteriaExtractor once if the job has no criteria yet and saves them to jd_analyses.criteria.
  4. The kind's module builds its ladder and calls core.documents.ladder.pick().
  5. To measure a state it uses the writer port (LLM), then fact_check.check(content, corpus), then the kind's HTML module and render.pages.
  6. The resume module reuses tailoring and pdf_fit.
  7. The status, pages used and content go to document_repo.
  8. The CLI polls GET /documents/{id}, then calls export and saves through document_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 in render/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.
  • render knows nothing of LLMs.
  • llm knows nothing of pages.
  • The ladder in core takes 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_client already 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 criteria with --language zh is refused.