caselaw-query

caselaw-query

Surfaces real appellate decisions that cite a statute. The "case law interpreting key sections" axis from the hackathon rubric.

When to use this skill

• After harvester_query.lookup_citation returns a hit and the user asks things like:
  • "any cases on this?"
  • "how have courts interpreted this?"
  • "is there precedent?"
  • "what's the standard for 'reasonable' under § 22350?"
• After pi_brief_format renders a brief, as a follow-up enrichment.
• For doctrine-level questions where the user names a known section.

When NOT to use it

• Not for fact-pattern triage ("client tripped on a sidewalk…"). CourtListener is statute-citation-driven, not fact-pattern-driven.
• Not for damages comparables (CourtListener is appellate opinions, not jury verdicts; settlements aren't there).
• Not as a first-line statute lookup. Always do statute lookup first — this skill enriches the answer, doesn't replace it.

Hard rules — no fabrication

This skill only surfaces what CourtListener returns. Do not:

• Summarize an opinion you haven't fetched.
• Claim a holding the search snippet doesn't mention.
• Combine multiple cases into "the law says X" without citing each.
• Attribute a quote to an opinion unless the snippet shows it verbatim.

The brief response shape: list the top N cases with case name, court, date, and the URL. The user clicks the URL to read the actual opinion. Specter's role is retrieval, not summarization (per SOUL voice rules).

Required env

COURTLISTENER_API_KEY=<token from https://www.courtlistener.com/help/api/rest/#authentication>

Free tier (5,000 queries/hour) is more than enough for the hackathon. Don't commit the key — .env is gitignored.

How to call

Shell

cd ~/Specter && .venv/bin/python -m openclaw.skills.caselaw_query.client \
    "Cal. Veh. Code § 23152(a)" --k 5

cd ~/Specter && .venv/bin/python -m openclaw.skills.caselaw_query.client \
    "Tex. Transp. Code § 545.351" --jurisdiction TX --k 3

Python

from openclaw.skills.caselaw_query.client import cases_for_statute, healthz

cases_for_statute("Cal. Veh. Code § 23152(a)", k=5)
# returns list of dicts:
#   [{"case_name": "...", "court": "...", "date_filed": "...",
#     "url": "https://www.courtlistener.com/opinion/.../",
#     "snippet": "...", "citation_id": ...}, ...]

Output for WhatsApp

Specter formats results like this — short, sourced, terse:

Cases interpreting Cal. Veh. Code § 23152(a):

  1. State v. Michaelson — Idaho Ct. App., 2025
     https://www.courtlistener.com/opinion/10692005/state-v-michaelson/

  2. State v. Polaski — Mont. Sup. Ct., 2005
     https://www.courtlistener.com/opinion/887401/state-v-polaski/

  3. United States v. Thornton — 9th Cir., 2006
     https://www.courtlistener.com/opinion/3036985/united-states-v-thornton/

5 total. Click for full opinion text.

If the user wants more detail on a specific case, Specter can run a fresh CourtListener query for that opinion. Specter does not paraphrase the opinion's content from training-data knowledge. If the API didn't return a snippet for the case, she says so:

"Top case is State v. Michaelson (Idaho 2025). I don't have a snippet — open the link for the holding."

Coverage caveats

CourtListener has strong coverage for:

• US federal courts (SCOTUS, Circuits, District Courts)
• State appellate courts (state supreme + state courts of appeal)
• Some state trial courts (limited and uneven)

Empirically tested coverage for our hackathon citations:

• ✅ FL DUI § 316.193 — 54 results
• ✅ TX speed § 545.351 — 8 results
• ✅ CA DUI § 23152(a) — 5 results
• ⚠️ CA basic speed § 22350 — 1 result (citation-string formatting variance is the likely cause)
• ⚠️ NY VTL § 1192 — 2 results (same reason)

Specter must report counts honestly. If only 1 or 2 cases come back, she says so — doesn't pretend a sparse result is comprehensive.

What it does NOT do

• ❌ Damages / settlement amounts (those are paywalled in private DBs)
• ❌ Trial-court verdicts (CourtListener has very limited trial-court coverage)
• ❌ Predict case outcomes
• ❌ Provide legal advice
• ❌ Paraphrase opinions Specter hasn't fetched

If the user asks for any of those, Specter declines politely and points at what CourtListener can answer — citing precedent, finding interpretive opinions, cross-jurisdiction analogues.