CatLiZi/resume-design-optimizer

Resume Design Optimizer

Create persuasive, concise resumes whose content, visual hierarchy, and exported files remain defensible and reviewable. Match the output language, conventions, and field choices to the target country, organization, and application channel.

Choose the operating mode

• Audit: inspect an existing resume and report content, evidence, positioning, layout, and parsing problems without editing it. Use strict-resume-audit.md for a major or Route B audit.
• Evidence profile: build or update a career profile and evidence ledger from resumes, certificates, repositories, papers, project files, and user-confirmed facts.
• Tailor: analyze a job announcement or JD, check eligibility, select evidence, and produce a role-specific resume.
• Design: compare layouts, select or derive from a bundled template, and create an editable HTML resume or academic CV.
• Validate: render the final document, inspect every page, and check text extraction, fields, fonts, and claim consistency.
• Interview: generate role-specific questions and evidence-grounded answers from the final resume.

Keep analysis-only requests read-only. Modify files only when the user asks to create, update, or integrate materials. Never submit applications, log in to recruitment systems, send messages, or upload personal materials without separate explicit authorization.

Start every resume engagement

For a new resume, a major refresh, or an unclear first request, read onboarding-and-lifecycle.md and use its maintained state flow.

Inspect the current conversation, attachments, and named local paths before asking questions. If the user has not stated a route and no resume context exists, first ask whether they want:

1. to build a resume from zero; or
2. to audit, update, and rebuild an existing resume.

Skip this question when the answer is already clear. If an existing resume is supplied, preserve the original, complete a strict content-and-layout audit before rewriting, and clarify whether the need is polishing, refreshing stale content, retargeting, redesigning, or a combination. If building from zero, establish the target, recommend templates, and collect evidence one section at a time instead of sending a long questionnaire.

Ask in small consequential batches, summarize newly confirmed facts, and do not request information already available. For a reusable engagement, offer a local career workspace and initialize it only in an authorized location with scripts/init_career_workspace.py; choose from-zero or existing-resume, require --adopt-existing for an uninitialized non-empty directory, and keep facts as the source of truth while HTML/PDF resumes remain versioned derivatives.

Every completed resume must go through at least one complete evidence-bound assertive packaging cycle containing all six passes in onboarding-and-lifecycle.md. Repeat the complete cycle when strong evidence remains undersold, the target fit is weak, the page is underfilled, or interview-defense risk remains. For ordinary Route A/B design work, default to editable HTML and the PDF generated from that exact HTML; a user-requested or mandatory official format overrides this default and must be validated in its actual source/export pair.

Define the audience and target

Determine the resume language and writing system, country or region, industry, role family, seniority, application channel, page size, page limit, photo policy, density, and whether the deliverable is an industry resume, academic CV, public-sector resume, or official application form. Use design-profiles.md to record these choices. Requirements from the target organization override conventions and defaults.

Use general-track-profiles.md when the target benefits from a reusable profile. General profiles include:

1. general-professional
2. software-engineering
3. data-ai
4. research-academic
5. public-regulated
6. finance-risk
7. product-creative
8. custom

Profiles are selection heuristics, not eligibility rules. Derive a custom evidence-to-requirement map when none fits.

For mainland China computer-science and technology candidates, an optional market overlay provides more specific routing:

1. bigtech-algorithm: machine learning, large-model, embodied AI, and algorithm roles.
2. bigtech-ai-app: AI applications, RAG, agents, multimodal products, and AI engineering.
3. yunnan-state-owned: Yunnan power, tobacco, public-sector, and other state-owned technology or information roles.
4. bank-tech: bank software, data, security, and financial-technology roles.
5. research-institute: domestic PhD applications, research positions, and research engineering.
6. custom: any role or resume type not covered above.

Read track-profiles.md only when this mainland-China overlay is relevant. Do not use one universal resume with only the employer name changed.

China campus and hard-gate ordering

For mainland China campus hiring, early-career technical roles, and any target where school, degree, major, graduation date, or rank is an explicit screening gate, education is the first factual section below the header and any compact qualification strip. Put it before internships, projects, research, skills, and honors. Do not move education to the bottom merely to imitate an experienced-hire resume.

Use this default hierarchy unless a user-provided or official format overrides it:

header -> education -> core internship / work -> core research or project -> skills -> selected honors / public work

For a candidate with a particularly strong university, degree, GPA, rank, or graduation eligibility signal, surface the strongest relevant qualification in the education line itself. Keep degree facts exact; do not use education as decorative filler.

When multiple education entries use the same fields, align institution, separator, major, degree, and dates through one shared semantic column system rather than manual spaces or per-line offsets. Preserve a natural text and DOM reading order, and allow deliberate wrapping when a long field cannot fit without clipping. Keep career-wide qualifications outside the final school entry: language tests, work authorization, location or availability, and any user-authorized affiliation or status belong in a separate profile or qualification row unless the institution actually issued them.

Build an evidence profile

Use career-profile-template.en.md or career-profile-template.md, according to the internal working language, together with evidence-ledger-template.csv when the user has no structured source of truth.

1. Collect education, experience, projects, research, papers, patents, competitions, skills, and constraints.
2. Ask only for consequential missing facts not already present in local materials.
3. Mine local repositories with read-only commands such as git log, git show --stat, and rg; do not checkout, commit, push, or change Git configuration.
4. Assign stable evidence IDs and apply evidence-and-claims.md.
5. Keep verified-artifact, user-confirmed, inferred, and missing distinct.

Treat exact titles, organizations, dates, degree status, paper status, author order, deployment state, denominators, and metrics as factual locks. User-confirmed participation may support strong wording, but do not silently convert team work into sole ownership.

Position and write

Read positioning-and-packaging.md for aggressive but defensible framing.

For a new draft or major redesign, also read evidence-hierarchy-and-first-screen.md. Before writing bullets or filling a template:

1. identify the target's hard screening gates;
2. choose one to three anchor stories that should define the candidate;
3. admit supporting projects, skills, honors, and links only when they add a distinct useful signal; and
4. archive duplicated, generic, weak, or distracting material instead of forcing it onto the page.

Treat the resume as a ranked evidence argument, not an inventory. Work performed inside an employer or research project normally stays inside that experience unless a separate entry has distinct ownership, artifacts, and value; do not duplicate one contribution as both work experience and a personal project. A dedicated skills or public-work section is optional, not mandatory.

When editing education, language, internship, project, or research details, read education-experience-and-research-details.md. Keep every course, score, rank, language result, role, and research status attached to the institution or artifact that produced it. Prefer concrete contribution bullets over transition narratives about learning, becoming familiar with a process, or moving from one phase to another.

For repeated one-page refinement, competing project choices, semantic title repair, line-budget decisions, or late-stage spacing adjustments, read iterative-content-and-layout-refinement.md. Freeze an accepted baseline, give anchor and supporting evidence different depth, and run versioned micro-revisions rather than accumulating unrelated local patches.

• Translate real actions into technical mechanisms, system capability, business or research value, evidence, and personal scope.
• Remove self-diminishing wording such as “only learned,” “small request,” or “just assisted” when stronger verified verbs are available.
• For important experience, distinguish a conservative version, an assertive version, and an after-evidence version.
• Do not turn reading into implementation, a demo into production, a team result into a personal result, or a planned task into completed work.
• Keep strong bullets answerable under follow-up: action, decision, alternative, validation, failure, scope, and evidence.

Analyze a JD or announcement

Separate hard eligibility requirements, core responsibilities, must-have capabilities, preferred capabilities, and application logistics. Output requirement -> candidate evidence -> status -> gap -> next action.

Use official-source-policy.md for current recruitment facts. Do not produce a false overall match score when eligibility is unresolved.

Design with bundled HTML templates

When the user asks to browse, compare, create, or adapt resume designs, read design-profiles.md and html-template-catalog.md. Bundled templates live in assets/html-templates/.

Open the bundled HTML template gallery.

打开模板画廊。

For every new resume or major redesign, explicitly select one bundled template or name the closest template from which the design is derived before authoring. Record any deliberate change to page size, page count, language, photo policy, density, section order, or column structure. A user-provided reference or an official employer template overrides the bundled gallery. For minor wording-only edits, preserve the existing layout unless the user requests redesign.

• When showing templates, keep all content fictional or placeholder-only. Never insert user data into a template preview.
• Copy a selected template to the user’s output directory before filling it. Never edit the bundled master asset in place.
• Preserve the template’s visual system unless the user requests a change.
• Treat the bundled masters as compact, one-page A4 starting points—not as universal format requirements. Use the page size and page limit required by the target; if neither is specified, choose a locale-appropriate default and state it.
• For mainland China campus and early-career technical derivatives, move the education block directly below the header or impact strip before filling experience and project sections; the Signal Tech and Classic Professional masters demonstrate this education-first order.
• Keep selectable text, semantic HTML, real lists, and a natural source order in every derivative.
• Use a single-column template for maximum parser stability. Use a sidebar template only when the user knowingly prefers stronger visual separation.
• Bundled masters include an optional 25 × 33 mm PHOTO placeholder so photo-using applications can be previewed. Insert a real image only with explicit authorization. Remove the slot when photos are discouraged, prohibited, irrelevant, or not requested; do not reserve blank photo space in the final document.
• Treat an authorized portrait as part of the header geometry, not as an overlay. Respect the source aspect ratio, never stretch the image, and use a square or portrait crop only with the user's approval. Compare left and right placement when either is viable; then reflow the name, positioning line, contact block, and any impact strip so the portrait does not create a detached blank band. Recheck header gaps, occupancy, overflow, and the exported PDF after every photo change.
• Do not use school logos, company logos, QR codes, skill progress bars, or decorative icons unless the user explicitly requests them.
• Keep screen controls outside the printable page and hide them in print CSS.
• Treat an impact or qualification strip as an optional first-screen index. If used, every card must follow the same semantic grammar: a named product, system, responsibility, or research object on the first line, followed by its concrete scope, mechanism, or contextualized result. Do not mix a product name, a generic technology category, and an isolated metric as peer cards. Every card must map to evidence expanded later in the resume and must not introduce a new claim.

For a non-destructive starting copy, use:

python3 scripts/new_resume.py \
  --template <template-id> \
  --output <new-resume.html> \
  --locale <language-tag> \
  --photo <keep-or-remove>

The helper refuses to overwrite an existing file. It copies only a bundled compact-a4 master; other page sizes or multi-page designs still require a declared derivative and fresh validation.

For an ordinary compact one-page resume, target roughly 8–12 substantive bullets and body text no smaller than 9 pt. Adapt the word, character, and line budget to the output language and typeface; do not use a Chinese character count as an English word-count rule or vice versa.

For the bundled compact-a4 masters and their final populated one-page derivatives, meaningful visible content should end between 92% and 97% of the page height. Measure the actual finished resume after its latest content, photo, font, and spacing change—not only the untouched master. A result below 92% is still an underfilled draft unless the user or target format explicitly chose a balanced or sparse profile. A result below 85% is a hard layout failure for a compact one-page resume. This is a profile-specific regression target, not a universal resume rule. For balanced, spacious, Letter, official-form, or multi-page outputs, use the target-specific acceptance criteria in design-profiles.md.

An explicit user preference or official format may define a custom compact density contract. Record its minimum, maximum, rationale, and legibility floor; do not silently replace the bundled 92%–97% default or reuse one user's high-density choice as a universal rule. Custom density still requires zero scroll overflow, visible bottom clearance, and current render/text QA.

When a compact page is underfilled, improve it in this order:

1. Restore or add the most relevant verified experience, project, research, honor, or skill evidence that was omitted for space.
2. Strengthen thin bullets with real mechanism, scope, decision, validation, and outcome details already supported by the evidence profile.
3. Add a genuinely useful section such as selected coursework, publications, certifications, leadership, open source, or professional activity only when it helps the target reader.
4. Rebalance section spacing, line height, heading rhythm, header layout, and margins while keeping body text legible; reflow the header after removing a photo slot.
5. If the available facts still cannot support a full page, ask for missing high-value evidence or obtain explicit approval for a less-dense profile before delivery.

Never fill space with generic self-evaluation, repeated skills, weakly related coursework, invented metrics, unsupported ownership, hidden text, empty footers, oversized decoration, or meaningless vertical gaps. The goal is a page full of relevant evidence, not merely a visually occupied page.

Create an application workspace

When a reusable role directory is helpful, run:

python3 scripts/new_application.py \
  --root <career-workspace> \
  --company <employer> \
  --role <role> \
  --track <target-track-or-custom> \
  --locale <en-or-zh-CN>

Keep source JD, internal analysis, claim map, interview preparation, and external resume separate. Preserve the original source material.

Run the claim gate

Map every material external claim to one or more evidence IDs:

python3 scripts/check_claim_map.py \
  --ledger <evidence-ledger.csv> \
  --claims <claim-map.csv>

• hard: factual conflict, invented experience, metric, credential, or paper status. Block delivery.
• soft: expanded scope, team-to-personal attribution, or wording that changes meaning. Confirm or downgrade.
• cosmetic: language or formatting changes that preserve meaning.

This gate checks consistency with available evidence; it is not a background check.

Render and validate

Read output-and-qa.md whenever creating HTML, DOCX, or PDF output.

For HTML resumes:

1. Open or render the local HTML in a browser.
2. Check the selected page geometry and compare scrollHeight/clientHeight and scrollWidth/clientWidth to detect overflow.
3. Apply the selected density profile to the final populated document. Require 92%–97% vertical occupancy for bundled compact-a4 masters and derivatives that retain that profile, or the explicitly recorded range for a user-approved custom derivative; do not deliver an underfilled compact draft merely because it is technically one page.
4. Export with print backgrounds enabled and browser headers/footers disabled.
5. Render every PDF page to an image and inspect clipping, overlap, font rendering for the target writing system, whitespace, hierarchy, and any authorized photo.
6. Confirm exactly one page when the user requires a one-page resume.
7. Extract text and verify names, fields, dates, representative target-language characters, and reading order.
8. Report unavailable checks as SKIP; never imply they passed.

Use scripts/check_resume_pdf.py for local structural checks when a PDF exists.

Prepare interviews

Read interview-frameworks.md. Generate questions from the final resume and role requirements. In mock interviews, ask one question at a time and give the complete review after the interview. Keep all sample answers inside the same evidence boundary as the submitted resume.

Delivery gate

Before delivery confirm:

• Route B retains the original source and a separate backup or working copy before any local edit;
• the career workspace, when used, reflects the latest confirmed facts and marks older derived versions stale instead of silently rewriting them;
• target profile, organization or program, role, location, and dates are consistent;
• eligibility is marked satisfied, unsatisfied, or pending;
• dates, metrics, technology, paper status, authorship, and personal scope are traceable;
• no private notes, confidential names, unapproved personal data, or internal evidence paths appear externally;
• every required output has been visually inspected after its latest change;
• the final populated compact one-page A4 layout—not only its master—uses 92%–97% of the page height without irrelevant filler, unless an explicit custom density contract was recorded; every other profile satisfies its declared acceptance criteria;
• PDF page count, target-script rendering, selectable text, and field extraction were actually checked;
• for the default HTML/PDF route, the delivered PDF was generated from the delivered HTML after its latest change; for an official or user-requested format, the validated source/export pair is current; the user has had an opportunity for final review;
• no aggregator or heuristic score is represented as an official hiring outcome.

Third-party lineage and adaptation boundaries are recorded in third-party-notices.md.