mirror of
https://github.com/MadsLorentzen/ai-job-search.git
synced 2026-11-02 13:12:50 +00:00
fix(specs): settle every workflow spec on python3, one Windows note at first use (#678)
* fix(specs): settle every workflow spec on python3 with one Windows note at first use * fix(specs): finish python3 in the specs /apply reads; Windows note says run as python - 04-job-evaluation (salary lookup), 05-cv-templates (verify_pdf x2) and CLAUDE.md now spell python3 like apply.md; framework_version bumped on 04 (1.2.7) and 05 (1.4.8), each with its own Windows note at first use. - The note now covers Windows generally: python3 is either the exit-49 Store stub or a separate Store Python without pip's packages, so run as python. - tests/test_python_command_specs.py globs commands, skills and agents instead of naming four files. - CHANGELOG entry matches the final scope. * changelog: place the #678 entry under [Unreleased] Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Mads Lorentzen <madslorentzen_17@hotmail.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
11 files changed
+168
-17
No files matched your search
@@ -44,8 +44,10 @@ Read the evaluation framework:
|
||||
|
||||
Using the framework from `04-job-evaluation.md`, evaluate the job posting against the candidate's profile. If the salary lookup tool is configured, run:
|
||||
|
||||
> **Windows:** run these tools as `python`, not `python3`. A python.org install ships no `python3`, so that name reaches the Microsoft Store alias, which either exits 49 with no output (#669) or starts a separate Store Python without the packages `pip` installed (such as pypdf). `.claude/settings.json` allows both spellings.
|
||||
|
||||
```bash
|
||||
python salary_lookup.py "<Company Name>" --json
|
||||
python3 salary_lookup.py "<Company Name>" --json
|
||||
```
|
||||
|
||||
If the posting specifies a city, add `--city "<City>"` to narrow results. Parse the JSON output and include the salary benchmark in the evaluation. If the tool is not configured or returns an error, skip the salary benchmark.
|
||||
@@ -256,10 +258,10 @@ If either compile fails, fix the error and re-compile until clean.
|
||||
**Measure first, then look.** A visual read catches gross breakage but cannot tell you that a page is 40% empty, and the failure below survives both a clean compile and a correct page count:
|
||||
|
||||
```bash
|
||||
python tools/verify_pdf.py cv/main_<company>_<role>.pdf --pages 2
|
||||
python tools/verify_pdf.py cover_letters/cover_<company>_<role>.pdf --pages 1
|
||||
python tools/verify_layout.py cv/main_<company>_<role>.pdf
|
||||
python tools/verify_layout.py cover_letters/cover_<company>_<role>.pdf
|
||||
python3 tools/verify_pdf.py cv/main_<company>_<role>.pdf --pages 2
|
||||
python3 tools/verify_pdf.py cover_letters/cover_<company>_<role>.pdf --pages 1
|
||||
python3 tools/verify_layout.py cv/main_<company>_<role>.pdf
|
||||
python3 tools/verify_layout.py cover_letters/cover_<company>_<role>.pdf
|
||||
```
|
||||
|
||||
The two `--pages` lines are the page-count check: exactly 2 pages for the CV and exactly 1 for the cover letter (the hard limits in `05-cv-templates.md` and `06-cover-letter-templates.md`), exit 1 otherwise. With a custom template active, substitute its declared **Page limit** from the `ACTIVE-TEMPLATE` block. Nothing else runs this check - `verify_layout.py` deliberately leaves page count to it, and Step 5d's extraction call passes no `--pages` - so if these lines are skipped, the page budget is enforced by nothing but the visual read below.
|
||||
@@ -301,12 +303,12 @@ Do not proceed to Step 6 until both PDFs pass inspection.
|
||||
|
||||
An ATS parser reads the PDF's embedded **text layer**, not the rendered page — a CV that passed visual inspection can still extract as garbage (icon glyphs where the contact details should be, scrambled reading order in multi-column layouts). This step verifies what a parser actually sees. It applies to the **CV only**; cover letters rarely go through keyword screening.
|
||||
|
||||
**Availability check:** extract with `python tools/verify_pdf.py` (tries **pypdf** first — BSD, `pip install pypdf` — then Poppler `pdftotext`). If both are missing, print a one-line warning that the mechanical parse check is skipped, do the keyword-coverage check (item 3 below) against your visual Read of the PDF instead, and note the degraded mode in the Step 6 report. Same graceful-skip pattern as the salary lookup. If a documented fallback still shells out to `pdftotext -layout`, keep the `-enc UTF-8` flag: Xpdf-based builds default to Latin-1 output, and without it a correct non-ASCII CV fails the replacement-character check below.
|
||||
**Availability check:** extract with `python3 tools/verify_pdf.py` (tries **pypdf** first — BSD, `pip install pypdf` — then Poppler `pdftotext`). If both are missing, print a one-line warning that the mechanical parse check is skipped, do the keyword-coverage check (item 3 below) against your visual Read of the PDF instead, and note the degraded mode in the Step 6 report. Same graceful-skip pattern as the salary lookup. If a documented fallback still shells out to `pdftotext -layout`, keep the `-enc UTF-8` flag: Xpdf-based builds default to Latin-1 output, and without it a correct non-ASCII CV fails the replacement-character check below.
|
||||
|
||||
**1. Extract the text layer:**
|
||||
|
||||
```bash
|
||||
python tools/verify_pdf.py cv/main_<company>_<role>.pdf --ascii-dates --dump-text cv/main_<company>_<role>.txt
|
||||
python3 tools/verify_pdf.py cv/main_<company>_<role>.pdf --ascii-dates --dump-text cv/main_<company>_<role>.txt
|
||||
```
|
||||
|
||||
`--ascii-dates` is the date-range check from `05-cv-templates.md` ("Date fields must be ASCII ranges"): it exits 1 if the raw text layer has a year joined to a Unicode dash - the en-dash LaTeX makes from `--`, which a Workday import dropped together with the date - naming each hit and its code point. It reads the raw layer, not the folded comparison `--contains` uses, which is why `--contains "2016-2024"` cannot catch this. The dump is written before the check runs, so a failure still leaves the `.txt`. Fix a hit in the `<CV_EXT>` date argument (a single ASCII hyphen), then re-run 5a-5c and re-extract.
|
||||
|
||||
@@ -26,6 +26,8 @@ Follow these steps **in order**.
|
||||
|
||||
Never read `job_scraper/seen_jobs.json` into the conversation. It holds every job the workspace has ever seen - most of it `skipped` - while a run only ever touches the handful of entries being scored, so a manual read costs the whole backlog on every run and grows for the life of the workspace. Selecting candidates is a query, so run the query:
|
||||
|
||||
> **Windows:** run these tools as `python`, not `python3`. A python.org install ships no `python3`, so that name reaches the Microsoft Store alias, which either exits 49 with no output (#669) or starts a separate Store Python without the packages `pip` installed (such as pypdf). `.claude/settings.json` allows both spellings.
|
||||
|
||||
```bash
|
||||
python3 tools/rank_state.py candidates --limit 10 # add --all / --focus "<text>" per Step 0
|
||||
```
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
framework_version: 1.2.6
|
||||
framework_version: 1.2.7
|
||||
---
|
||||
|
||||
# Job Evaluation Framework
|
||||
@@ -124,8 +124,11 @@ Does this role advance career goals and contain tasks that energize?
|
||||
### 6. Salary Benchmark (Optional)
|
||||
|
||||
If the salary lookup tool is configured (`salary_data.json` exists), look up the company:
|
||||
|
||||
> **Windows:** run these tools as `python`, not `python3`. A python.org install ships no `python3`, so that name reaches the Microsoft Store alias, which either exits 49 with no output (#669) or starts a separate Store Python without the packages `pip` installed (such as pypdf). `.claude/settings.json` allows both spellings.
|
||||
|
||||
```
|
||||
python salary_lookup.py "<Company Name>" --json
|
||||
python3 salary_lookup.py "<Company Name>" --json
|
||||
```
|
||||
|
||||
If a city is known from the posting, add `--city "<City>"` to narrow results.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
framework_version: 1.4.7
|
||||
framework_version: 1.4.8
|
||||
---
|
||||
|
||||
# CV Templates and Tailoring Guide
|
||||
@@ -273,8 +273,10 @@ Restore the highest-relevance item that was previously cut — a CV that ends mi
|
||||
|
||||
Most employers run CVs through an ATS before a human sees them, and the ATS reads the PDF's embedded **text layer**, not the rendered page. A CV can pass visual inspection and still extract as garbage. After the layout passes the compile-and-inspect loop, verify the text layer:
|
||||
|
||||
> **Windows:** run these tools as `python`, not `python3`. A python.org install ships no `python3`, so that name reaches the Microsoft Store alias, which either exits 49 with no output (#669) or starts a separate Store Python without the packages `pip` installed (such as pypdf). `.claude/settings.json` allows both spellings.
|
||||
|
||||
```bash
|
||||
python tools/verify_pdf.py cv/main_<company>_<role>.pdf --dump-text cv/main_<company>_<role>.txt
|
||||
python3 tools/verify_pdf.py cv/main_<company>_<role>.pdf --dump-text cv/main_<company>_<role>.txt
|
||||
```
|
||||
|
||||
Extraction tries **pypdf** first (`pip install pypdf`, BSD license), then Poppler `pdftotext`. If a fallback still uses `pdftotext -layout`, it must also pass `-enc UTF-8`: Xpdf-based builds default to Latin-1, which makes every non-ASCII character in a perfectly good CV read back as a replacement character. If neither extractor is available, skip the mechanical check with a warning and rely on the visual PDF read for keyword coverage.
|
||||
@@ -310,7 +312,7 @@ Two independent causes, both easy to avoid:
|
||||
|
||||
Where a genuine range exists, use it even when a single year would be factually accurate - a degree written `1995` is true but imports worse than `1992-1995`. Do not invent a start date you do not have; a lone graduation year is fine, just expect it to be typed in by hand.
|
||||
|
||||
**Cause 1 is mechanical in step 5d**: `python tools/verify_pdf.py cv/main_<company>_<role>.pdf --ascii-dates` scans the raw text layer for a year joined to a Unicode dash and exits 1 naming each hit with its code point (`U+2013 in 'Role Title 2016–2024'`). It deliberately reads the raw layer: the fold that lets `--contains "2016-2024"` match what the template renders maps that same en-dash back to `-`, so `--contains` can never see this. A year on either side of the dash is enough, so `Mar 2016 – Jul 2016` and `2016 – Present` are caught too; a numeric range with no year (`EUR 600k–1M`) is left alone. **Cause 2 stays a read-through check**: after extracting the text layer, confirm every experience entry shows a start *and* an end. Because both failures are silent and invisible in the PDF, the candidate otherwise discovers them only while filling in the application form.
|
||||
**Cause 1 is mechanical in step 5d**: `python3 tools/verify_pdf.py cv/main_<company>_<role>.pdf --ascii-dates` scans the raw text layer for a year joined to a Unicode dash and exits 1 naming each hit with its code point (`U+2013 in 'Role Title 2016–2024'`). It deliberately reads the raw layer: the fold that lets `--contains "2016-2024"` match what the template renders maps that same en-dash back to `-`, so `--contains` can never see this. A year on either side of the dash is enough, so `Mar 2016 – Jul 2016` and `2016 – Present` are caught too; a numeric range with no year (`EUR 600k–1M`) is left alone. **Cause 2 stays a read-through check**: after extracting the text layer, confirm every experience entry shows a start *and* an end. Because both failures are silent and invisible in the PDF, the candidate otherwise discovers them only while filling in the application form.
|
||||
|
||||
## Page Budget - Hard 2-Page Limit
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
framework_version: 1.1.5
|
||||
framework_version: 1.1.6
|
||||
---
|
||||
|
||||
# Web Research and Fetching
|
||||
@@ -35,6 +35,8 @@ Do **not** respond to a 403 by softening the cover letter to vague generalities,
|
||||
|
||||
The retry command below runs this check itself and refuses to fetch when it fails - there is no flag to skip it. The standalone checker is still there for diagnosing a refusal:
|
||||
|
||||
> **Windows:** run these tools as `python`, not `python3`. A python.org install ships no `python3`, so that name reaches the Microsoft Store alias, which either exits 49 with no output (#669) or starts a separate Store Python without the packages `pip` installed (such as pypdf). `.claude/settings.json` allows both spellings.
|
||||
|
||||
```bash
|
||||
python3 tools/robots_check.py '<URL>'
|
||||
```
|
||||
@@ -52,7 +54,7 @@ Two details worth knowing, both covered by `tests/test_robots_check.py`:
|
||||
python3 tools/fetch_page.py '<URL>' --out "${SCRATCHPAD:?set this to the session scratchpad directory from your system prompt}/page.html" --text
|
||||
```
|
||||
|
||||
One command does the whole retry: it runs the `robots.txt` gate above (exit `1` and no fetch when the policy says no), GETs the page with browser headers, saves the body to `--out`, prints `HTTP <code> size=<bytes> saved=<path>`, and with `--text` prints the tag-stripped text (script, style, noscript, svg and comments removed, entities unescaped) capped at `--max-chars` (default 6000). It is GET-only with a fixed argv, http(s) only, bounded to 45 s, 5 redirects and 10 MB, and it refuses an `--out` inside the repo - fetched content is untrusted and belongs in the scratchpad. That fixed shape is why the workflow pre-approves `python tools/fetch_page.py` and not `curl`.
|
||||
One command does the whole retry: it runs the `robots.txt` gate above (exit `1` and no fetch when the policy says no), GETs the page with browser headers, saves the body to `--out`, prints `HTTP <code> size=<bytes> saved=<path>`, and with `--text` prints the tag-stripped text (script, style, noscript, svg and comments removed, entities unescaped) capped at `--max-chars` (default 6000). It is GET-only with a fixed argv, http(s) only, bounded to 45 s, 5 redirects and 10 MB, and it refuses an `--out` inside the repo - fetched content is untrusted and belongs in the scratchpad. That fixed shape is why the workflow pre-approves `python3 tools/fetch_page.py` and not `curl`.
|
||||
|
||||
The HTTP status is information, not a verdict: a `403` body still tells you what the site answered. Only exit `2` (unsupported scheme, transport failure, oversized response) means nothing was retrieved.
|
||||
|
||||
|
||||
@@ -143,6 +143,8 @@ For each new job, do a rapid fit check (NOT the full evaluation from `04-job-eva
|
||||
|
||||
1. Derive each entry's key with the helper, never by slugifying in the moment:
|
||||
|
||||
> **Windows:** run these tools as `python`, not `python3`. A python.org install ships no `python3`, so that name reaches the Microsoft Store alias, which either exits 49 with no output (#669) or starts a separate Store Python without the packages `pip` installed (such as pypdf). `.claude/settings.json` allows both spellings.
|
||||
|
||||
```bash
|
||||
python3 tools/job_key.py --company "<company>" --title "<title>" --url "<url>"
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user