# 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:

```text
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

```powershell
# 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/`.