search-jobs
Skill4 starsChanged 13 days agoMITView on GitHub
Run the top-of-funnel sourced sweep — scan configured sources, dedupe, check liveness, coarse-triage every new entry with fitScore/fitBucket/fitBasis, save JD bodies, write watermarks, and optionally hand top sourced roles to evaluate-job. Does not tailor, fill, or submit.
- Reads credentials
1 other project uses a version of this.
Adopted by
Most recently taken up by
- seonwooj0810/careerlooptheir own version, first seen Oct 20, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- seonwooj0810/careerloop★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository31 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- answer-questionSkill
- apply-jobSkill
- calendar-syncSkill
- coach-gapsSkill
- company-healthSkill
- configureSkill
- discover-companiesSkill
- email-commsSkill
- evaluate-jobSkill
- ingest-mailSkill
- ingest-messagesSkill
- ingest-profileSkill
- intake-extractSkill
- interview-prepSkill
- optimize-linkedinSkill
- reevaluate-strategySkill
- relationship-sourcingSkill
- report-issueSkill
- research-boardsSkill
- research-companySkill
- research-compSkill
- resume-extractSkill
- schedule-meetingSkill
- setup-searchesSkill
- sync-statusSkill
- tailor-applicationSkill
- track-outcomesSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
31 rules. About 0 are common, 12 are distinctive, and 19 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
19
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Do not stop after the first viable lead while search or fetch budget remains.
- Distinctive: line 48
Read all gate files before touching anything else:
- Very specific: line 58
Run careerrat doctor and confirm it exits clean.
- Very specific: line 65
If doctor says the next discovery step is setup-searches, research-boards, or discover-companies, run that owning skill first during an …
- Distinctive: line 67
When the user explicitly asked to search and at least one enabled source exists, their request already authorizes a partial sweep of the …
- Distinctive: line 84
If sources are present but haven't been derived from targeting yet, optionally rebuild:
- Very specific: line 101
Use --explicit when the user asked for this search.
- Very specific: line 110
Keep its exact returned run ID and continue the conversation while the worker runs.
- Very specific: line 114
If the user cancels, use careerrat search cancel --id <run-id> --json and retain any saved partial results.
- Very specific: line 125
If every source was non-runnable, health is failed and says nothing was searched.
- Distinctive: line 137
Don't start a second foreground scan while the same worker is active.
- Very specific: line 141
Run the full sourced sweep against all enabled sources since their lastRunAt watermarks:
- Distinctive: line 163
JS-rendered or login-gated boards: if a source returns nothing (or returns only partial listings) because the board requires a login or …
- Distinctive: line 183
After the session is ready, scrape via the session browser.
- Very specific: line 201
Verify the salary-band integer renders the expected floor on the live page before trusting it (LinkedIn occasionally renumbers bands).
- Very specific: line 216
If a previous snapshot exists for a source, run the delta to extract only net-new entries not already in tracker or workspace/jobs/:
- Very specific: line 271
If workspace/scan-results/sourced-<date>.json already has the body text, use it.
- Very specific: line 274
Write to workspace/jobs/<company>-<slug>.md with frontmatter:
- Very specific: line 289
Sourced-role lifecycle: every new posting written here is simultaneously added to (or confirmed in) sourced rows with status: "sourced": …
- Very specific: line 298
After the sweep completes, ensure lastRunAt is updated for each source that ran.
- Very specific: line 305
Read and print the current (before) lastRunAt value: searches[id=<source>].lastRunAt (print it so the write can be confirmed).
- Distinctive: line 313
If during this session the user said something like "skip \<Company\> from now on", "add \<signal\> as a cut", or "cap me at N apps to …
- Very specific: line 323
After writing, echo the CLI's confirmation.
- Very specific: line 327
[DELEGATE: subagent]: When several high-fit roles qualify, fan out the body-read gate — one subagent per role (cap ≈5).
- Very specific: line 355
Do not promote any sourced entry to tracker application state without an evaluate-job GATE: KEEP verdict.
- Distinctive: line 367
Run tracker integrity after any sourced additions:
- Very specific: line 402
KEEP verdicts ready, hand off to apply-job.
- Distinctive: line 408
One point-of-use choice: Ask the site-specific Yes/No login question only when that source needs it.
- Distinctive: line 411
Visible auth challenges stay with the user: Ask the point-of-use Yes/No question for a login wall.
- Very specific: line 413
Tool-agnostic browser prose: Keep the provider on auto and use the available session browser.
- Distinctive: line 416
Domain-neutral: No hardcoded platforms beyond what source config defines.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
search-jobs
Runs under AGENTS.md. These contracts bind without being restated here: Privacy Invariant (
current_basenever outbound), Honesty Firewall, Placeholder/Bracket Ban, Gate Write-back, Domain-Neutral Rule, Browser Automation Contract, Activity Pulse logging, Tracker verify+snapshot, and Sent-Clears-Draft. Inline reminders at point-of-use are intentional; standalone restatements point back to the relevant AGENTS.md section. Barecandidate/,workspace/,config/, and.internal/paths below are symbolic; resolve them per AGENTS.md's Path Resolution rule.
AI Web Search mode
Do not stop after the first viable lead while search or fetch budget remains. Keep looking for distinct active postings until the bounded search is genuinely exhausted or the practical result goal below is met, then stop immediately and return.
Activated when the kickoff input is JSON containing "mode": "ai-web-search" (a prompts: [{id, text}] array, a candidate context object, and a server-owned search_plan arrive alongside it in that same input). When this mode is active, run this section instead of STEP 0 through STEP 8 above — it is a separate, read-only execution path through the same skill, not a variant of the file-writing sweep.
Tool surface is restricted to Read, Glob, Grep, WebFetch, WebSearch, and Skill. No Bash, no Write, no Edit, no session browser, and no careerrat/npm CLI commands are available in this mode — the embedded runtime enforces this at the tool-allowlist level, so do not attempt any of them. Everything STEP 0-8 above does through a CLI command, a file write, or the session browser is out of scope here; see "Skip" below.
The kickoff search_plan is authoritative for every initial, freshness-recovery, and useful-set top-up turn. Run its query_hints exactly in the supplied order; do not paraphrase them, retry them, or invent another query. Its per-turn limits are hard stops: use at most 4 WebSearch calls per saved prompt and at most 8 job-posting WebFetch calls per saved prompt. Count every attempted call before running it. A failed search or fetch consumes that call's budget. Never start a call that would exceed either limit. Stop immediately when every query hint is consumed, the practical result goal is met, or either relevant budget limit is reached, and return the required JSON.
The broad hints split the selected titles into location-preserving queries. The remaining hints are server-derived configured-source, employer-owned career, or direct-ATS queries built only from the selected configured titles, location posture, and bounded host-only source_hints. The source_hints are advisory inputs to those supplied queries only; never use them to invent another query or search. Search broadly before spending the fetch budget, with a practical goal of 3-5 viable leads per prompt when the open web has them. Keep the candidate set diverse across at least two different source hosts whenever two viable hosts exist, and return no more than one candidate from the same third-party host in one prompt turn. Third-party boards are useful discovery sources: resolve their employer-and-title leads to an employer-owned or direct ATS posting when one is available. Never emit an aggregator search/results page. Every returned URL must identify one posting, never a generic search, category, location, career-hub, or redirect-wrapper page. An employer's own current openings page may be kept only when the named role is visibly present there. For up to eight promising posting URLs, use WebFetch to improve the capture. When a fetched page is archived, expired, gone, mismatched, or for a different job, requisition, or posting, discard it and use another lead already returned by the supplied query hints instead of searching again. If a posting-specific third-party URL still needs a browser session or is browser-blocked after a direct-posting resolution attempt, return the title, company, exact URL, visible location/comp/date, and factual search-result evidence with body_text: null and body_partial: true; CareerRat preserves it as an explicitly unverified partial lead. Reject an expired redirect. Drop generic search, category, location, and career-hub pages; unsafe or private URLs; results that lack a specific role and employer; postings whose canonical evidence names a different job; hard-filter violations; and duplicates. A saved minimum_base screens guaranteed annual base pay only. A saved minimum_annual_earnings screens comparable annual cash earnings from wages, tips, commission, and recurring cash bonuses. Equity and benefits never count toward either floor. Unknown or unposted pay stays unverified.
Every successfully fetched posting-specific URL must be accounted for in the same JSON reply. Keep it in roles[], or put that exact URL in rejected_postings[] with one short factual reason such as expired, wrong role, wrong location, duplicate, or below a hard requirement. Never silently drop a fetched exact posting. rejected_postings[] is bounded to the eight-fetch turn limit. If the server asks for a correction because a fetched URL is missing, do not run WebSearch, WebFetch, or any other tool again; return the complete corrected JSON only.
Score every posting you keep using the STEP 3 — Coarse triage rules above, verbatim — the same fitScore/fitBucket/fitBasis/ruleFlags/one-line-reason shape, no new rules invented here. Score against the candidate context object in the kickoff input (role buckets with their fit/down signals, top-level keep_signals/cut_signals, excluded companies, comp floor, location posture, work authorization) rather than reading candidate/targeting.yml directly — candidate/targeting.yml, candidate/profile.yml, and the learnings inputs STEP 3 also lists are not reachable in this mode (no CLI, no tracker read). The candidate context object additionally carries compact application_limits[] ({company, status, reapply_after}, only companies with a caution/blocked status) and company_history[] ({company, flags}, flags drawn from active/recent-rejection/prior-sourced) summaries when the server had tracker data to build them — use those directly to apply app-limit-* and company-history-*, the same way STEP 3 does from a live tracker read. oe-candidate still requires you to confirm all three of its conditions from the posting itself plus the given candidate context. If a flag's underlying data isn't present in the context (an empty or absent application_limits/company_history, or no learnings), omit that flag rather than guessing.
Skip: everything that writes. No workspace/jobs/*.md, no config/search-sources.yml watermark, no careerrat activity append, no tracker write, no evaluate-job handoff. The server that invoked this run validates your JSON reply and persists survivors itself — this mode never touches disk or the tracker directly.
Finish with exactly one fenced ```json block matching config/ai-web-search.schema.json and nothing else — no prose before or after the fence, since the server is a machine reading exactly that one block. Shape:
roles[]— one entry per posting kept, each withcompany,title,url, nullablecomp_text, nullablebase_comp_text, nullableannual_earnings_text,fit_score,fit_bucket,fit_basis,rule_flags, andsource_evidence(required), plus whichever oflocation,posted_at,body_text, andbody_partialyou actually have. Put guaranteed base pay only inbase_comp_text; put annual cash earnings including quantified tips or commissions only inannual_earnings_text; usecomp_textonly for compensation that can't be assigned safely to one basis. Always return all three compensation keys, usingnullwhen the posting doesn't supply that basis.source_evidenceis the concise factual reason this specific result is credible and relevant, not a guessed JD. Usebody_partial: truewheneverbody_textis absent or incomplete.rejected_postings[]— up to eight successfully fetched exact posting URLs that are not inroles[], each as{url, reason}. Use the exact fetched URL and one short factual reason. Return an empty array when every successful exact fetch is kept or no exact posting was fetched.queries_run[]—{prompt_id, query, status, error?}for everyWebSearchcall you actually ran, so the server can report exact search coverage back to the user. Usestatus: "completed"when the query returned normally. Usestatus: "failed"and a short factualerrorwhen the search call failed; never hide a failed query or report it as completed.
STEP 0 — Prerequisites
Check adjacency config first. Run careerrat doctor (or read candidate/targeting.yml and candidate/profile.yml) and look for a "Targeting is missing adjacency config" note: no non-primary role bucket and no role_families, or no profile.location.commute_cities for a hybrid or on-site candidate. Targeting saved before title lanes shipped usually lacks all of it, and a scan without it drops related titles and nearby towns without saying so. When it is missing, do not scan yet. Propose the additions yourself from the candidate's field, following the ingest-profile instructions (secondary bucket of adjacent titles, role_families, seniority ladder and ceiling on the primary bucket, commute cities), show them to the candidate, and save only what they confirm. If they decline, scan anyway; the scan summary will say it ran without adjacency config.
Read all gate files before touching anything else:
candidate/targeting.yml—role_buckets,keep_signals,cut_signals,excluded_companies,fit_bands,degree_policycandidate/profile.yml—compensation.minimum_base,compensation.minimum_annual_earnings,location.*,candidate.domain— used for guaranteed-base or annual-cash floor triage. Annual cash earnings may include wages, tips, commission, and recurring cash bonuses, but never equity or benefits. Do not read or usecompensation.current_basefor any purpose in this skill.- Application limits — in DB mode read
careerrat data candidate get --json(application-limits.companies[]); in legacy mode readcandidate/application-limits.yml. Build a blocked/capped company set now so the scan can flag them at triage time. workspace/tracker.json— existingapplications[]andsourced[]. Build company-history sets now: active applications, recent rejections, prior cuts/closed sourced rows, and exact req/company-role duplicates. Company history is not the same as an application-limit block, but it must affect warnings and priority.- For a classifiable role, read its learnings via
careerrat learnings read "<role>"— the helper resolves the family from targeting.yml and skips silently when no file exists. Improves triage scoring. candidate/modes.yml— optional. Runcareerrat modes status; absent =usage_mode: standard,application_mode: balanced.- Source config — in DB mode use CareerRat commands/scan output as the canonical view; in legacy mode read
config/search-sources.yml(searches[], per-sourcelastRunAtwatermarks,recency.postFilterAfter).
Run careerrat doctor and confirm it exits clean. Read the Discovery pipeline
section before scanning. The post-onboarding order is:
setup-searches -> research-boards -> discover-companies -> search-jobsIf doctor says the next discovery step is setup-searches, research-boards, or
discover-companies, run that owning skill first during an automatic pipeline handoff.
When the user explicitly asked to search and at least one enabled source exists, their
request already authorizes a partial sweep of the configured sources. Run it without a
second override question. If source config is missing or has no enabled entries, run
setup-searches as part of the same request, then continue the sweep without another
handoff. A disabled login-backed source is still actionable: start the sweep so its
contextual Yes/No login question appears. If setup still produces no runnable source,
settle honestly with the setup recovery instead of inventing a permission gate:
Available portals: the baseline auto-seeds domain-appropriate sources, and
careerrat searches --providerslists all 77 public deterministic adapters.setup-searchesauto-detects recognized pasted board URLs and supports explicit adapter selection for branded hosts.
careerrat searchesIf sources are present but haven't been derived from targeting yet, optionally rebuild:
careerrat searches --from-targetingPrivacy gate: profile.compensation.current_base is private. It must not appear in any scan output, intake file, tracker note, or JD frontmatter produced by this skill. Use minimum_base for guaranteed base and minimum_annual_earnings for annual cash from wages, tips, commission, and cash bonuses. Equity and benefits do not clear either one.
Mode gate: discovery stays broad/recall-oriented. application_mode affects how scanner
ratings are promoted after scoring (high-volume queues more medium fits; selective
keeps medium fits in review), not which plausible roles are discovered. Before a broad
multi-source sweep, run:
careerrat modes allows search:sweep:broad --explicitUse --explicit when the user asked for this search. Their request authorizes this one
run and must not trigger another override question or change their saved usage mode. For
an automatic or background sweep, omit --explicit. If the verdict is downshift, run
fewer enabled sources or a narrower recency window. If it is run, proceed normally.
STEP 1 — Full sweep
In a terminal workspace (CAREERRAT_SURFACE=tui) with an existing database,
start or reuse the configured-source scan with careerrat search start --json.
Keep its exact returned run ID and continue the conversation while the worker
runs. Inspect careerrat search status --id <run-id> --json for progress and
completion. On completion, read the handoff and its complete resultPath JSON,
including all offers[]; don't substitute the bounded TUI summary for the result.
If the user cancels, use careerrat search cancel --id <run-id> --json and retain
any saved partial results. Source errors and login requests need honest follow-up.
Status and the saved handoff carry a health block (ok, degraded or failed)
with failed and skipped source counts and the error reasons grouped by count. A
completed run with degraded or failed health is not a success: say so in plain
words, give the counts and the top reasons, and then work from the partial results.
Sources that can't run in the terminal (browser-only, or login-backed with no session)
are left out before the run, so they never produce error rows or count toward the
failed share. The summary carries notSearchable (count plus sources[] with a
label and reason), and health.notSearchable has the count. List them once as "not
searchable from the terminal" with the reason; they don't mean the network is broken.
If every source was non-runnable, health is failed and says nothing was searched.
A source whose URL answers 404, or whose board an ATS says doesn't exist, is dead. The
summary carries deadSources (count plus sources[] with label, kind, url, reason
and action), and the terminal summary lists them under "Dead sources". They stay in
errors[] too. Tell the user which ones and the next step: remove the source, or re-resolve
the company's board. Nothing remembers a dead source between runs yet, so it will show up
again until it's removed.
Sources that need a free API key (USAJobs: USAJOBS_API_KEY and USAJOBS_USER_AGENT;
Adzuna: ADZUNA_APP_ID and ADZUNA_APP_KEY) read it from the environment CareerRat runs in.
With the key missing, that source's error row names the variables and the signup page. Say
so plainly and point the user at careerrat searches --providers, which shows which keys are
set. Don't treat it as a network failure and don't ask the user to paste a key into chat.
Don't start a second foreground scan while the same worker is active. Additional
agent-led search and AI Web Search still follow this skill's owning sections.
The commands below remain the legacy/foreground entry, with no implicit migration.
Run the full sourced sweep against all enabled sources since their lastRunAt watermarks:
npm run scan:sourced -- --write --verifyThis dedupes against existing tracker sourced entries and workspace/jobs/, checks liveness,
captures JD artifacts, and writes sourced rows through the canonical write path. In DB mode,
--write uses DB verbs and exports the generated tracker files; agents must not hand-edit
canonical tracker state or source YAML. Consume the complete structured JSON result from stdout,
especially offers[]: it is not presentation-truncated and carries each canonical sourced-row
id, artifacts.jd, fitScore, fitBucket, ruleFlags, and ratingReason. The scanner does not
generate a parallel Markdown intake queue.
For a targeted rescan of a single company:
npm run scan:sourced -- --company "<Company>" --write --verifyPrint the run summary: sources scanned, new entries, filtered, duplicates, expired, errors.
JS-rendered or login-gated boards: if a source returns nothing (or returns only partial listings) because the board requires a login or heavy client-side rendering, the normal scan path will not reach its content. In that case reach for the capture scripts instead:
npm run capture:board -- --ingest # capture one board page and ingest offers in DB mode
npm run capture:search-sources -- --ingest # capture configured source pages and ingest offers in DB modeThese drive the bundled browser session (Layer 2 per docs/BROWSER.md). In DB workspaces,
--ingest writes parsed offers through the SQLite sourced-row path and captures each JD body
into workspace/jobs/*.md with artifacts.jd mirrored onto the row. Without --ingest, they
are snapshot-only diagnostics/fallback artifacts. Use them as a manual fallback, not a first step.
Login-backed browser sources
Sources with source_type: "browser", auth: true, and a platform field use that site's saved browser session. There is no separate search permission matrix.
When an enabled source reaches a login wall, ask exactly one contextual question in chat: “Do you want to log into LinkedIn so I can use it?” Render Yes and No choices and accept the same words as text. Yes opens the source's exact saved-search URL in the visible CareerRat browser. No skips that source and continues the rest of the sweep. Keep the decision durable so navigation does not duplicate the prompt or lose the running search.
For a disabled authenticated source the user explicitly asks to use, ask the same question at that point, then enable only that source on Yes. Do not redirect the user to Settings and do not require capability, platform, terms, or consent switches.
After the session is ready, scrape via the session browser.
Navigate to the source's saved-search URL in the session browser (Layer 3 per
docs/BROWSER.md). Keep the provider on auto unless the user explicitly changes it;
CareerRat resolves the current session browser and reuses its signed-in session.
Snapshot or read the current page state before each action — never rely on hardcoded
selectors. Drive the live DOM turn-by-turn.
Scrape the visible postings (title, company, URL, posted date where available), then open each exact posting in that same session and capture the full visible JD before leaving the authenticated browser path. Preserve an unreadable but posting-specific result as bodyPartial: true for later Evaluate; drop it only when its URL is unsafe or the page reaches an auth challenge. Feed every scraped posting through the same existing pipeline this skill already uses for other sources: intake → dedupe against tracker and workspace/jobs/ → liveness check → coarse triage (STEP 3) → JD save (STEP 4) → watermark (STEP 5). A session-captured full body is already canonical input and must not be fetched again over public HTTP. Do not invent a parallel pipeline.
LinkedIn URL-filter recipe (keep each saved search to ~1 page). Encode the candidate's hard gates directly in the saved-search URL so the platform pre-filters server-side and you read one page per keyword instead of paging through noise. Build/maintain the url: of each platform: linkedin source in source config from these query params:
keywords=%22<phrase>%22— URL-encode the quoted phrase for an exact-title match (drop the quotes only when you deliberately want a broad net).f_TPR=r<seconds>— time-posted window.r86400= 24h,r604800= 7d,r2592000= 30d. Set this to track the run cadence: tight (24h) for a daily sweep so each term returns ~1 page; widen it if the source is run less often, or you'll miss postings between runs.f_SB2=<band>— salary-band floor. The band is an integer where each step is ~$20k (…7≈$160k+,8≈$180k+,9≈$200k+). Derive the band from the candidate'sprofile.yml#compensation.minimum_base, never hardcode a figure — pick the band whose threshold equals (or is the nearest at-or-below)minimum_base. This mirrors the same comp floorevaluate-jobenforces, so below-floor roles never reach triage.sortBy=DD— sort by date, newest first, so the freshest postings are at the top of the single page.location=<area>/geoId=<id>— geography; match the candidate's location constraints.
Verify the salary-band integer renders the expected floor on the live page before trusting it (LinkedIn occasionally renumbers bands). When a term still returns multiple pages after these filters, tighten f_TPR rather than paging.
Safety: halt immediately and ask the user if you encounter a captcha, a 2FA prompt, a login wall, or any unexpected interstitial. Never attempt to bypass an auth challenge. Keep all scraped pages and screenshots under workspace/ only. Once the user enables a source, it participates in normal searches like every other enabled source.
Indeed through the official connector (only when already connected)
Indeed's own MCP connector is the only sanctioned way to read Indeed beyond the saved browser source. It is in beta and available only through Claude connectors, so treat it as optional and never as a requirement.
- Use it only when it is already connected in this session. Check the tools you were actually given for an Indeed connector. Do not ask the person to install or connect it, do not walk them through setup, and do not fall back to scraping, a headless browser, JobSpy, or any unofficial Indeed API when it is missing.
- When it is absent, skip it without comment mid-run, but note it. Continue the sweep with the other sources and add one line to the run summary: "Indeed connector not connected; skipped." A missing connector is not an error and never makes the sweep
failed. - Never read the person's Indeed résumé without saying so first. The connector can expose the résumé stored on their Indeed account. Searching postings does not need it. If a step would read that résumé, tell the person what you are about to read and why, and wait for a yes. Without a yes, search postings only and do not open the résumé.
- Postings go through the same pipeline. Each result is intake, dedupe, liveness check, coarse triage (STEP 3), JD save (STEP 4) and watermark (STEP 5), like every other source. Record the source as the Indeed connector. Anything the connector returns that you did not need (profile fields, résumé text) stays out of the workspace unless the person said to import it.
STEP 2 — Incremental delta (if a prior snapshot exists)
If a previous snapshot exists for a source, run the delta to extract only net-new entries not already in tracker or workspace/jobs/:
npm run delta:sourced -- --source <provider> --repo-new-only --writeOutput: workspace/intake/delta-<source>-<date>.md.
Cold start (no prior snapshot for the source): the delta command will error because there is no baseline to diff against. Run the cold-start variant instead:
npm run delta:sourced -- --source <provider> --repo-new-only --write --baseline-ok--baseline-ok tells the scanner to treat the current state as the baseline rather than erroring. Use this once per source on first run; omit it on all subsequent incremental runs.
STEP 3 — Coarse triage on every new sourced entry
The scanner (STEP 1's npm run scan:sourced) already scored every sourced entry. scoreSourcedOfferFromConfig ran against candidate/targeting.yml and profile.yml#compensation.minimum_base, and its fitScore/fitBucket/ruleFlags/ratingReason are present in the returned offer and persisted sourced row. Read those stored triage fields; do not recompute them or re-derive the scanner's own flags (comp-below-floor, excluded-company, comp-unposted, top-of-band-only, family-cold) from scratch.
For each sourced entry, still add the flags below that the scanner has no way to compute — it never reads the tracker, application limits, or learnings at scan time:
learnings/<role-family>.md— viacareerrat learnings read "<role>"when the sourced role's family is classifiable; skips silently if no file exists. AdjustratingReason(not the storedfitScore) with what it says.- application limits — blocked/capped companies
Emit per-entry, starting from the stored fields and adding only the agent-derived flags:
fitScore: <read from the scanner result or persisted sourced row>
fitBucket: high | med | stretch # high ≥ 85, med ≥ 65, stretch < 65 (targeting.fit_bands; default 85/65)
fitBasis: "triage" # marks as pre-read estimate; evaluate-job overwrites with "evaluated"
ruleFlags: [<the scanner's stored flags, plus any agent-derived flags below>]
ratingReason: "<the stored one-line reason, extended with any agent-derived signal>"Rule flags already written by the scanner (read, don't recompute): likely-cut (matches a cut_signals entry), comp-below-floor, excluded-company, comp-unposted, top-of-band-only.
Rule flags the agent adds at triage time — the scanner cannot see this data:
possible-duplicate— title+company match an existing tracker rowcompany-history-active— the same company has an active application (awaiting,screen,interview,blocked, or equivalent non-terminal status)company-history-recent-rejection— the same company has a rejection or pass inapplications[]within the last 90 days, unless application limits define a different cooldown windowcompany-history-prior-sourced— the same company has prior sourced rows, cuts, or closed/404 entries that may affect prioritizationoe-candidate— ALL THREE conditions must hold: (1) the posting is fully remote (no required onsite days), AND (2) posted comp falls withinprofile.compensation.oe_min_base–profile.compensation.oe_max_base(both from foundations-spec §2; if either is null, the OE range is unconfigured — skip the flag), AND (3) the best-matchingrole_buckets[]entry haspriority: oe. If any condition fails, do not apply the flag. The scanner does not flag OE itself — applying this three-part check at triage time is an agent behavior (the scanner stays a coarse pre-screen, not a comp gate).app-limit-blocked— company has an active application-limit blockapp-limit-caution— company is approaching its application-limit cap
A coarse honest estimate beats no fit at all. Closed or expired postings get status closed and are not queued.
Company-history handling: exact req/URL duplicates and exact company+role duplicates are dedupe hits; update/skip the existing row instead of adding a new one. Different roles at a previously applied company may be kept as prospects, but never treat company history as invisible. Add the relevant company-history-* flag, carry a concise warning into the intake/tracker note, and require evaluate-job to own the final manual/apply-now decision. If the company has an active app or recent rejection, search triage must not label the role apply-now; use manual until the body-read gate reviews the history.
STEP 4 — Save the JD body
For each sourced entry not cut outright (i.e., not excluded-company or app-limit-blocked), save the full JD body — the durable copy that outlives the live posting (see the JD-body capture invariant in AGENTS.md). A saved URL is not enough: reqs close and login sessions expire, so capture the text now while it's reachable.
- If
workspace/scan-results/sourced-<date>.jsonalready has the body text, use it. - If the body is missing from the snapshot, try
WebFetchon the posting URL first. If the response is empty, truncated, login-walled, or clearly JS-rendered (no meaningful role content), escalate to the session browser: render the page and readdocument.body.innerText. The session browser holds the user's existing logins, so it reaches login-gated postingsWebFetchcan't. Keep the provider onauto; CareerRat resolves the current session browser. Seedocs/BROWSER.mdfor the full escalation ladder. Do not invoke the browser on every posting — only whenWebFetchreturns insufficient content. Treat aWebFetchfailure as "escalate to the browser," never as "the posting is gone."
Write to workspace/jobs/<company>-<slug>.md with frontmatter:
---
company: "<Company>"
role: "<Title>"
reqId: "<req-id or empty>"
source: "<source name from search-sources.yml>"
postedAt: "<ISO date or empty>"
fetchedAt: "<ISO date>"
status: sourced
url: "<posting URL>"
---Sourced-role lifecycle: every new posting written here is simultaneously added to (or confirmed
in) sourced rows with status: "sourced": through DB verbs in DB mode, or
workspace/tracker.json sourced[] in legacy mode. That is the ungated, pre-evaluation state.
The gate that advances or cuts the role runs in evaluate-job.
Validate the file against config/job.schema.json. One file per posting/req — consolidate location-clone duplicates to a single file.
STEP 5 — Write the watermark
After the sweep completes, ensure lastRunAt is updated for each source that ran. Without this,
the next invocation is not incremental. In DB mode, the scan/write path owns source watermarks in
SQLite and exported files are generated artifacts; do not hand-edit YAML. In legacy mode only,
update config/search-sources.yml directly if the scanner did not already write the watermark.
For each legacy source that needs a manual watermark:
- Read and print the current (before)
lastRunAtvalue:searches[id=<source>].lastRunAt(print it so the write can be confirmed). - Edit
config/search-sources.ymldirectly — setlastRunAtto the ISO timestamp of this run. - Print the new (after)
lastRunAtvalue as confirmation:Written lastRunAt for <source>: <before> → <after>.
Then run careerrat doctor to confirm the file still validates.
STEP 6 — Gate write-back (if user stated a new gate mid-session)
If during this session the user said something like "skip <Company> from now on", "add <signal> as a cut", or "cap me at N apps to <Company>", persist it through the owning DB-aware command now. A stated gate must never live only in chat.
| What the user said | Command |
| "skip / never / exclude <Company>" | careerrat gate exclude-company "<Company>" --write (applies directly with an Undo) |
| "add <signal> as a cut signal" | careerrat gate cut-signal "<signal>" --write (write-and-report if unambiguous) |
| "cap <Company> at N apps" | careerrat data candidate limits upsert --data '<json row>' in DB mode (per-company caps/cooldowns); legacy mode routes to configure — never hand-edit candidate/application-limits.yml |
| "below $X is a no" | careerrat gate comp-floor <N> --write (add --confirm only when lowering an existing floor, after the user says yes) |
| "I need to make $X a year including tips/commission" | careerrat gate comp-annual-floor <N> --write (add --confirm only when lowering an existing floor, after the user says yes; excludes equity and benefits) |
After writing, echo the CLI's confirmation. careerrat gate writes SQLite in DB mode and legacy YAML only in legacy mode; never hand-edit candidate/*.yml.
STEP 7 — Optional: hand top sourced roles to evaluate-job
[DELEGATE: subagent] When several high-fit roles qualify, fan out the body-read gate —
one subagent per role (cap ≈5). Each runs evaluate-job's read-only gate (fetch JD, body-read,
emit the GATE/FIT/COMP/ACTION block) and returns the verdict; it does NOT write the
tracker. The orchestrator applies evaluate-job STEP 9 (the sourced-row fitScore/status
write-back) serially through the canonical write path (careerrat data in DB mode,
the legacy tracker writer otherwise), so there is one writer of canonical tracker state. WebFetch-able JDs
parallelize; JS-portal JDs that need the session browser serialize (one-browser rule).
Degrade to inline sequential gating with no subagent primitive. See the Delegation
Contract in AGENTS.md.
Hand each subagent the STEP 0 digest instead of a re-read. This orchestrator already
loaded the full parsed contents of candidate/targeting.yml and candidate/profile.yml,
the application-limits blocked/capped company set, and the tracker company-history sets
(active applications, recent rejections, prior cuts/closed rows) at STEP 0. Include that
digest directly in each subagent's dispatch prompt — trimmed to the posting's own company
for the company-history slice — so evaluate-job's STEP 2 reads it from the prompt rather
than opening those same files again in a fresh context. candidate/honesty.yml and any
role-family learnings/ file are not part of the STEP 0 digest (this skill never loads
them); each subagent still reads those itself, along with the live JD fetch.
For each sourced entry with fitBucket: high and no excluded-company / app-limit-blocked / likely-cut flag, offer to run evaluate-job for a full body-read gate:
careerrat evaluate workspace/jobs/<company>-<slug>.mdExit 0 = KEEP, exit 2 = REVIEW, exit 1 = CUT.
Do not promote any sourced entry to tracker application state without an evaluate-job GATE: KEEP verdict. The required gate output format is:
GATE: KEEP|CUT|REVIEW - reason
FIT: high|med|stretch <score> - why | caveats: ... | priority: ...
COMP: clear|review|below-floor|OE-bucket - reason
COMP ANCHOR: <expected salary to state> - <rationale>
ACTION: apply-now|hold|manual|cutSTEP 8 — Validate
Run tracker integrity after any sourced additions:
npm run verify:trackerReport the summary. List any issues found. Snapshot tracker state:
careerrat trackerThen log the source run to the Activity Pulse feed (the dashboard's live timeline — see Activity Pulse in AGENTS.md). One summary event per source run, not per role:
careerrat activity append --type sourced --actor agent \
--title "Sourced <N> roles — <source>" --summary "<one-line triage note, e.g. 'M passed coarse triage'>" \
--tag "<source>" --writeScope boundary
search-jobs owns discovery, coarse triage, JD save, and intake. It does not:
- tailor resumes
- fill or submit applications
- promote a sourced entry to application state without a GATE: KEEP from
evaluate-job
The body-read gate is mandatory and lives in evaluate-job.
Final handoff
End every run with the next agent task. If high-fit sourced roles were found, hand
off to evaluate-job for the top roles before any application work; if there are
KEEP verdicts ready, hand off to apply-job. If the sweep is dry or only returns
known companies, hand off to research-boards or discover-companies to expand
coverage before another refresh.
Rules — authenticated browser sources
- One point-of-use choice. Ask the site-specific Yes/No login question only when that source needs it. Yes opens that source; No skips it while the sweep continues. Never replace this with a Settings checklist.
- Same pipeline, no parallel track. Postings scraped from authenticated sources flow through the same intake → dedupe → liveness → triage pipeline as every other source. No special path.
- Capture while the session can read it. Open each exact result in the same session and carry its full visible JD into persistence. Never throw that body away and try to recover a login-only posting over public HTTP.
- Visible auth challenges stay with the user. Ask the point-of-use Yes/No question for a login wall. Stop for CAPTCHA, 2FA, or an unexpected account-selection/interstitial screen. Never bypass them.
- Local-only. Scraped pages and screenshots stay under
workspace/. Nothing goes outbound. - Tool-agnostic browser prose. Keep the provider on
autoand use the available session browser. Never ask the user to choose a CLI, extension, or browser driver, and never name an MCP namespace or vendor tool. - Domain-neutral. No hardcoded platforms beyond what source config defines. No bracketed placeholder tokens — if a detail is unknown, omit or go generic.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

