feat(apply,interview): cache company research to skip repeat lookups (#349)

/apply Step 3's reviewer agent and /interview Step 2 each independently
execute the Company Research Checklist (04-job-evaluation.md) for the
same company - applying to a role and later prepping for its interview
researches the company twice from scratch, same WebSearch/WebFetch cost
both times, no sharing between the two commands.

Adds a company_research/<normalized-name>.json cache (30-day TTL) that
either consumer checks before researching and writes after a fresh
pass. Defined once in 04-job-evaluation.md, next to the checklist it
mirrors, so both commands point at one source instead of restating the
schema. Does not change the verification model: 03-writing-style.md
rule 5 already treats reviewer-agent research as a lead, not a source,
requiring independent re-confirmation before any company claim ships
in a final artifact - the cache stores source URLs alongside each
fact so that re-confirmation stays cheap, but the requirement itself
is untouched and restated in both consumers.

company_research/*.json added to .gitignore and security_guards.py's
REQUIRED_IGNORE_RULES as a plain rooted pattern (not **/-prefixed):
the cache is referenced from commands, not a skill, so it resolves
against the repo root normally, unlike job_scraper/upskill's
skill-relative paths.

Pinned by tests/test_company_research_cache.py, mirroring the
spec-pinning pattern in test_rank_command.py and test_onboarding_privacy.py.
The write-back assertions for both apply.md and interview.md were
verified to actually fail against the regression they guard (the
instruction stripped, confirmed the test catches it, restored) before
being considered done - the write half is the one most likely to be
dropped silently in a future edit, since the read half is the more
obvious change to make.

framework_version bumped 1.2.4 -> 1.2.5 in 04-job-evaluation.md, the
only touched file inside the tracked skill set.
This commit is contained in:
Gabriel Ignacio Mensi
2026-08-22 11:21:34 +02:00
committed by GitHub
parent ab91c60cc4
commit becdc5dfd7
8 changed files with 225 additions and 3 deletions
@@ -1,5 +1,5 @@
---
framework_version: 1.2.4
framework_version: 1.2.5
---
# Job Evaluation Framework
@@ -179,6 +179,52 @@ Present the evaluation as:
- [ ] Identified network contacts who may know the team/manager
```
## Company Research Cache
The Company Research Checklist above is executed independently by `/apply` Step 3's
reviewer agent and by `/interview` Step 2 - the same company, researched from scratch
twice when the two commands run against the same application. This cache lets either
consumer reuse a recent result instead of repeating the search/fetch work.
**This does not change how a claim gets verified.** `03-writing-style.md` rule 5 and
`/interview`'s own Step 2 already require that any company-specific claim landing in a
final artifact (cover letter, interview prep pack) be independently re-confirmed before
inclusion, regardless of source - a cache hit is a lead, exactly like reviewer-agent
research already is, never a substitute for that final check. The cache only removes
repeated *discovery* work: it stores where each fact came from, so re-confirming a
specific claim means re-fetching a known URL instead of re-searching for it.
**File:** `company_research/<normalized-company-name>.json`, one file per company.
Normalize the company name for the filename: lowercase, trim, spaces to hyphens (e.g.
`Acme Corp` -> `acme-corp.json`). No legal-suffix normalization - a near-miss on a
different spelling just costs a cache miss and a fresh (correct) research pass, never a
wrong answer.
**TTL:** 30 days from `fetched_date`. A conservative default, easy to change here alone
since both consumers read this section rather than hardcoding a number of their own.
**Schema** (fields mirror the Company Research Checklist's own categories above):
```json
{
"company": "Acme Corp",
"fetched_date": "YYYY-MM-DD",
"sources": {
"website": {"url": "...", "notes": "mission, values, recent news"},
"reviews": {"url": "...", "notes": "..."},
"linkedin": {"url": "...", "notes": "team size, recent hires"},
"media": {"url": "...", "notes": "..."}
},
"network_contacts_note": "..."
}
```
**Before researching a company**, check for `company_research/<normalized-name>.json`.
If it exists and `fetched_date` is within the 30-day TTL, use its contents as the
starting point instead of searching from scratch - still subject to the final-claim
verification rule above. If it is missing or stale, research per the checklist as usual,
then write (or overwrite) the file with fresh findings and today's date, so the next
consumer benefits.
## Weighting
- Technical Skills: 30%
- Experience Match: 25%