claude-resume-kit/DOCS.md

System documentation

This is the operating reference for the evidence-first resume workflow. Project-wide safety rules remain in AGENTS.md; personal facts and preferences remain in config.md.

Architecture

Layer	Location	Purpose
Raw evidence	knowledge_base/	Employment records, papers, notes, project material
Extractions	knowledge_base/extractions/	Source-supported facts with attribution and open questions
Canonical registry	resume_builder/canonical/claims.json	Authoritative dates, titles, claims, scope, verbs, skills and restrictions
Historical safety	resume_builder/canonical/historical_outputs.json	Prevents unsafe old packages from seeding new ones
Normalized context	resume_builder/experience/	Detailed achievement context linked to canonical IDs
Role strategy	resume_builder/bundles/	Evidence priorities and cautions by role family
Support	resume_builder/support/	Evidence-tiered skills and safe reframing guidance
Workflow policy	resume_builder/reference/	Fit, resume, letter, critique and session rules
Generation skills	.agents/skills/	Extraction, KB maintenance, generation, editing and critique
Outputs	output/	Application artifacts; never an evidence source

The dependency direction is one-way:

raw source -> extraction -> canonical claim -> normalized context -> generated document

When a fact is corrected, update the canonical registry first, propagate the correction to dependent normalized files, classify affected historical outputs, and run the validator.

Canonical claims

Each reusable achievement should have a stable ID and, where applicable:

• employer and role;
• source and verification state;
• ownership scope;
• supported action, method, outcome and metric state;
• allowed verbs;
• forbidden or unsafe wording;
• skills actually demonstrated;
• role relevance.

The registry also holds the employment timeline, identity, work authorization, language facts, education, evidence-tiered skills, and global forbidden patterns.

Skills use evidence states such as production-current, production-historical, hands-on-current, proof of concept, certification-only, or unverified. A JD keyword never upgrades the evidence state. Unverified and forbidden skills do not appear in an application.

Application decision

Generation begins only after the real JD is saved and classified. Every required and preferred qualification is recorded as:

• Direct: demonstrated in a canonical professional example;
• Adjacent: credible transfer, explicitly identified as such;
• Gap: no supported evidence;
• Constraint: location, authorization, clearance, compensation, language, or another practical blocker.

Evidence Fit is scored independently of document quality:

Dimension	Weight
Required qualifications	35
Core responsibilities	25
Level and scope	15
Recency	10
Transferability	10
Practical constraints	5

Fit classes are Core (75+), Adjacent (60--74), and Stretch (below 60). A failed hard requirement can override the numeric class and produce a no-go. User approval may override whether to apply, but never rewrites the fit result.

Channel Strength is Strong, Moderate, or Weak and is tracked separately. Core applications should include a concrete warm-channel action where feasible.

Resume policy

The default is a two-page International Tech resume for US-tech/FAANG-style employers in Europe:

• conventional employer, formal title, date and location hierarchy;
• optional summary limited to two or three rendered lines;
• four to six compact, evidence-backed skill lines;
• normally 11--14 bullets selected for relevance, not as a quota;
• more evidence for recent roles, with zero or one bullet for older roles where appropriate;
• natural one-, two-, and three-line bullet lengths;
• no photo or demographic data;
• certifications listed once.

The Swiss/DACH overlay keeps the same evidence and hierarchy. Dennis's Swiss B residence permit and no-sponsorship status are verified, but should appear only when they resolve work-authorization uncertainty or a form asks for them. A photo is opt-in only, and supporting certificates or references are separate portal attachments when requested. A three-page dossier is an employer-specific exception, not the default.

Do not replace formal titles with tailored marketing themes. Do not add a skill to imitate the JD. Do not use whitespace as a reason to add filler.

Cover-letter policy

A cover letter is generated only when it is required or adds material value, for example:

• a strong, verified employer-specific motivation;
• a transition or unusual background that needs explanation;
• work authorization or location context that helps the decision;
• a directly relevant example that needs slightly more narrative than a resume bullet allows;
• an employer-specific Swiss/DACH motivation-letter convention.

Generic optional letters are skipped. Every work claim in a letter must be both canonical and present in the resume. Employer hooks require a current first-party source. One page and two or three substantive paragraphs are normally sufficient.

Critique policy

Critique reports three axes, never one overall number:

1. Evidence Fit: whether the background meets the actual job.
2. Document Quality: truth/provenance, hierarchy, bullets, relevance, skills and mechanics.
3. Channel Strength: cold versus warm application conditions.

Hard-gate failures come first. A high-quality document is not called submit-ready when role fit fails. Interview likelihood is a qualitative competitive read, not invented precision.

Impact evidence

knowledge_base/impact_evidence.md is the capture queue for missing outcomes. A metric is reusable only when its definition, period, baseline, scope, source and attribution are known. Qualitative outcomes remain qualitative until verified. This prevents a plausible number from becoming a permanent fabricated fact.

Cohort tracking

job_scout/state/application_cohort.json tracks a ten-role learning cohort:

• seven Core applications;
• two Adjacent applications;
• one deliberate Stretch application.

Use resume_builder/helpers/cohort_tracker.py to add or summarize entries. Record outcome stages consistently: submitted, recruiter screen, hiring-manager screen, assessment, interview, rejected, withdrawn, or closed. Review results after the cohort rather than changing the strategy after each rejection.

Commands

# Validate normalized sources and workflow policy
python resume_builder/helpers/validate_resume_system.py

# Validate a generated resume or cover letter
python resume_builder/helpers/validate_resume_system.py --document output/Role/file.tex

# Readability diagnostics; no target bands
python resume_builder/helpers/char_count.py output/Role/file.tex

# Cohort status
python resume_builder/helpers/cohort_tracker.py summary

For each generated package, also compile the LaTeX, confirm the expected page count, visually inspect every page, and use pdftotext to check ATS-readable order.

Skills

Skill	Responsibility
setup-extract	Preserve facts, sources, attribution and unresolved questions
setup-build-kb	Promote reviewed evidence into canonical and normalized sources
make-resume	Verify JD, run fit gate, plan, generate and validate
make-cl	Decide whether a letter helps, then generate only when justified
critique	Audit hard gates, evidence, document quality and channel separately
edit-resume	Apply approved repairs without bypassing canonical controls

See the complete procedures in .agents/skills/<skill>/SKILL.md and resume_builder/reference/.