152 lines
7.7 KiB
Markdown
152 lines
7.7 KiB
Markdown
# 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/`.
|