dennisthiessen/claude-resume-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: rebuild evidence-first application workflow

Browse Source
This commit is contained in:
dennisthiessen
2026-07-27 17:56:15 +02:00
parent c24892f381
commit fe5f24704f
57 changed files with 3815 additions and 3555 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOCS.md
+124 -184
View File
@@ -1,211 +1,151 @@
# Documentation
# System documentation
Detailed reference for claude-resume-kit. For the quick overview, see [README.md](README.md).
---
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
```
claude-resume-kit/
├── CLAUDE.md # Auto-loaded project instructions
├── config.md # Your personal configuration
├── .claude/skills/ # 6 skills (invoked as /skill-name)
│ ├── setup-extract/SKILL.md # Extract from papers → structured data
│ ├── setup-build-kb/SKILL.md # Synthesize KB from extractions
│ ├── make-resume/SKILL.md # JD → tailored resume/CV (.tex)
│ ├── make-cl/SKILL.md # Session → cover letter (.tex)
│ ├── edit-resume/SKILL.md # Edit from critique/feedback
│ └── critique/SKILL.md # Independent quality review
├── resume_builder/
│ ├── reference/ # Generation rules and protocols
│ │ ├── shared_ops.md # Session workflow (all skills read this)
│ │ ├── resume_reference.md # Resume/CV formatting rules
│ │ ├── cl_reference.md # Cover letter rules
│ │ ├── critical_rules.md # Compact re-read for generation phase
│ │ ├── session_file_template.md # Session file format spec
│ │ └── critique_framework.md # 8-part critique system
│ ├── templates/ # LaTeX .cls classes + .tex templates
│ │ ├── resume.cls # 2-page resume class
│ │ ├── cv.cls # Multi-page CV class
│ │ ├── resume_template.tex # Resume structural template
│ │ ├── cv_template.tex # CV structural template
│ │ └── coverletter_template.tex # Cover letter template
│ ├── helpers/
│ │ └── char_count.py # Character counting utility for bullets
│ ├── examples/ # Fictional "Dr. Jordan Chen" — full worked example
│ ├── experience/ # YOUR experience files (built by /setup-build-kb)
│ ├── bundles/ # YOUR role-type bundles (built by /setup-build-kb)
│ └── support/ # Skills taxonomy, pub metadata, AI fingerprint rules
├── knowledge_base/
│ ├── extractions/ # Paper extractions (built by /setup-extract)
│ ├── papers/ # Drop your PDFs / .tex source here
│ └── notes/ # Any other reference material
├── JDs/ # Job descriptions (text files)
└── output/ # Generated .tex files, session files, critiques
| 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.
## Concepts
## Canonical claims
### Session Files
Each reusable achievement should have a stable ID and, where applicable:
Every JD gets a session file (`output/<Folder>/session_<name>.md`) that tracks:
- JD analysis and ATS keywords
- Which bundle was selected
- Bullet plan (which achievements, in what order, at what length)
- All generation decisions and their rationale
- Cover letter plan
- Critique scores
- 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.
All 4 generation skills read and update this file. It's the single source of truth for each application.
The registry also holds the employment timeline, identity, work authorization, language facts, education, evidence-tiered skills, and global forbidden patterns.
### Experience Files
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.
One file per position (e.g., `experience_postdoc_university.md`). Each achievement has:
- **Source paper** with citation
- **Methods and tools** used
- **Quantitative results**
- **Pre-written bullet variants** (2-line and 3-line)
- **Tags** for which role types this achievement is relevant to
- **Significance** context for cover letters
## Application decision
### Role-Type Bundles
Generation begins only after the real JD is saved and classified. Every required and preferred qualification is recorded as:
One file per target audience (e.g., `bundle_academic.md`). Each bundle contains:
- **S1: Role Profile** — what this audience values, positioning strategy
- **S2: Summary Guide** — how to write the summary for this role type
- **S3: Achievement Reframing Map** — priority ranking of your achievements for this audience
- **S4: Skills Guide** — which tools to bold, which to include, grouping strategy
- **S5: Cover Letter Guide** — opening hooks, paragraph templates, anti-patterns
- **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.
### Provenance Flags
Evidence Fit is scored independently of document quality:
The system enforces accuracy through provenance tracking in `config.md`. Every achievement is tagged with its publication status. The skills check this table before every output and will never:
- Claim unpublished work is published
- Claim internal tools are peer-reviewed
- Use full-ownership verbs for shared work
- Inflate author position
| Dimension | Weight |
|---|---:|
| Required qualifications | 35 |
| Core responsibilities | 25 |
| Level and scope | 15 |
| Recency | 10 |
| Transferability | 10 |
| Practical constraints | 5 |
### The Critique System
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.
The `/critique` skill runs a multi-part assessment:
1. **Domain-Specialist Lens** — reviewer persona, gap analysis, competitive landscape
2. **Five-Perspective Read-Through** — ATS bot, recruiter (10s), HR (30s), hiring manager (2min), technical reviewer (10min)
3. **Eight-Dimension Scoring** — weighted score out of 100
4. **Interview Likelihood** — per-reader probability estimates
5. **Tiered Improvements** — ranked by point impact
6. **Interview Bridge Points** — resume-to-interview talking points
7. **Cover Letter Critique** — 6 sub-checks (anti-patterns, tailoring, context-specific, ATS keywords, structural, package cohesion)
8. **Post-Generation Verification** — mechanical and content checklists including AI fingerprint scan
Channel Strength is Strong, Moderate, or Weak and is tracked separately. Core applications should include a concrete warm-channel action where feasible.
---
## Resume policy
## Three-Session Workflow
The default is a two-page International Tech resume for US-tech/FAANG-style employers in Europe:
For best results, use a **separate Claude Code session** for each step. This gives each skill fresh context, which produces better quality (especially for critique — you want fresh eyes, not the same context that generated the resume).
- 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.
```
Session 1: /make-resume JDs/job.txt → resume/CV .tex
/clear
Session 2: /make-cl → cover letter .tex
/clear
Session 3: /critique → critique .md with score
/clear
/edit-resume → refined .tex (if needed)
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.
## Customization
## Skills
### Everything in `config.md` (edit directly)
| 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 |
| Setting | What it controls | Example |
|---------|-----------------|---------|
| **Personal Info** | Name, email, phone, links on all outputs | Your contact details |
| **Document Preferences** | Page counts, bullet line variants, skills layout | `Resume: 2 pages, CV: 5 pages` |
| **Provenance Flags** | What claims are safe to make | `ML paper: under review → never say "published"` |
| **Role Types** | Target audiences and their bundles | `Academic (Tier 1), Industry R&D (Tier 2)` |
| **Decision Tree** | How JD keywords map to role types | `"tenure-track" → Academic` |
| **FIXED Sections** | Template sections that never change per JD | `Education, Publications, Awards` |
| **Output Rules** | Package formats and constraints | `Resume: 2pg + 1pg CL = 3pg package` |
| **KB Corrections** | Errors to never re-introduce | `Spearman is 0.82, not 0.85` |
### LaTeX Templates (edit directly)
- **Fonts, colors, spacing** — modify `.cls` files
- **Section order** — reorder sections in `.tex` templates
- **FIXED content** — fill in education, awards, publications, header
- **Icons** — replace `GS.png` / `orcid.png` with your own
- **Page geometry** — adjust margins in `.cls` if needed
### Knowledge Base (built by skills, then editable)
| File | How to customize |
|------|-----------------|
| **Experience files** | Edit bullet text, add/remove achievements, adjust tags |
| **Bundles** | Change priority matrices, rewrite summary guides, add role types |
| **Skills taxonomy** | Add/remove skills, change groupings, adjust bold rules |
| **Pub metadata** | Update citation counts, add new publications |
### Reference Docs (advanced)
| File | What you'd change |
|------|-------------------|
| `resume_reference.md` | Page budgets, character limits, section specs |
| `cl_reference.md` | Cover letter paragraph templates, word count targets |
| `critical_rules.md` | Generation-time rules tables |
| `critique_framework.md` | Scoring weights, critique dimensions |
| `shared_ops.md` | Session workflow, file derivation logic |
### Skill Prompts (advanced)
Each skill is a markdown file in `.claude/skills/<name>/SKILL.md`. You can:
- Add STOP points for more user control
- Change the number of web searches in Phase 0
- Adjust how many bullets per position
- Modify the critique scoring weights
- Add new skills for your workflow
---
## Key Design Decisions
- **Accuracy > Relevance > Impact > ATS > Brevity** — the priority hierarchy for every generation decision
- **LaTeX-only output** — Claude generates `.tex`, you compile locally. No formatting surprises.
- **FLIPPED position format** — the bold line under each position title is a JD-customized theme, not a generic description. This is the strongest tailoring lever.
- **Structured provenance** — every achievement is tracked from source paper through extraction to experience file to resume bullet
- **Character-precise budgets** — every bullet is calibrated to fit the template geometry, not "try to keep it short"
- **Session files as state** — all decisions for a JD live in one file. Skills can recover from interruptions.
- **Anti-fabrication by design** — provenance flags, verb discipline, and corrections logs prevent overclaiming even under pressure to impress
- **AI fingerprint avoidance** — a dedicated rules file is loaded by all generation and critique skills, covering banned words and phrases (with technical exceptions), structural anti-patterns, positive markers, and a 12-item post-generation checklist
---
## FAQ
**Q: Do I need to know LaTeX?**
No. Claude generates the `.tex` files. You just compile them (`pdflatex file.tex`). The templates handle all formatting.
**Q: How many papers should I extract?**
All papers where you're first author or co-first author, plus key contributing-author papers. Quality matters more than quantity — 5 well-extracted papers beat 20 shallow ones.
**Q: Can I use this for non-academic roles?**
Yes. The framework supports any role type — define them in `config.md`. Industry R&D, consulting, data science, and engineering roles all work. Just create appropriate bundles.
**Q: What if I don't have a Google Scholar / ORCID?**
Remove those lines from the templates. The framework adapts to what you have.
**Q: How do I update after publishing new papers?**
Run `/setup-extract` on the new paper, then update your experience file and bundles. Existing session files are not affected.
**Q: Can I use this with resume formats other than the included templates?**
Yes. The `.cls` files define the visual style. You can modify them or write your own. The skills generate content based on the template structure — update the `[GENERATE: ...]` and `[FIXED: ...]` markers in your template.
**Q: Can multiple people use the same kit?**
Each person needs their own clone with their own `config.md`, knowledge base, and templates. The framework itself is shared; the content is personal.
**Q: What Claude model should I use?**
The skills are designed for Claude's most capable models (Opus, Sonnet). Less capable models may skip steps or produce lower-quality output.
See the complete procedures in `.agents/skills/<skill>/SKILL.md` and `resume_builder/reference/`.