Company Talent Economics

Company Talent Economics

Operating procedure (follow this literally)

Every run is a directory with a fixed set of files and ten numbered phase gates. Do not skip gates, do not write report.json by hand before Phase 8, and do not present anything before Phase 10 passes. $SKILL below means the folder containing this file.

python $SKILL/scripts/init_run.py "<company>" --out ./talent-economics/<slug> --year <FY> \
       [--jurisdiction <code>] [--language <tag>] [--threshold N --currency ISO]
python $SKILL/scripts/check_phase.py ./talent-economics/<slug> --next     # prints the exact steps for the next phase
# ... do the steps ...
python $SKILL/scripts/check_phase.py ./talent-economics/<slug>            # verifies the gate; on pass prints the next phase

Repeat check_phase.py until PHASE 10 GATE PASSED. If a gate fails, fix only what it lists, then rerun. The gate output is the authoritative to-do list; the rest of this file explains why.

--jurisdiction and --language are inferred from the company name when omitted, and both are recorded in run.json. Confirm them at Phase 0 — changing either later means recompiling and re-rendering.

Files the harness creates and what you must do with each:

Rules that the scripts cannot check for you:

1. A search snippet is never a source. Fetch the filing, read the section, then write the number.
2. Anything from a forum or salary-crowdsourcing site is Tier E and can only appear as calibration only.
3. Never invent a number to satisfy a gate. Leave it null and write NOT AVAILABLE: <fact_key> - <what you searched> in the notes. For an unlisted entity that passes the Phase 1 gate and marks the whole run provisional; the report then says so on its cover and no figure in it may be presented as measured.
4. When unsure which default to use, take it from assets/defaults.json or assets/jurisdictions.json and say so in the notes.
5. Use the words in references/glossary.md, in the language you are writing in. A company has articles/charter, never a "constitution". TC is pre-tax and includes annualised vested equity.

Language: follow the company name

Write the report in the language of the company name the user typed. ソニーグループ gets a Japanese report; Siemens AG gets a German one; 小米集团 gets a Chinese one. If the user wrote their request in a different language from the company name, the user's language wins — they are the reader. Speak to the user in that language too, not only in the PDF.

init_run.py resolves this and records it in run.json -> language; every later script reads it from there. Explicit --language beats $CTE_LANG, which beats detection from the name.

Read references/localization.md before Phase 0. The two things it settles:

• Detection confidence. python $SKILL/scripts/i18n.py detect "<name>" reports high / medium / low / ambiguous. On low or ambiguous — plain Latin names, or a legal form like S.A. that four languages share — do not silently default to English. Use the language the user wrote in; if that is also unclear, ask once, in one line.
• Any language works. Twelve languages have a locale pack for the report's structural labels (en zh-CN zh-TW ja ko es fr de pt it ru ar). Any other language still gets a full report in that language, with the structural labels falling back to English and a note printed. Adding a pack is one JSON file: python $SKILL/scripts/check_locales.py --new <tag>.

Search in two languages, always: filings are indexed under their local names, cross-border coverage under English ones. search_plan.py does this automatically.

Do not translate the company's own words. Native titles, level names, segment names and charter terms stay in the original language with a translation in parentheses on first use.

Country: route by jurisdiction, not by assumption

assets/jurisdictions.json holds 49 jurisdictions with filing venues, local document names, registries, currency, a default high-pay threshold and an employer social-contribution rate.

python $SKILL/scripts/i18n.py jurisdictions          # list every code
python $SKILL/scripts/i18n.py jurisdictions japan    # one entry in full; aliases resolve

Two of those fields are priors, not facts, and every override belongs in analysis_notes.md:

• threshold_default is the round local number that reads as "high earner" in that market (CNY 1,000,000, JPY 20,000,000, USD 250,000, INR 10,000,000). It is not a statistical cut-off and is not comparable across countries at market FX. A user-supplied threshold always wins.
• employer_social_rate ranges from roughly 1% (Denmark, funded through income tax) to roughly 32% (Spain). Applying the wrong one silently breaks the payroll envelope. Use the disclosed number whenever the filing gives one.

An unmapped country routes to other: find the national registry and securities regulator first, then run the generic six-pass plan. Read references/jurisdiction_playbooks.md for what each regime is unusually good at and where it misleads.

Analyze talent as part of the company's economic system, not as a generic salary benchmark.

The central causal chain is:

business model -> profit pools -> critical processes -> critical roles -> org/level structure -> market replacement cost -> compensation distribution -> promotion/hiring paths

A title is not a salary. Two people at the same nominal level may rationally receive very different compensation if they control different profit pools, customer relationships, technical bottlenecks, or scarce capabilities.

Default scope

If the user gives only a company name:

• analyze the most recent public information available;
• use the company's main operating geography, but segment materially different geographies;
• define total compensation (TC) as base salary + expected cash bonus/commission + annualised vested equity value, pre-tax, in the reporting currency; state the equity price basis (grant-date or report-date);
• separately show cash TC and equity-inclusive TC when equity is material;
• take the high-compensation threshold from assets/jurisdictions.json for that jurisdiction (a round local-currency number that reads as "high earner" there), state it explicitly on the cover, and let any user-supplied threshold override it; in a high-inflation economy state the FX date or quote in USD;
• include employees and executives, exclude founders from employee-distribution statistics unless the user asks otherwise.

Non-negotiable rules

1. Use only public, legally accessible sources. Never bypass login walls, CAPTCHAs, robots restrictions, or access controls.
2. Prefer official filings, prospectuses, annual reports, exchange filings, company job postings, and formal compensation/equity disclosures.
3. Public professional profiles may be used to infer aggregate role taxonomy and career transitions, never a private person's exact pay.
4. Tag every claim in the evidence ledger with a canonical key: observed_fact, derived_metric, assumption, inference or reconstruction. Write those same English keys into report.json; render_report.py prints the label for the report's language (披露 / Disclosed / Offengelegt / 開示 ...). validate_bundle.py accepts either form in report.json and only the canonical key in evidence.jsonl.
5. Never present inferred company-wide counts or promotion probabilities as exact. Give ranges and confidence.
6. Do not equate title with level without evidence. Maintain company-native titles and a separate normalized latent-role representation.
7. Do not infer compensation solely from market salary sites. Company economics and internal pay capacity are separate constraints.
8. If evidence is weak, widen intervals and report the missing evidence that would most reduce uncertainty.
9. Use the terminology in references/glossary.md, in the language you are writing in: use that language's accounting and corporate-law term, never its colloquial one. A company has articles/charter (章程 / Satzung / statuts / 定款 / 정관 / устав), never a "constitution"; employee benefit expense is not take-home pay; a grant is not a vest; observed transition shares are not promotion probabilities.
10. Cite fetched primary documents, not search snippets. A snippet is a pointer to a document that must then be read.

Final deliverable contract

The default user-facing artifact is report.pdf, not raw Markdown.

Always build the analysis in an auditable structured form, then typeset it:

• analysis_notes.md - the written-out reasoning chains (see references/reasoning_chains.md) with intermediate numbers; produced before report.json;
• report.json - structured report model used by the renderer;
• evidence.jsonl - claim-level evidence ledger;
• source_manifest.csv - every source searched/used, with date and source type;
• model.json - headcount/TC assumptions used by estimators;
• career_transitions.csv - observed public-profile transitions when used;
• report.pdf - final polished deliverable.

The final PDF must not be generated by directly converting Markdown. Populate report.json using assets/report_spec.json (including meta.language), run scripts/validate_bundle.py <dir>, then run scripts/render_report.py report.json -o report.pdf. The renderer builds a typeset DOCX internally and converts that document to PDF, choosing section titles, table headers, number formatting, fonts and text direction from meta.language. Keep the DOCX only when explicitly requested with --keep-docx.

Before delivery, visually inspect the rendered PDF: clipped tables, tofu boxes where the script's font is missing, orphaned headings, pagination. For Arabic and Hebrew, confirm the mirrored layout actually rendered. render_report.py warns on stderr when no installed font covers the report's script — install the font rather than shipping boxes.

Company-type routing is mandatory

Before searching compensation data, read references/company_type_router.md and classify the entity. The source plan must change by company type. Charter and control-structure sources are a separate workstream (Pass 1), not an optional appendix.

For historical charters, use one of three statuses:

• original - actual charter/articles/amendment obtained;
• official_summary - official filing describes the terms but original document is not attached;
• reconstructed - terms inferred from later prospectus/legal opinion/registry history.

Never present reconstructed wording as original charter text.

Required output

Produce these sections unless the user requests a narrower analysis:

1. Executive estimate — workforce, median/upper-tail TC, employees above threshold, confidence.
2. Charter and control structure — legal form, share classes, founder economic ownership vs voting power, board control, charter document status.
3. Business economics — revenue, gross profit, operating profit, major segments/profit pools, customer concentration, payroll/R&D/sales intensity.
4. Profit-pool → role dependency map — which processes and roles appear to create, defend, or unlock each profit pool.
5. Organization map — functions, business units, management layers, IC/manager tracks, native levels where observable.
6. Compensation distribution — cash and equity-inclusive TC by function x level x geography, with p25/p50/p75/p90 or defensible ranges.
7. High-compensation population — estimated count and share above threshold, decomposed by bucket.
8. Role pay bands — for economically important roles, show market replacement band, economic-justification band, and recommended/defensible overlap.
9. Career graph — observed internal promotions, external-entry routes, typical tenure between states, and the first states that usually cross the target TC.
10. Equity incentives & talent capital allocation — equity incentives, dilution, share-based compensation, executive pay, and who receives ownership.
11. Evidence & uncertainty — source ledger, confidence, sampling biases, and sensitivity.

Workflow

Phase 0 — Resolve the entity, language and jurisdiction

First confirm the three fields init_run.py inferred, because everything downstream depends on them:

• run.json -> language — the language you will write in. Inferred from the company name; if the user wrote to you in another language, theirs wins. Fix it now, not at Phase 10.
• run.json -> jurisdiction — decides which filing venues Phase 1 searches. python $SKILL/scripts/i18n.py jurisdictions <code> shows what that maps to.
• run.json -> currency and threshold — priors from the registry. State the threshold on the cover; a user-supplied one always wins.

Then identify:

• legal entity and major subsidiaries;
• listed ticker/exchange if applicable;
• private/public status;
• jurisdiction;
• reference date;
• relevant business units and geographies.

Do not mix parent-company and subsidiary headcounts or compensation without labeling them.

Classify the company using references/company_type_router.md before launching the search plan. Record the legal form, listing venue, issuer domicile, operating entity, share classes, and whether historical charter documents are expected to be publicly available.

Phase 1 — Six-pass public-source search

Read references/source_playbook.md, references/jurisdiction_playbooks.md, and references/company_type_router.md.

Use whatever web tools the host agent exposes (Claude Code: WebSearch / WebFetch; Codex: built-in web search) to run a structured search, not a single query. Fetch primary filings in full rather than relying on search snippets. Run six separate search passes with the stop rules in references/source_playbook.md: (1) identity & charter, (2) business economics, (3) workforce & payroll, (4) compensation & equity awards, (5) organisation & critical roles, (6) career transitions. scripts/search_plan.py <company> --jurisdiction <code> --year <FY> prints the query ladder: venue-scoped site: queries built from that jurisdiction's filing venues and local document names, plus six passes of queries in the run's language and in English. Search both sides — filings are indexed under their local names, cross-border analyst coverage under English ones. For each pass, search → identify the primary document → fetch it in full → extract numbers with unit, period and page. Search across:

• official filings / annual reports / prospectus / ESG reports;
• investor relations and exchange disclosures;
• company careers pages and current job postings;
• executive biographies and organization announcements;
• equity-incentive and share-based-compensation documents;
• reputable compensation databases and public recruiting ranges;
• public professional histories for aggregate transitions;
• reputable media only for facts not available in primary sources.

Create evidence.jsonl matching schemas/evidence.schema.json and a source_manifest.csv. The manifest must record sources that were searched but unavailable when that absence matters (for example, an early private-company charter).

When a required figure genuinely is not public — normal for unlisted entities, where gross profit and the payroll line are often never filed — leave it null and write in analysis_notes.md:

NOT AVAILABLE: <fact_key> - <the venues and queries you actually searched>

Use the run.json key as <fact_key> (revenue, gross_profit, employee_benefit_expense, headcount). For an unlisted entity the Phase 1 gate then passes and marks the run provisional: compile_report.py forces the report's confidence to the locale's provisional wording and prints a cover note naming what was missing. You still need revenue or headcount — without either there is no scale anchor, and no company-wide distribution may be produced at all. This is a label for honest uncertainty, never a licence to invent the missing number.

Continue searching until each critical output has at least one strong source and major estimates have a cross-check, or until no additional public source is likely to materially reduce uncertainty.

Phase 2 — Reconstruct company economics and the payroll envelope before salaries

Read references/company_economics.md and write Chains 1 and 4 of references/reasoning_chains.md into analysis_notes.md. The payroll envelope (employee benefit expense − SBC − employer social contributions) is a hard ceiling every later bucket model must respect.

Collect and derive:

• revenue, gross profit, operating profit, net income;
• segment revenue and, when available, segment gross profit / operating profit;
• customer concentration and major-channel dependence;
• employee count, R&D headcount, sales headcount if disclosed;
• employee cash payments / employee benefit expense / share-based compensation;
• R&D, sales, G&A expense;
• revenue, gross profit, and payroll per employee;
• equity incentive grants and dilution.

Build a profit_pool table. Do not assume revenue equals value creation; use gross profit / contribution / operating profit when available.

Phase 3 — Reconstruct organization and critical roles

Read references/org_dependency_model.md.

Build role states using two layers:

Company-native layer

• native title / level / BU / location / manager-or-IC.

Latent comparable layer

• scope: task / project / team / multi-team / function / company;
• decision authority;
• technical depth;
• people responsibility;
• revenue/profit responsibility;
• customer concentration exposure;
• talent scarcity / replacement difficulty;
• equity intensity.

For each major profit pool, trace:

profit pool -> critical process -> critical role -> likely org node

Score role dependency qualitatively (low, medium, high, extreme) with evidence. Never turn weak evidence into a fake precise score.