Résumé generation flows

The generator has evolved from one model writing an entire résumé to a structured pipeline in which models still make the judgment calls, but code owns identity, attribution, ordering, and document assembly. This page maps the generation flows currently implemented in resume-lambda, with special attention to where deterministic processing replaces prompt compliance.

This is deliberately a generation-architecture view. It leaves out deployment, job execution, batching, and caching.

The progression at a glance

Direct and prose-first flows

V1: single-pass generation

1. ModelGenerate résuméCandidate history + job description + full format prompt
2. CodeSanitize outputStrip fences, tool scaffolding, and leading chatter
3. CodeLintRecord structural and candidate-history defects

V1 is the baseline. One request chooses the content, writes the prose, and emits Power Markdown. Code trims provider scaffolding and checks the result, but it does not constrain the model through an intermediate evidence representation.

V2 alpha and gamma: plan, then compose

1. ModelStrategy + evidenceAnalyze the role and decide what candidate evidence matters
2. ModelComposeWrite the résumé from the intermediate artifacts
3. CodeNormalize + lintRepair mechanics and check blocking structure

Alpha established the two-stage split. Gamma keeps that topology but restores stronger writing rules: write rather than transcribe the evidence notes, vary which facet of recurring flagship work leads, avoid worn canonical phrases, and keep titles defensible. The gated gamma flow then runs the same deterministic format checks used elsewhere.

The V2 beta family explores alternate control structures around prose-first composition:

• Single stage: the direct baseline with the newer compose contract.
• Generator–critic: compose, score the résumé, and revise until accepted or the retry cap is reached.
• Cyclic serial: critique strategy, then evidence, then the résumé; rejected planning stages regenerate upstream artifacts.
• Parallel custom: collect evidence from role-alignment, technical-depth, and risk-gap perspectives; compose once; then run truthfulness, tailoring, and writing revisions before reconciliation.

These flows can improve a model-authored draft, but critics and revisers still operate on prose or prose-like artifacts. They do not create a hard provenance boundary.

Decomposed V3 flows

V3 changes the unit of planning. Instead of asking one strategist to solve the whole job description, it decomposes the role into independently searchable desired attributes and runs an evidence miner for each.

1. ModelDecompose JDRole-level picture plus desired attributes
2. ModelMine per attributeOne evidence branch for each requirement
3. ModelWinnowDeduplicate and select a global evidence plan
4. ModelCompose MarkdownWrite the complete Power-Markdown document
5. CodeFormat gate + lintNormalize mechanics and detect blocking defects

The standard V3 graph uses all four model stages. The fused variant combines winnowing and composition into one final call. The veracity-checked variant inserts a claim audit after composition and before the format guardrails. That audit is observational—it records whether the draft's claims are supported, but it is itself a model judgment rather than a deterministic proof.

Structured V3: models write, code assembles

The structured graphs keep V3's job decomposition and per-attribute search, but replace free-form evidence and document generation with canonical records and validated JSON.

1. CodeNormalize sourcesStable source references and canonical identity
2. ModelDecompose JDRanked requirements and narrative strategy
3. Model + codeExtract passagesExact quotes, then source-span validation
4. Model + codeSelect evidenceChoose IDs, then materialize immutable records
5. CodeAssemble planCanonical role containers and ordering
6. ModelRewriteCited summary, context, bullets, skills, and functional titles
7. CodeValidate + renderCanonical metadata and Power Markdown
8. CodeNormalize + lintFinal deterministic guardrails

There are three structured variants:

• Structured budgeted (main/15) caps extraction, uses a model to select immutable evidence IDs, and targets a bounded résumé.
• Structured retain-all (main/16) keeps every validated, placeable evidence record and skips the model winnow.
• V3 beta (main/19) uses the budgeted structured flow but gives the rewrite stage gamma's stronger compose guidance. The model still returns JSON prose and evidence-backed parenthetical titles; it never owns the roster or final markup.

What the deterministic path actually does

“Structured” does not mean the model has no discretion. It means model discretion is confined to typed, cited fields that code can reject or safely render.

1. Build a canonical source catalog

Candidate YAML is parsed into records with stable references such as experience[0], projects[2], and education[1]. Code preserves the original ordinal and canonical display identity—actual title, employer, dates, location, project name, or credential. Roles at the same company remain separate records.

2. Validate exact evidence

An evidence miner names a source field and returns one to three exact excerpts. Code resolves each excerpt back to the canonical source text, tolerating whitespace-only formatting differences but rejecting paraphrases, unknown references, wrong source types, invalid project-to-role destinations, and conflicting parent assignments.

Accepted evidence receives a stable ID derived from its source, destination, field offsets, and text. If multiple miners find the same passage, code deduplicates it and merges the attributes it supports.

3. Materialize selection by ID

In the budgeted flow, the selector can choose evidence IDs, coverage, and a recommended level of detail. It cannot rewrite the evidence. Code looks up every selected ID in the canonical catalog, rejects unknown or duplicate IDs, and carries forward the immutable source spans and destination role.

The retain-all flow makes this decision deterministically: every validated, placeable record is kept, direct and adjacent evidence are bucketed by strength, and unplaced evidence is omitted.

4. Assemble canonical role containers

Code groups retained evidence under its validated destination role. The included role set therefore follows selected evidence, not a model-generated roster. Each container receives canonical metadata from the source catalog, and the role list is sorted by the source ordinal. Education candidates are built the same way.

Before the writing call, the full source catalog is reduced to a writer plan containing only the selected evidence, role identities, role-specific directives, job strategy, and length target. Unselected narrative is not available for opportunistic mining.

5. Constrain and validate the rewrite

The writer returns JSON containing:

• a cited summary;
• exactly one object for each supplied role;
• an evidence-backed parenthetical functional title for each role;
• cited role context and bullets;
• cited skills; and
• selected education references.

Validation rejects missing, duplicated, or invented roles; unknown evidence; evidence moved between jobs; uncited titles or context; evidence reused across bullets; unsupported skills; and invalid or omitted required education. The validator then restores canonical role and education order regardless of the order returned by the model.

6. Render canonical metadata in code

The renderer writes the header, sections, experience containers, skill markup, and education markup. Actual titles, employers, dates, locations, contact data, and section structure come from the canonical plan. Only validated prose and the cited parenthetical title come from the model. Authored text is flattened to plain text and HTML-escaped before insertion.

7. Normalize and lint the result

The normalizer performs mechanical repairs: removing code fences and preambles, reconstructing a missing header from canonical candidate data, standardizing headings and bullet markers, fixing common Power-Markdown punctuation, balancing indentation, and closing a final missing div when safe.

The format gate checks defects that mechanical rewriting cannot safely infer, including an empty document, unbalanced containers, unresolved placeholders, missing employment history, missing role titles or dates, a missing header or contact block, and missing required sections. Model-authored flows may receive one narrowly scoped format-repair pass. Structured flows do not: once code renders the document, a failed gate proceeds to lint as a visible defect rather than handing canonical markup back to a model.

Decision ownership

Registered generation versions

Back to the Résumé Generator overview