isds-arbitrators

Research aid for arbitration counsel and tribunal-selection teams — accretive-judgment work: the skill surfaces and grounds; it never recommends an appointment. Not legal advice; counsel decides. Two modes:

• Mode 1 — Profile: "tell me about arbitrator X (or X, Y, Z)" → one profile table per person.
• Mode 2 — Selection: "help me pick an arbitrator for this case" → intake, then a ranked shortlist; each finalist gets a Mode 1 table.

Setup (once)

1. The user downloads the UNCTAD full-data Excel themselves (investmentpolicy.unctad.org → ISDS Navigator → full data download) into data/; data/ stays local. If data/ has no workbook: search the connected project folder first (e.g. isds-arbitrators/data/*.xlsx) and stage the user's copy before asking for an upload — in cloud sessions the container-side data/ and user-config.json do NOT persist between sessions, so both gates will otherwise fire every fresh session. The engine accepts any filename with the UNCTAD schema and prints a load-verification line; record the located path in user-config.json saved to the CONNECTED run root (not the container). Durable copy: keep the workbook somewhere persistent that future sessions can find — the connected project's data/ folder by default; if only a run root is connected, beside or inside a run folder is acceptable — and record its path in user-config.json so no future session needs a re-upload.
2. scripts/query_arbitrators.py is the query engine (profiles, shortlists, annex, delta). assets/icsid-cvid-map.json maps names → ICSID profile pages; refresh it by saving the ICSID listing page as PDF and running scripts/parse_icsid_cvids.py.
3. First-run workspace check: before any research, confirm you can write to the user's project folder — create <project>/YYYY-MM-DD Arbitrator Search/ and write a test file. Folder naming: if the user names their runs differently (or asks for a specific folder name), use their name — ask at intake when in doubt; the dated default is a fallback, not a rule. If no writable folder is available (e.g. none connected in Cowork), STOP and ask the user to connect/choose one. Record the chosen root in user-config.json (gitignored), WRITTEN TO THE CONNECTED RUN ROOT the moment the root is established — container-writability is not persistence — and reuse it on later runs. On-device shell writes use the absolute session-mount path (/sessions/<session>/mnt/<folder>/…), never the local OS path and never a cd fallback.
4. Companion skill (recommended): install isds-research (github.com/ccrnyc/isds-research, also on Lawve). This skill delegates all decision retrieval and grounding to it — see "Check the record" below. Tell the user at setup if it is missing.

Compliance gates (default ON, non-overridable)

• Targeted, user-initiated lookups only. No bulk harvesting, no id-walking (cvid or UNCTAD case ids), no scraping-and-hosting. Read references/compliance.md before any fetch beyond ICSID/UNCTAD/PCA. Hosts absent from that table are NOT cleared (default-deny): name the host and record the two-gate result in the run log before fetching — otherwise links only.
• italaw: links only; the user downloads manually.
• Hard rule: no issue-outcome claim from a secondary report (news, blog, summary) may enter a table. Secondary reports only select which decisions to retrieve; unretrievable claims are quarantined outside the table as "reported in secondary sources (not verified against primary source — not included in table)".
• Page-source rule (hard rule): any value that drives a classification or a table cell — acceptance/appointment dates, roles, appointing parties, case status — is read from the case page's own text (raw HTML if needed), never taken from a summarised extraction alone. Automated summarisation layers have fabricated plausible acceptance dates in testing; if a summarised read cannot be reproduced against the page text, re-fetch the source and use only what the page itself says. If the page source itself cannot be fetched, the value is "not established" and the failure is disclosed — never fall back to the summarised extraction. Profile-page row parsing is advisory only: profile-listed case numbers have failed to match their own case pages — confirm on the case page before any reliance.
• Every output states: treaty-based ISDS only; commercial appointments and confidential cases invisible; refer to Jus Mundi/GAR ART for fuller analytics.
• Work product: profiles and shortlists are dispute-related work papers. Every deliverable carries the header "Attorney work product — prepared at counsel's direction for arbitrator selection" (+ matter name if given), and the run folder is the user's own storage — remind counsel that where these files are stored or shared is their privilege call, not the tool's.
• Confidence: grounded values are stated plainly; inferred or single-source values carry their source tag and [verify]; uncertain or conflicting values are never resolved silently — show both, or say "not established." Docket facts verbatim: procedural events taken from a case page — hearing subject, filing type, order type — are reported with the page's own label (quote or mirror it); where the page gives no label (e.g. "Hearing transcripts" with no subject), say so rather than inferring one.
• Deliverable language: builder vocabulary — "Tier 1", "Tier 2", "Mode 1/2", "engine", "rung", "Seats" — NEVER appears in user-facing deliverables OR in chat replies to the user — the rule covers anything counsel reads, not only files. Say "dataset profile (UNCTAD snapshot + live ICSID lookup)", "record check from the decisions", "arbitrator profile", "shortlist". Builder terms are fine in run logs and build docs only. Before delivering ANY user-facing file, scan it for the banned terms; notes for the skill maintainer go in the run log, never in a deliverable.
• Availability (hard rule): death, retirement or unavailability is NEVER asserted without a named, dated source — same bar as issue outcomes. Snapshot silence, profile staleness and "everyone knows" prove nothing. The correct sourced negative is: "no death/retirement notice found at [sources, dates]; that is not confirmation of availability — confirm directly." Default label where unchecked: "availability-unverified".

What this skill does NOT do

Recommend or rank-order an appointment decision; assert personal win-rates or individual votes without retrieved decisions; cover commercial (non-treaty) arbitration; access Jus Mundi/GAR ART/italaw-by-fetch; run any bulk harvest.

Mode 1 — Profile

1. Resolve the name via the engine (--arbitrator "Surname"). If ambiguous, show the candidates and ask. Never merge name variants on similarity — see assets/curated-aliases.json; unverified identity = distinct. The same discipline applies to given names: NEVER expand a dataset initial (e.g. "Ramírez Hernández, R.") into a full given name without profile-level verification from a named source — absent that, use the dataset's own form.
2. Live lookup, per person: assets/icsid-cvid-map.json → fetch the ICSID profile URL → confirm the page is the same person → take nationality, languages, the ICSID case list (role, appointing party) — and SAVE the retrieved list with a provenance header (URL + date). Label everything self-reported. The profile page is a FLOOR, never a case list: testing measured ~77% coverage of ICSID-numbered appointments for one heavy-load arbitrator, with no pattern explaining the omissions — absence of a case from the profile is weak evidence of inactivity, and every count built on it is "at least", not "is". No verified map entry → do NOT guess a cvid; offer the ICSID listing page via the user's browser. Environment-refused fetches follow a disclosed ladder: WebFetch → script route → Claude in Chrome → the user's own browser — each refusal named in the run log, never worked around by inference.
3. CV: link it (chambers/university/SIAC/IAI). CV hosts usually block automated fetch: tell the user visibly — download-then-upload, or Claude in Chrome opens it live. Screen publication titles for issue-relevant writings; then ask whether to review the publications' content for supportive/adverse material (open-access only; paywalled = link).
4. Build ONE table per references/output-template.md — exact section order, wording, footnote conventions (*, **, †, ‡ in order of appearance), italicized case names, visible "▸ Want …? Say 'check the record.'" offers. The case-list annex follows the fixed column spec in the template.
5. Gender: from public self-description only; "not publicly stated" otherwise.
6. Save everything (tables, annex xlsx, retrieved extracts with "Retrieved from: URL" + date, run log) to the run folder (step 3 name). Follow-ups update the same folder. Run log: one log file PER SESSION, named _run-log <subject> <YYYY-MM-DD>.md — NEVER append to a shared _run-log.md (a concurrent-session collision destroyed three sessions' logs in testing), and NEVER force-write past an mtime/changed-on-disk rejection: stop and ask the user. Storage rules: raw engine dumps and other intermediates go to a working/ subfolder — only header-carrying deliverables sit at the run-folder root. Deliverables go to the connected run folder ONLY — never mirror them into the claude.ai project store on your own initiative (it rejects xlsx and leaves an unswept shadow copy of privileged work product; an explicit user instruction to copy is of course honoured). Bridge-outage fallback: if a device write fails mid-save, deliver a zip of the correctly named run folder in-chat for manual unzip, update the run log inside the archive, and state what was and was not verified on disk — never leave outputs stranded or retry past the failure silently.

Mode 2 — Selection

1. Intake: side; treaty & rules; sector; issues; seat/region; language; role sought; conflicts constraints; matter name for the work-product header (optional — the header carries no matter reference if none is given).
2. Screen with the engine (--shortlist --issue ... --rules ... --role ... --treaty ...). Use --treaty whenever a treaty is part of the intake (e.g. --treaty "Energy Charter"); sector is a poor proxy for treaty. Print the ranking weights with the shortlist (user-adjustable via --weights; defaults in the engine). The Excel is the only corpus-wide layer — say so.
3. Shortlist warning: snapshot data cannot see death, retirement, or current unavailability. Before the list is used: (a) the per-finalist live lookup (Mode 1 steps 2–3) is mandatory; (b) a per-candidate availability check with named, dated sources — no deceased/unavailable label without a source; candidates not checked are marked "availability-unverified". Never ship or rely on a static deceased list. Hold-back rule: a candidate is never screened out on an unverified availability premise — the pattern is "availability-unverified — include unless verified otherwise"; verify with a named, dated source before any hold-back.
4. Comparison sheet (candidates × key metrics, incl. shortlist gender balance) + Mode 1 table per finalist. State plainly: research aid; selection judgment, interviews and conflicts checks remain with counsel.

"Check the record on X" (record checks — on request only)

Offers are always SCOPED: "check the record on dissents", "…on annulment committees", "…on her votes", "…on challenges", "…on double-hatting", "…on counsel patterns", "…on publications", "…on newer cases", "…on intra-EU jurisdiction", "…on pending status". When the user asks for one, run only that item per references/deeper-analysis.md. (In deliverables these are "record checks" or "deeper analysis" — never "Tier 2".)

Whenever a record check requires retrieving and reading decisions, invoke the isds-research skill and follow its methodology — correct document identification on the case page, the CONFIRM step against the PDF's own first pages, locating paragraphs, and voice discrimination (is the passage the tribunal speaking, or a claimant/respondent recital?), unanimous-vs-majority per holding limb. Do NOT produce its memo output — its grounding feeds this skill's profile table (pinpoints included). If isds-research is not installed, recommend installing it and, only as a fallback, follow the retrieval-ladder summary in the reference file. Newer cases follow the delta workflow (engine --delta-file): ≤6 newly decided → download all; >6 → websearch selects, then targeted downloads (hard rule above applies). Delta intake: "the cutoff"/"the dataset" defaults to the UNCTAD snapshot — confirm in one line without blocking, OR bundle the cutoff confirmation (snapshot marked as the recommended default) into the single blocking intake call alongside depth; never a separate blocking round-trip of its own. Depth (list only vs list + retrieve decisions) IS a blocking intake question, asked before any answer. Classify "new" by the arbitrator's ACCEPTANCE date on the case page, never by case-number year (registration ≠ appointment; the engine flags boundary-vintage cases); report snapshot-absence as its own class.

Delivery checklist (every run, before anything is delivered)

1. Banned-vocabulary scan over every user-facing file AND the outgoing chat reply.
2. Work-product header on every deliverable, including every xlsx Sources sheet (+ matter name when given).
3. Every document quoted or relied on has an archived extract in retrieved/ (provenance header, route + date).
4. Every fetched host is in references/compliance.md or named in the run log with its two-gate result.
5. Every xlsx conforms to the template's formatting spec — including no header wrapping, on hand-built sheets too.
6. Selection runs: every shortlist finalist links to their profile table.
7. At close: the full run-folder tree INCLUDING working/ verified on disk (listed back with sizes), or delivered as a zip with that stated.

Data freshness (every output)

Footer states: Excel snapshot date (31/12/2023, 1,332 cases) vs live Navigator (31/12/2025, 1,463) vs today; live-layer scope (ICSID-only; post-2023 UNCITRAL/PCA/SCC invisible from free sources — assert nothing); for active arbitrators snapshot counts materially understate current activity. Conflicting values: show both with source classes (primary > institutional metadata > secondary).