Scope Rates on this page use substantiated CPS investigations (Categories I – III). n = 289,280 · 23% of records with a recorded outcome. All-cases values shown as comparisons where relevant.

Everything the pipeline does — de-identifying narratives, reading them, and extracting the risk indicators — runs on the lab's own computers. No narrative is sent to a cloud service. Human coders write and review the definitions behind every indicator, and check the software's work against a hand-coded standard. Only aggregate county-by-year numbers ever reach these dashboards.

How it works, step by step

Each case narrative passes through five stages before it turns into a number on this dashboard. Every stage happens on the lab's own computers, and every stage is designed around human review.

1
De-identification

Direct identifiers — names, addresses, phone numbers, court case numbers, and exact dates — are removed or replaced with realistic stand-ins before any indicator-extraction software sees the text. The de-identifier was validated externally on a hand-coded sample.

2
Indicator definition & codebook

Every indicator has a written codebook that defines what counts as a "Present" mention, what counts as ambiguous, and what is out of scope. The codebooks are reviewed by domain experts before any model is trained.

3
Human review & training data

For each indicator, trained human coders label a sample of narratives using the codebook. Two coders independently rate every case in the sample; disagreements are reconciled by a third reviewer. The reconciled labels become the gold standard that the indicator software is trained against, and the held-out portion becomes the validation set.

4
Indicator extraction

The risk indicators are extracted from each de-identified narrative. Each indicator has its own software model trained to apply that indicator's codebook consistently across cases. The output is a structured label per case for each indicator — not a probability, not a diagnosis, not a severity assessment.

5
Aggregation & release

The per-case indicator labels are aggregated to county-by-year totals. Only aggregate counts and rates reach this dashboard. No individual narrative or per-case label is exposed.

Validation

Every indicator is checked against the held-out human-coded set before it is approved for release. Two checks must pass:

Indicators that do not meet both checks are pulled from the dashboard until the codebook, the training sample, or the software is revised. The decision to release an indicator is recorded; the decision to retire one is recorded; both are auditable.

Where this fits in the larger data pipeline

This dashboard is one output of a longer end-to-end pipeline. From source to surface:

  1. Source records. Michigan child-welfare disposition narratives are received from the originating system on a fixed cadence.
  2. Cleaning & normalization. Narratives are normalized (encoding, whitespace, case) and joined to a per-case geographic table (county, ZIP, year).
  3. De-identification. The de-id stage above runs over the cleaned narratives.
  4. Indicator extraction. The trained indicator software produces a structured label per case for each indicator.
  5. Lab data warehouse. Per-case labels land in the lab's existing data warehouse, behind the same access controls that already cover the source records. Per-case data does not leave the warehouse.
  6. Aggregation. The dashboard pulls only the aggregate county-by-year counts and computes the rates shown here.
  7. Downstream uses. The same per-case labels in the warehouse feed other lab products — research papers, methodology development, and program-evaluation analyses — under the lab's existing data-use agreements. The dashboard is one view; the warehouse is the canonical source.

Why substantiated cases are the primary slice

Michigan CPS assigns every completed investigation to one of five categories. The categories reflect what the investigation found — evidence of abuse or neglect, and the risk to the child — and drive what happens next.

Category I

Preponderance of evidence of abuse or neglect + high or intensive risk. Court petition + Central Registry.

Category II

Preponderance of evidence + moderate–high risk. Case opens for ongoing CPS services + Central Registry.

Category III

Preponderance of evidence + low–moderate risk. Community-based services offered. Not added to Central Registry.

Category IV

Investigation did not find a preponderance of evidence, but risk factors present. Community services offered.

Category V

Investigation found no evidence and no risk. Case closed with no further action.

Unknown / OPENCLOSE

Some cases carry an "OPENCLOSE" suffix (same-day open-and-close) which we treat as the same category. A small share of records have no recorded category and are excluded from both slices.

Substantiated means Categories I, II, or III — the investigation confirmed a preponderance of evidence of abuse or neglect. That's ~289,280 cases in this dataset, or ~23% of records with a recorded outcome.

The dashboards use the substantiated slice as the primary numbers because that's where the signal that matters to program work lives. A narrative in a substantiated case describes a confirmed problem; a narrative in an unsubstantiated case may describe a false alarm, an unfounded referral, or a live situation that did not clear the evidentiary bar. Both are useful, but they mean different things.

Every page shows the substantiated rate as the headline number and the all-cases rate as a comparison annotation, so the audience can see the gap and judge for themselves. The all-cases number is never hidden.

Privacy by design

Nothing goes to a cloud

Every part of the pipeline runs on the lab's own computers. No narrative text is sent to a cloud service or a commercial AI provider at any stage. The narratives never leave the building.

Identifiers removed first

Every narrative is de-identified before any indicator model reads it. Names, addresses, phone numbers, case numbers, and exact dates are removed or replaced with realistic stand-ins. The de-identifier itself runs locally.

Aggregates only reach here

The dashboard only ever sees county-by-year totals. Per-case labels stay behind the same access controls that already protect the source records. Counties with fewer than 1,000 cases in the stable-year window are suppressed from the top-county ranking to limit re-identification risk on small populations.

Auditable

Every indicator has a written definition, a versioned model, and a recorded performance against a set of cases that human coders labeled first. Any change to the definition or the model is logged and re-runs the affected numbers.

About the models

Narrative Insights is a deliberate choice to use small, specialized, local tools rather than large, general, cloud-hosted AI. Everything below is designed around that choice.

Small, purpose-built tools

The tools we use are much smaller than the frontier AI systems in the news. That's on purpose. Each indicator is a well-defined job — apply a written definition consistently across a lot of narratives — and small tools trained for that specific job are enough. Bigger is not always better.

Two kinds of tool, one job each

For the simpler indicators (any substance, domestic violence, firearms, homelessness, housing instability), we use small pattern-matching models that produce a Yes or No for each narrative. For the more nuanced indicators (which type of substance, based on how it's described), we use a larger language model — but still one small enough to run on our own hardware.

Runs on our own hardware

Every model runs on the lab's own computers. Model files live on the lab's storage; the reading happens on the lab's machines. Narratives never travel to a commercial AI provider or a cloud service. This is the design constraint, not an afterthought.

Small energy footprint

Because we don't call out to giant data centers, the whole system uses very little power. A full run over Michigan's multi-year corpus consumes about as much electricity as a household appliance running for a few hours. Comparable cloud-AI extraction of the same corpus would consume orders of magnitude more energy.

Low compute cost

Small models mean small bills. Running the pipeline over one thousand narratives costs cents, not dollars. A comparable cloud-AI approach at this scale would run into the tens or hundreds of dollars per thousand — and that's every re-run.

Not making decisions

The models don't decide anything about a case. Each one reads a narrative and applies a written definition to it — the same way a trained human coder would, only faster and consistently at the volume the caseload actually generates. Program decisions are made by people using the enriched structured data.

How we build a reliable indicator

Getting a small model to do a well-defined job reliably takes deliberate work. Here's what happens behind every indicator on this dashboard:

  1. Every training example is human-coded first. Models are not trained on labels a computer produced. Human reviewers label a sample of narratives from scratch using the written definition. Two reviewers work independently on the same cases; a third resolves any disagreement. The reconciled human labels are what the model learns from.
  2. We grow the training set carefully, not blindly. After the first round of human coding, the model is used to surface its own uncertain cases in the broader corpus — narratives where its answer is barely a Yes or barely a No. Those are the cases we send to human reviewers next. Result: a small, high-value training set rather than a large noisy one.
  3. When models disagree, humans decide. For the more nuanced indicators we run two independent models. When they disagree on a case, that case is flagged and sent to a human reviewer — the disagreement itself is what makes the case worth human attention.
  4. We adapt each model to the source language. Before we train an indicator, its underlying model reads through 200,000 anonymous Michigan disposition narratives to learn the vocabulary and phrasing of this exact record type. Only then do we train it on the indicator's definition. This adaptation step alone measurably improves how closely the model matches human coders.
  5. External benchmarks where they exist. For some indicators, published human-coded benchmarks exist from academic research. Where they do, we hold our model to that same benchmark before its numbers appear here. If it doesn't clear the benchmark, it doesn't ship — the codebook, the training sample, or the model gets revised.

The combined effect is a set of small tools that each do one thing well, on the lab's own computers, with human review at every step where judgment matters.

Publications behind this work

Peer-reviewed research from the University of Michigan Data Lab team that established the methods used on this dashboard.

Text analysis, language models, and rule-based coding in child welfare data

Perron, B. E., Stoll, D., Victor, B. G., Qi, Z., Jud, A., & Ryan, J. P. (in press). Validation of a small language model for DSM-5 substance category classification in child welfare records. Journal of Evidence-Based Social Work.

Qi, Z., Perron, B. E., Victor, B. G., Stoll, D., & Ryan, J. P. (2025). Small models achieve large language model performance: Evaluating reasoning-enabled AI for secure child welfare research. Journal of Evidence-Based Social Work, 1–22. https://doi.org/10.1080/26408066.2026.2616711

Perron, B. E., Victor, B. G., Bushman, G., Moore, A., Ryan, J. P., Lu, A. J., & Piellusch, E. K. (2019). Detecting substance-related problems in narrative investigation summaries of child abuse and neglect using text mining and machine learning. Child Abuse & Neglect, 98, 1–13. https://doi.org/10.1016/j.chiabu.2019.104180

Victor, B. G., Perron, B. E., Sokol, R. L., Fedina, L., & Ryan, J. P. (in press). Automated identification of domestic violence in written child welfare records: Leveraging text mining and machine learning to enhance social work research and evaluation. Journal of the Society for Social Work and Research.

Perron, B. E., Luan, H., Victor, B. G., Hiltz-Perron, O., & Ryan, J. (2024). Moving beyond ChatGPT: Local large language models (LLMs) and the secure analysis of confidential unstructured text data in social work research. Research on Social Work Practice. https://doi.org/10.1177/10497315241280686

Perron, B. E., Stoll, D., Qi, Z., Yoo, N., & Ren, C. (2026). Not all language models are generative: A methods primer on encoder models in social work research [Working paper]. SSRN. https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6731299

Opioid and firearm papers in child welfare data

Sokol, R. L., Victor, B. G., Piellusch, E. K., Nielsen, S. B., Ryan, J. P., & Perron, B. E. (2020). Prevalence and context of firearms-related problems in child protective service investigations. Child Abuse & Neglect, 107, 1–6. https://doi.org/10.1016/j.chiabu.2020.104572

Bushman, G., Victor, B. G., Ryan, J. P., & Perron, B. E. (2018). In utero exposure to opioids: An observational study of mothers involved in the child welfare system. Substance Use & Misuse, 53, 844–851. https://doi.org/10.1080/10826084.2017.1388406

The risk indicators

Plain-language definition of each indicator — what a "Present" label on a case means in operational terms. For the full operational specification of each indicator — its written codebook, retrieval seeds, and LLM prompt — see Indicator playbooks at the bottom of this page.

Substance involvement

IndicatorWhat "Present" means
Any substance involvementNarratives that record substance involvement of any kind — the broadest indicator that something substance-related appears in the case.
CannabisNarratives that mention cannabis (marijuana) use.
AlcoholNarratives that mention alcohol use by the caregiver, a household member, or the child.
OpioidsNarratives that mention any opioid — prescription or illicit, by the caregiver, a household member, or the child.
StimulantsNarratives that mention stimulants — methamphetamine, cocaine, or prescription stimulants.
Sedatives, hypnotics, anxiolyticsNarratives that mention sedatives, sleep aids, or anti-anxiety medications (benzodiazepines, sleep aids, similar).

Co-occurring concerns

IndicatorWhat "Present" means
HomelessnessNarratives that describe the family as homeless or living in a shelter, vehicle, or other non-housing setting.
Housing instabilityNarratives that describe housing instability short of homelessness — eviction, frequent moves, doubled-up living, or unsafe housing conditions.
Firearms in the homeNarratives that mention firearms present in the home or accessible to the family.
Domestic violenceNarratives that record domestic violence between caregivers or against a partner.

Indicator playbooks

A "Present" label is more than a keyword match. Every indicator is governed by a written specification — a codebook that defines what counts, an LLM prompt or model spec that operationalizes the codebook on each narrative, and (for retrieval-based indicators) curated seed examples used to find candidate cases for human review. Expand any indicator below to read the full source documents.

Reading the playbooks

Each indicator's specification is a working research document — written for analysts and coders, not for the public-facing dashboard. The technical language is intentional; the codebooks are how the construct is held consistent over time.

Substance involvement

Any substance involvement2 document(s)
Indicator prompt or specification
# Substance-Related Problems Detection Prompt — construct-extraction style

This prompt extracts evidence of **substance-related problems (SRP)** in
Michigan child-welfare disposition narratives using the
construct-extraction JSON schema expected by the autonomous labeling
pipeline. The construct definition is grounded in Perron et al. (2019):
a substance-related problem exists when a caregiver's alcohol or drug
use is reported as a clinical, legal, social, or child-welfare concern —
not merely incidental use.

## Instructions

1. Carefully read the provided text.
2. Identify ANY mention of a caregiver substance-use problem —
   including current or recent alcohol or drug misuse, intoxication,
   substance-affected pregnancies or births, substance-use-related
   legal involvement, mandated or self-referred treatment, prior
   substance-use treatment history mentioned as a current concern, or
   substance-positive drug screens.
3. Distinguish problem-level use from incidental mention (e.g.,
   "mother had a glass of wine with dinner" without further concern).
4. Extract the exact terms and full surrounding sentences for every
   term you classify as true-positive or false-positive.
5. When multiple sentences contain SRP-relevant terms, separate each
   sentence with a semicolon (;).

## What counts as a substance-related problem (TRUE POSITIVES)

Inclusive: any of these counts as a true positive when the use rises to
problem level (clinical, legal, social, or child-welfare concern):

- **Substances:** alcohol, beer, wine, liquor, drinking heavily, drunk,
  intoxicated, intoxication; marijuana, weed, cannabis, THC; opioids,
  heroin, fentanyl, oxycodone, methadone, suboxone; cocaine, crack;
  methamphetamine, meth; amphetamines; benzodiazepines, benzos;
  prescription drug misuse, pill-popping; inhalants, huffing; synthetic
  drugs; "K2", "spice"
- **Use-as-problem language:** substance abuse, drug abuse, alcohol
  abuse, addiction, dependence, substance use disorder, SUD, AUD,
  chemical dependency, in active use, relapse, relapsed, using again,
  came up dirty, dirty drop, positive drug screen, positive UA, positive
  tox, tested positive for [substance]
- **Substance-affected pregnancy/birth:** NAS (neonatal abstinence
  syndrome), drug-affected birth, prenatal substance exposure, drug-
  exposed infant, drug-positive at birth, meconium positive
- **Treatment / recovery:** rehab, residential treatment, inpatient
  treatment, outpatient treatment, AA, NA, MAT (medication-assisted
  treatment), methadone clinic, suboxone clinic, sobriety, sober,
  recovery, in recovery, mandated treatment, court-ordered treatment,
  CARES (when used in this context), substance use evaluation,
  substance assessment
- **Substance-related legal:** DUI, OWI, drug arrest, drug possession,
  drug trafficking, paraphernalia, drug-related charges, drug probation
- **Substance-use disclosure that signals current concern:** "father
  reports daily marijuana use", "mother continues to drink despite case
  plan goals"

## What does NOT count (FALSE POSITIVES)

- **Incidental social drinking** without concern ("parents had a few
  beers at the BBQ — no concerns noted").
- **Prescription medication used as prescribed** for a clinical
  condition (e.g., "father takes prescribed Vicodin for chronic back
  pain") UNLESS there is a misuse/abuse signal.
- **Historical substance use clearly resolved** ("father was sober for
  the past 10 years; no current substance concerns").
- **Substance use by a non-caregiver** (e.g., a non-resident relative)
  when not relevant to the case family's caregiving capacity.
- **Person names** containing substance-suggestive words (e.g.,
  "Brandy" as a first name, "Hunter" as a surname, "Wine" as a place
  name).
- **Medical / professional context** ("the nurse administered morphine
  for pain management in the hospital").
- **Smoking tobacco alone** without further concern (cigarettes,
  vaping, e-cigarettes) — not an SRP per this construct.
- **Substance-use training or awareness** without a substance-use
  event ("father attended a drug-awareness class as part of probation"
  alone, if no substance-use concern is otherwise documented, is NOT
  POSITIVE).
- **Hypothetical references** ("if the parent were using
  substances...").

## Output format

Return your analysis in this exact JSON format. The top-level boolean
key MUST be named `srp_mentioned`. No other format is allowed.

```json
{
  "srp_mentioned": true,
  "srp_terms": ["exact term 1", "exact term 2"],
  "true_positive_context": "EXACT sentence(s) containing genuine SRP-related term(s), separated by semicolons",
  "false_positive_terms": ["false positive term 1", "false positive term 2"],
  "false_positive_context": "EXACT sentence(s) containing the false positive term(s), separated by semicolons"
}
```

## Example responses

**Text:** "Mother tested positive for cocaine and methamphetamine at the time of the child's birth. Infant exhibited NAS symptoms and was transferred to NICU."

```json
{
  "srp_mentioned": true,
  "srp_terms": ["tested positive for cocaine and methamphetamine", "NAS symptoms"],
  "true_positive_context": "Mother tested positive for cocaine and methamphetamine at the time of the child's birth.; Infant exhibited NAS symptoms and was transferred to NICU.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

**Text:** "Father takes prescribed Vicodin for chronic back pain. He provides documentation of his prescription and no concerns about misuse were observed."

```json
{
  "srp_mentioned": false,
  "srp_terms": [],
  "true_positive_context": "",
  "false_positive_terms": ["prescribed Vicodin"],
  "false_positive_context": "Father takes prescribed Vicodin for chronic back pain."
}
```

**Text:** "Mother attended outpatient substance-abuse treatment three days per week and provided clean drug screens for the past 60 days. She continues to attend AA meetings."

```json
{
  "srp_mentioned": true,
  "srp_terms": ["outpatient substance-abuse treatment", "drug screens", "AA meetings"],
  "true_positive_context": "Mother attended outpatient substance-abuse treatment three days per week and provided clean drug screens for the past 60 days.; She continues to attend AA meetings.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

**Text:** "Maternal aunt Brandy lives in the home and helps with childcare. There is no use of substances in the home."

```json
{
  "srp_mentioned": false,
  "srp_terms": [],
  "true_positive_context": "",
  "false_positive_terms": ["Brandy"],
  "false_positive_context": "Maternal aunt Brandy lives in the home and helps with childcare."
}
```

## Text to analyze

[INSERT TEXT HERE]
Seed examples — used to retrieve candidate narratives
# Synthetic seeds for Substance-Related Problems embedding retrieval.
# Current OR historical use of intoxicating substances (alcohol, illicit
# drugs, misused prescription medications).

positive_seeds:
  - "Mother admitted to using methamphetamine daily and tested positive for both meth and amphetamines on a recent urine screen."
  - "Father has a documented history of alcohol abuse, including multiple DUI arrests and a recent inpatient rehabilitation stay."
  - "Stepfather has been in opioid use treatment at the methadone clinic for the past nine months following a heroin overdose."
  - "Mother was observed to be intoxicated during the home visit; she admitted she had been drinking vodka throughout the day."
  - "The teenage son was found with marijuana and a vape pen in his school locker; he reported daily cannabis use."
  - "Father relapsed on cocaine following the loss of his job and is now attending Narcotics Anonymous meetings twice weekly."
  - "Mother's toxicology came back positive for fentanyl and benzodiazepines at the time of the child's birth."
  - "Stepfather was arrested for possession of crack cocaine with intent to distribute."
  - "Mother completed a 28-day residential treatment program at the LeValley Rehabilitation Center but relapsed within two weeks of discharge."
  - "Father was observed to be under the influence at the home visit, with slurred speech and an unsteady gait."

negative_seeds:
  - "Mother completed rehabilitation treatment over fifteen years ago and has been continuously sober since; no current substance concerns."
  - "Father takes oxycodone as prescribed for post-surgical pain and has no history of substance abuse."
  - "Maternal grandmother offered the children caffeinated soda during the home visit; no other substance concerns reported."
  - "The toddler accidentally ingested a small amount of cough syrup that was left within reach but no other drug concerns exist."
  - "Mother smokes cigarettes only; she has no history of alcohol or illicit drug use."
  - "Father was prescribed a brief course of Xanax for severe situational anxiety following a family death but has discontinued use."
Cannabis2 document(s)
Codebook — what counts as a positive
# Codebook — Cannabis Use

## Operational definition

Cannabis Use is any indication that a person connected to the case (caregiver, parent, child, sibling, household member, relative, or other named person) is using, has used, possesses, cultivates, traffics, or is involved with cannabis or its derivatives in a way that is documented in the narrative as a case-relevant fact. This includes recreational use, problematic use, cannabis use disorder, marijuana-related arrests, positive drug screens for THC, prenatal cannabis exposure, neonatal positive THC screens, and child access to cannabis products in the home. The trigger is the *substance* (cannabis / marijuana / THC), at any point in time and for any subject. The construct is distinct from substance use broadly: alcohol, opioids, methamphetamine, cocaine, or other non-cannabis substances are NOT positive unless cannabis is also explicitly named.

This construct covers **mentions of use**, not severity grading per DSM-5. A single documented positive THC screen on a caregiver is POSITIVE, regardless of whether the narrative also labels it as a "disorder."

Michigan legalized recreational cannabis in December 2018. Narratives in this corpus may therefore distinguish lawful recreational use from problematic use; **both count as POSITIVE** if cannabis is named as relevant to the case. The construct is about identification of cannabis in the narrative, not about whether the use is illegal.

## What counts as POSITIVE

- **Generic terms:** marijuana, cannabis, weed, pot, grass, ganja, herb, bud, dope (in cannabis context), reefer, Mary Jane, MJ.
- **Active compound and metabolites:** THC, delta-9-THC, delta-8-THC, THC-COOH, cannabinoid (in psychoactive context), positive THC screen, positive for marijuana, positive for cannabinoids.
- **Product forms:** edibles, gummies, brownies, cookies (in cannabis context), tinctures (THC-containing), vape pens or cartridges (THC / cannabis), wax, shatter, dabs, rosin, kief, hash, hashish, hash oil, BHO (butane hash oil), live resin, concentrate.
- **Smoked / inhaled forms:** joint(s), blunt(s), spliff(s), bowl, bong, pipe (cannabis context), one-hitter, dab rig, vaporizer (cannabis context).
- **Behavior verbs:** smoking, smoked, getting high, lit up, blazed, baked, stoned, ripped, faded, blunted, dabbing.
- **Acquisition / supply:** dealing, selling, distributing, trafficking, possession, cultivation, grow operation, grow house, grow tent, indoor grow, outdoor grow.
- **Clinical / problem language:** cannabis use disorder (CUD), marijuana abuse, marijuana dependence, problematic cannabis use, cannabis hyperemesis, marijuana intoxication.
- **Perinatal / pediatric:** prenatal cannabis exposure, maternal THC use during pregnancy, newborn positive for THC at birth, child ingestion of an edible, toddler ate a gummy and was hospitalized.
- **Legal events:** marijuana arrest, possession charge, MIP marijuana, OWI marijuana (operating while intoxicated, cannabis), trafficking charge, cultivation charge, drug court for cannabis.
- **Disclosure / admission:** parent admits to smoking weed daily; caregiver self-reports recreational marijuana use; teen disclosed using cannabis.

Any subject (caregiver, parent, household member, relative, other named person, child) and any timeframe (historical, current, active) count.

## What does NOT count

- **CBD-only products (non-psychoactive)** where the narrative explicitly identifies the product as CBD with no THC, hemp-derived CBD oil, or where the cannabidiol use is for a clearly separate reason (anxiety, sleep) and no THC / marijuana / cannabis use is named. The qualifier matters: "CBD oil" alone is NEGATIVE; "CBD oil plus marijuana use" is POSITIVE for the marijuana mention.
- **Hemp / industrial hemp / hemp products** (hemp seeds, hemp protein, hemp clothing, hemp lotion) with no THC content named.
- **Synthetic cannabinoids (K2, Spice, AK-47, fake weed)** — these are a distinct construct (synthetic cannabinoid use), not cannabis sensu stricto. Mark as NEGATIVE for cannabis unless the narrative explicitly conflates them with marijuana use.
- **Awareness, training, or education** sessions about cannabis (e.g., "mother attended drug awareness class that included marijuana information") with no use event.
- **Historical resolved use** with sustained sobriety (e.g., "father has 8 years of sobriety from marijuana") and no current bearing on the case.
- **Hypothetical or speculative reference only** ("if she relapses on marijuana again, we will…").
- **Name overlap / homograph** — surnames like "Reefer", street names containing "Mary Jane", a person named "Bud", colloquial idioms ("kicked the bucket", "high spirits", "smoking gun") with no cannabis context.
- **Medical-context cannabinoid medications used as prescribed with no misuse signal** — Marinol (dronabinol), Cesamet (nabilone), Sativex, Epidiolex (cannabidiol for seizures), when documented as prescribed and used as directed for a medical indication.
- **Other named substances without cannabis** — alcohol, opioids, methamphetamine, cocaine, benzodiazepines, hallucinogens with no marijuana mention.
- **Negation:** "denies marijuana use," "tested negative for THC," "no history of cannabis use" — these are NEGATIVE for cannabis use.

## Edge cases — resolve by rule

The labeling prompt examples (in the corresponding
`cannabis_construct_published_style.md`) cover the canonical edge cases for
this construct. Apply this rule: **if a candidate record fits one of the
prompt's negative-example patterns, it is NEGATIVE**; **if it fits a
positive-example pattern, it is POSITIVE**; otherwise apply the
operational definition and the inclusion/exclusion lists above.

| Pattern | Rule |
|---|---|
| Resolved past with no current bearing | NEGATIVE |
| Hypothetical or speculative reference only | NEGATIVE |
| Metaphor, idiom, name overlap | NEGATIVE |
| Awareness, training, drill, or preparedness only | NEGATIVE |
| Genuine reference with current applicability | POSITIVE |
| Past episode whose effect on current functioning persists | POSITIVE |
| CBD-only, hemp-only, or synthetic cannabinoid (K2/Spice) with no THC/cannabis named | NEGATIVE |
| Recreational lawful use named as case-relevant (e.g., smoking around child) | POSITIVE |
| Prescribed Marinol/Epidiolex used as directed with no misuse signal | NEGATIVE |
| Explicit negation ("denies marijuana use", "negative for THC") | NEGATIVE |

## How to handle uncertainty

If the construct-related content is too sparse to apply the rules above,
or if the narrative is incomplete in a way that prevents a clear
judgment (e.g., "drug use" with no substance named, "tested positive"
with no panel listed), mark **UNCERTAIN**. Default to UNCERTAIN rather
than guessing. The pipeline reports UNCERTAIN records separately from
POSITIVE and NEGATIVE and they are routed out of the LLM-labeled
training pool.
Indicator prompt or specification
# Cannabis Use Detection Prompt — construct-extraction style

## Operational definition

Cannabis Use is any indication that a person connected to the case (caregiver, parent, child, sibling, household member, relative, or other named person) is using, has used, possesses, cultivates, traffics, or is involved with cannabis or its derivatives in a way that is documented in the narrative as a case-relevant fact. This includes recreational use, problematic use, cannabis use disorder, marijuana-related arrests, positive drug screens for THC, prenatal cannabis exposure, neonatal positive THC screens, and child access to cannabis products in the home. The trigger is the *substance* (cannabis / marijuana / THC), at any point in time and for any subject. The construct is distinct from substance use broadly: alcohol, opioids, methamphetamine, cocaine, or other non-cannabis substances are NOT positive unless cannabis is also explicitly named. Michigan legalized recreational cannabis in December 2018; both lawful recreational and problematic use count as POSITIVE if cannabis is named as case-relevant.


## Instructions

1. Carefully read the provided text.
2. Identify ANY mention of cannabis or its derivatives: marijuana, weed, pot, cannabis, THC, hash, hashish, dabs, wax, shatter, edibles, gummies (cannabis), joints, blunts, spliffs, bongs, vape cartridges (THC), grow operations, marijuana arrests, positive THC drug screens, prenatal cannabis exposure, neonatal THC screen.
3. Distinguish problem-level or case-relevant involvement (use, possession, cultivation, child access, arrest, prenatal exposure, positive screen) from false positives: CBD-only products, hemp / hemp seeds / hemp clothing, prescribed cannabinoid medications (Marinol, Epidiolex, Cesamet) used as directed, synthetic cannabinoids (K2 / Spice), awareness or training without a use event, fully resolved past with no current bearing, explicit negation ("denies marijuana use", "negative for THC"), and unrelated substances (alcohol, opioids, methamphetamine, cocaine, benzodiazepines).
4. Count cannabis regardless of stated subject (parent, child, relative, household member) and regardless of timeframe (historical, current, active) so long as the narrative treats it as case-relevant.
5. Extract the exact terms and the full surrounding sentence(s) as context.
6. Separate multiple cannabis-relevant sentences with semicolons (;).

## What counts as a positive (TRUE POSITIVES)

- **Generic cannabis terms:** marijuana, cannabis, weed, pot, grass, ganja, herb, bud, reefer, Mary Jane, MJ, dope (in cannabis context).
- **Active compound / metabolites:** THC, delta-9-THC, delta-8-THC, THC-COOH, cannabinoid (in psychoactive context), positive THC screen, positive for marijuana, positive for cannabinoids.
- **Product forms:** edibles, gummies (cannabis), THC-infused brownies / cookies, tinctures (THC), vape pens or cartridges (THC), wax, shatter, dabs, rosin, kief, hash, hashish, hash oil, BHO (butane hash oil), live resin, concentrate.
- **Smoked / inhaled paraphernalia:** joint, blunt, spliff, bowl, bong, pipe (cannabis context), one-hitter, dab rig, vaporizer (cannabis context).
- **Behavior verbs:** smoking weed, smoked marijuana, getting high (cannabis context), lit up, blazed, baked, stoned, dabbing.
- **Acquisition / supply / cultivation:** dealing, selling, distributing, trafficking, possession, cultivation, grow operation, grow house, grow tent, indoor grow, outdoor grow.
- **Clinical / problem language:** cannabis use disorder (CUD), marijuana abuse, marijuana dependence, problematic cannabis use, cannabis hyperemesis syndrome, marijuana intoxication.
- **Perinatal / pediatric:** prenatal cannabis exposure, maternal THC use during pregnancy, newborn positive for THC at birth, child ingestion of an edible / gummy, toddler hospitalized after eating a cannabis-infused product.
- **Legal events:** marijuana arrest, possession of marijuana charge, MIP marijuana, OWI / DUI marijuana, trafficking charge, cultivation charge, drug court for cannabis.
- **Disclosure / admission:** parent admits to smoking weed daily; caregiver self-reports recreational marijuana use; teen disclosed using cannabis.

Any subject (caregiver, parent, household member, relative, other named person, child) and any timeframe (historical, current, active) count.

## What does NOT count (FALSE POSITIVES)

- **CBD-only products (non-psychoactive)** where the narrative explicitly identifies the product as CBD oil, hemp-derived CBD, or cannabidiol with no THC and no marijuana use named. ("Mother uses CBD oil for anxiety, labeled zero THC" → NEGATIVE.)
- **Hemp / industrial hemp / hemp seeds / hemp clothing / hemp protein / hemp lotion** with no THC content named.
- **Synthetic cannabinoids: K2, Spice, AK-47, fake weed, synthetic marijuana** — these are a distinct construct (synthetic cannabinoid use), not cannabis. Mark NEGATIVE for cannabis unless the narrative explicitly conflates them with marijuana use.
- **Prescribed cannabinoid medications used as directed with no misuse signal:** Marinol (dronabinol), Cesamet (nabilone), Sativex, Epidiolex (cannabidiol for seizures). If the narrative says "prescribed and uses as directed, no concerns," NEGATIVE.
- **Awareness, training, drug education** sessions about cannabis with no actual use event ("attended drug awareness class that mentioned marijuana").
- **Historical resolved use** with sustained sobriety and no current bearing ("father has 8 years sobriety from marijuana, no current concerns").
- **Hypothetical or speculative reference** ("if she relapses on marijuana again…").
- **Name overlap, metaphor, idiom:** surnames or street names containing "Mary Jane" / "Bud" / "Reefer"; idioms like "smoking gun", "high spirits", "kicked the bucket"; "weeding the garden"; "potted plant."
- **Explicit negation:** "denies marijuana use," "tested negative for THC," "no history of cannabis use," "the panel did not include cannabinoids" — NEGATIVE for cannabis use.
- **Other named substances without cannabis** — alcohol, opioids (heroin, fentanyl, oxycodone), methamphetamine, cocaine, benzodiazepines, hallucinogens with no marijuana mention.

## Output format

Return your analysis in this exact JSON format. The top-level boolean key MUST be named `cannabis_mentioned`. No other format is allowed.

```json
{
  "cannabis_mentioned": true,
  "tp_terms": ["term 1", "term 2"],
  "tp_context": "EXACT sentence(s) from the narrative containing genuine cannabis terms, separated by semicolons.",
  "fp_terms": [],
  "fp_context": ""
}
```

## Example responses

**Text:** "Mother tested positive for THC and marijuana metabolites at the time of the infant's birth, and the newborn also screened positive for cannabinoids. Father reported smoking blunts in the home daily."
```json
{
  "cannabis_mentioned": true,
  "tp_terms": ["THC", "marijuana", "cannabinoids", "blunts"],
  "tp_context": "Mother tested positive for THC and marijuana metabolites at the time of the infant's birth, and the newborn also screened positive for cannabinoids.; Father reported smoking blunts in the home daily.",
  "fp_terms": [],
  "fp_context": ""
}
```

**Text:** "Mother uses hemp-derived CBD oil for anxiety and the bottle is labeled as containing zero THC. She denies any current or historical marijuana use and her drug screens have been negative for cannabinoids."
```json
{
  "cannabis_mentioned": false,
  "tp_terms": [],
  "tp_context": "",
  "fp_terms": ["CBD oil", "hemp-derived", "marijuana use (denied)", "THC (negative)"],
  "fp_context": "Mother uses hemp-derived CBD oil for anxiety and the bottle is labeled as containing zero THC.; She denies any current or historical marijuana use and her drug screens have been negative for cannabinoids."
}
```

**Text:** "Father was hospitalized after smoking K2 / Spice synthetic cannabinoids and presented with severe agitation in the emergency department."
```json
{
  "cannabis_mentioned": false,
  "tp_terms": [],
  "tp_context": "",
  "fp_terms": ["K2", "Spice", "synthetic cannabinoids"],
  "fp_context": "Father was hospitalized after smoking K2 / Spice synthetic cannabinoids and presented with severe agitation in the emergency department."
}
```

## Text to analyze

[INSERT TEXT HERE]
Alcohol2 document(s)
Codebook — what counts as a positive
# Codebook — Alcohol Use

## Operational definition

Alcohol Use is any indication that a person connected to the case (caregiver, child, sibling, household member, or other named relative) is currently consuming, has consumed, or has a problem history involving beverage alcohol — beer, wine, liquor, malt liquor, hard seltzer, or other ethanol-containing drinks — at any point in time. The construct is broad with respect to *use*: it covers explicit drinking events, intoxication, alcohol-related legal events (DUI/OWI/DWI/MIP), treatment for alcohol use disorder (AUD), withdrawal, fetal alcohol exposure, and disclosures of problematic drinking. The trigger is the consumption of beverage alcohol, at any time, by any subject. **Scope is DSM-5 USE/MENTIONS, not severity grading**: any genuine drinking episode, history, or treatment qualifies; the labeler does not need to grade mild/moderate/severe AUD.

The construct is distinct from non-beverage alcohol products (rubbing alcohol, isopropyl, hand sanitizer, alcohol wipes/swabs, ethanol-based cleaning agents) and from negated or fully resolved past use.

## What counts as POSITIVE

- **Beverage alcohol mentions in a use context**: beer, wine, liquor, hard liquor, vodka, whiskey, bourbon, scotch, gin, rum, tequila, brandy, cognac, champagne, malt liquor, hard seltzer, fortified wine, moonshine, homemade alcohol, "drinks," "drinking," "a drink."
- **Intoxication and impairment language**: drunk, intoxicated, inebriated, under the influence (of alcohol), "had been drinking," buzzed, tipsy, hammered, wasted, blackout/blacked out, passed out from drinking, smelled of alcohol, slurred speech attributed to drinking, BAC/blood alcohol concentration above zero.
- **Alcohol-related legal events**: DUI, DWI, OWI, OUI, drunk driving, driving while intoxicated, open container charge, public intoxication, MIP (minor in possession of alcohol), zero-tolerance violation, alcohol-related arrest or probation condition.
- **Alcohol use disorder language**: alcoholism, alcoholic, alcohol abuse, alcohol dependence, alcohol use disorder, AUD, problem drinking, binge drinking, heavy drinking, drinking problem, "drinks too much," "can't stop drinking."
- **Treatment / recovery**: AA (Alcoholics Anonymous), 12-step for alcohol, alcohol treatment, alcohol rehab, detox for alcohol, inpatient/outpatient treatment for drinking, sober living for alcohol, medication-assisted treatment for AUD (naltrexone, acamprosate, disulfiram/Antabuse), SMART Recovery for alcohol.
- **Withdrawal**: alcohol withdrawal, delirium tremens, DTs, shakes from not drinking, withdrawal seizure attributed to alcohol cessation.
- **Caregiving while intoxicated**: parent intoxicated while supervising children, driving children while drunk, leaving children alone to go drinking, passing out drunk in front of children.
- **Perinatal / fetal alcohol**: drinking during pregnancy, prenatal alcohol exposure, fetal alcohol spectrum disorder (FASD), fetal alcohol syndrome (FAS), positive alcohol/EtG test at delivery.
- **Disclosure / collateral report**: subject states they drink heavily; relative reports the parent "drinks every night"; child describes parent's drinking.
- **Any certainty level**: confirmed, suspected, self-reported, observed by worker, collateral-reported all count as POSITIVE.
- **Any subject and any timeframe**: caregiver, parent, child, sibling, relative; current, historical, recent, longstanding. (Resolved-past-with-no-current-bearing rule applies — see Edge cases.)

## What does NOT count (NEGATIVE / FALSE POSITIVES)

- **Non-beverage alcohol products**: rubbing alcohol, isopropyl alcohol, isopropanol, denatured alcohol, methanol; hand sanitizer or alcohol-based gel; alcohol wipes, alcohol prep pads, alcohol swabs; alcohol-based cleaning products; alcohol used as a topical antiseptic. These are NEGATIVE unless the narrative specifies ingestion as a substitute for beverage alcohol (then POSITIVE).
- **Cooking / culinary alcohol with no consumption signal**: "wine used in cooking," "rum cake," "cooking sherry" — NEGATIVE unless an actual drinking event is described.
- **Religious / sacramental use**: a sip of communion wine, kiddush wine, ceremonial use with no other drinking signal — NEGATIVE.
- **Education / awareness / training only**: a school assembly on the dangers of drinking, a DARE-style program, a MADD presentation, a community AA awareness flyer — NEGATIVE if no use event is described.
- **Historical use fully resolved with sustained sobriety and no current bearing**: "Mother is a recovering alcoholic with 15 years of sobriety and no current concerns" — NEGATIVE. (If the past episode has a current consequence — custody loss, lingering health problem, ongoing AA attendance — apply the edge-case table.)
- **Negation**: "denies any alcohol use," "no history of drinking," "no alcohol involved," "alcohol was ruled out," "negative for alcohol on screen" — NEGATIVE.
- **Non-alcohol substance use without alcohol mention**: cannabis, opioids, methamphetamine, cocaine, benzodiazepines used without any mention of drinking — NEGATIVE for *this* construct (they belong to other constructs).
- **Medical/professional context where the named party is not the case subject**: a clinician describing alcohol screening protocols, a worker mentioning AUDIT-C as a routine assessment tool with no positive result for the case subject — NEGATIVE.
- **Person names / surnames / place names that overlap with alcohol terms**: "Mr. Beer," "Wine Street," "Brandy" as a child's name, "Sherry" as a caregiver's first name — NEGATIVE unless context makes the drinking reference explicit.
- **Hypothetical references**: "if she were to start drinking again," "in case of relapse" — NEGATIVE unless a concrete current or historical use event is also described.
- **Idiom / metaphor**: "drunk with power," "wine and dine," "small beer" (meaning trivial) — NEGATIVE.
- **Brand-name overlap with non-alcohol products**: "Corona" referring to the virus or to a vehicle/place; "Bud" as a nickname; "Jack" as a person's name — NEGATIVE unless context makes the alcohol reference explicit.

## Edge cases — resolve by rule

The labeling prompt examples (in `alcohol_construct_published_style.md`)
cover the canonical edge cases for this construct. Apply this rule:
**if a candidate record fits one of the prompt's negative-example
patterns, it is NEGATIVE**; **if it fits a positive-example pattern, it
is POSITIVE**; otherwise apply the operational definition and the
inclusion/exclusion lists above.

| Pattern | Rule |
|---|---|
| Resolved past with no current bearing | NEGATIVE |
| Hypothetical or speculative reference only | NEGATIVE |
| Metaphor, idiom, name overlap, brand-as-name | NEGATIVE |
| Awareness, education, training, or presentation only | NEGATIVE |
| Non-beverage alcohol product (rubbing alcohol, sanitizer, wipes) with no ingestion | NEGATIVE |
| Cooking or religious/sacramental use with no consumption signal | NEGATIVE |
| Negation ("denies," "no use," "ruled out," "negative screen") | NEGATIVE |
| Genuine reference with current applicability | POSITIVE |
| Past episode whose effect on current functioning persists (ongoing AA, lingering health issue, custody consequence) | POSITIVE |
| Social drinking explicitly described as light / occasional / no impairment / no caregiving impact | NEGATIVE (see below) |
| Any drinking described with intoxication, impairment, caregiving interference, or legal involvement | POSITIVE |

**Decision boundary — social drinking vs. problematic use.** Bare mentions of "social drinking" or "a glass of wine with dinner" with no caregiving impact, no impairment, no frequency/quantity escalation, and no AUD language are NEGATIVE. Any drinking described in the context of caregiving impairment, legal involvement, treatment, frequency/quantity escalation, withdrawal, or AUD language is POSITIVE.

## How to handle uncertainty

If the construct-related content is too sparse to apply the rules above,
or if the narrative is incomplete in a way that prevents a clear
judgment (e.g., a one-word reference to "drinking" with no surrounding
context), mark **UNCERTAIN**. Default to UNCERTAIN rather than guessing.
The pipeline reports UNCERTAIN records separately from POSITIVE and
NEGATIVE and they are routed out of the LLM-labeled training pool.
Indicator prompt or specification
# Alcohol Detection Prompt

You are tasked with analyzing text from Michigan CPS disposition narratives to detect mentions of **beverage alcohol use** while distinguishing them from non-beverage alcohol products (rubbing alcohol, hand sanitizer, alcohol wipes), homonyms, brand-as-name overlap, awareness/training references, and resolved-past use with no current bearing. The construct is grounded in standard DSM-5 use/mentions scope: any genuine drinking episode, intoxication, alcohol-related legal event, treatment for alcohol use disorder, withdrawal, or perinatal alcohol exposure counts. Severity grading is not required.

## Instructions

1. Carefully read the provided text.
2. Identify ANY mention of beverage alcohol use, intoxication, alcohol-related legal events (DUI/OWI/DWI/MIP), alcohol use disorder, alcohol treatment or recovery (AA, naltrexone/Antabuse/acamprosate, detox, rehab), alcohol withdrawal, or perinatal alcohol exposure, for any subject (caregiver, parent, child, sibling, relative) at any timeframe (current or historical with current bearing).
3. Distinguish problem-level beverage alcohol involvement from false positives: non-beverage alcohol products, cooking or religious use with no consumption signal, awareness/training references with no use event, negation, person/place/brand names that overlap with alcohol terms, and fully resolved past use with documented sustained sobriety and no current bearing.
4. Extract the EXACT terms used in the text (do not paraphrase).
5. For EVERY extracted term (true or false positive), include the complete sentence(s) containing that term. When multiple sentences contain relevant terms, separate each sentence with a semicolon (;).
6. If the text contains both genuine alcohol use AND a lookalike (e.g., "father drank a six-pack" + "the nurse used an alcohol wipe"), record the genuine reference under true positives AND the lookalike under false positives, so the labeling decision is auditable.

## What counts as an alcohol mention (TRUE POSITIVES)

The trigger is consumption of (or problem involvement with) beverage alcohol, at any time, by any subject. Bare mentions are sufficient if they describe an actual use event, treatment, legal event, withdrawal, or perinatal exposure — diagnostic certainty is NOT required.

- **Beverage alcohol in a use context:** beer, wine, liquor, hard liquor, vodka, whiskey, bourbon, scotch, gin, rum, tequila, brandy, cognac, champagne, malt liquor, hard seltzer, fortified wine, moonshine, homemade alcohol, "drinks," "drinking," "a drink," "drank," "had been drinking."
- **Intoxication / impairment:** drunk, intoxicated, inebriated, under the influence (of alcohol), buzzed, tipsy, hammered, wasted, blackout / blacked out, passed out drunk, smelled of alcohol, slurred speech attributed to drinking, BAC / blood alcohol concentration above zero.
- **Alcohol-related legal events:** DUI, DWI, OWI, OUI, drunk driving, driving while intoxicated, open container, public intoxication, MIP (minor in possession), zero-tolerance violation, ignition interlock requirement, alcohol-related arrest or probation condition.
- **Alcohol use disorder language:** alcoholism, alcoholic, alcohol abuse, alcohol dependence, alcohol use disorder, AUD, problem drinking, binge drinking, heavy drinking, drinking problem, "drinks too much."
- **Treatment / recovery:** AA (Alcoholics Anonymous), 12-step for alcohol, alcohol treatment, alcohol rehab, detox for alcohol, inpatient/outpatient for drinking, sober living for alcohol, naltrexone for AUD, Vivitrol for AUD, acamprosate/Campral, disulfiram/Antabuse, SMART Recovery for alcohol.
- **Withdrawal:** alcohol withdrawal, delirium tremens, DTs, withdrawal seizure attributed to alcohol cessation, the "shakes" from stopping drinking.
- **Caregiving while intoxicated:** parent drunk while supervising children, driving children while drunk, leaving children alone to go drinking, passing out drunk in the home.
- **Perinatal / fetal alcohol:** drinking during pregnancy, prenatal alcohol exposure, fetal alcohol spectrum disorder (FASD), fetal alcohol syndrome (FAS), positive alcohol or EtG test at delivery.
- **Disclosure / collateral report:** the subject states they drink heavily; a relative reports the parent "drinks every night"; a child describes a parent's drinking.

## What does NOT count (FALSE POSITIVES / LOOKALIKES)

Reject the following explicitly. If the text contains ONLY these patterns and no genuine alcohol use event, return `alcohol_mentioned: false`.

- **Non-beverage alcohol products:** rubbing alcohol, isopropyl alcohol, isopropanol, denatured alcohol, methanol, hand sanitizer, alcohol-based gel, alcohol wipes / prep pads / swabs, alcohol-based cleaners or antiseptics. These are NEGATIVE unless the narrative explicitly describes ingestion as a substitute for beverage alcohol.
- **Cooking / culinary alcohol** with no consumption signal: cooking sherry, wine reduction, rum cake, beer-battered fish — NEGATIVE unless an actual drinking event is described.
- **Religious / sacramental use:** a sip of communion wine, kiddush wine, ceremonial use with no other drinking signal — NEGATIVE.
- **Awareness / education / training only:** a school assembly on underage drinking, a DARE program, a MADD presentation, a community AA awareness flyer — NEGATIVE if no use event is described.
- **Historical use fully resolved with sustained sobriety and no current bearing:** "Mother is a recovering alcoholic with 20 years of sobriety and no current concerns" — NEGATIVE. (If the past episode has a current consequence — ongoing AA attendance, lingering health problem, custody consequence — it is POSITIVE.)
- **Negation:** "denies any alcohol use," "no history of drinking," "no alcohol involved," "alcohol was ruled out," "negative for alcohol on the screen" — NEGATIVE.
- **Other substances without alcohol mention:** cannabis, opioids, methamphetamine, cocaine, benzodiazepines used without any mention of drinking — NEGATIVE for this construct.
- **Person names / place names / brand names** that overlap with alcohol terms: "Mr. Beer," "Wine Street," "Brandy" as a child's name, "Sherry" as a caregiver's first name, "Bud" or "Jack" as a nickname, "Corona" referring to the virus or a vehicle — NEGATIVE unless context makes the alcohol reference explicit.
- **Hypothetical / speculative:** "if she were to start drinking again," "in case of relapse" — NEGATIVE unless a concrete current or historical use event is also described.
- **Idiom / metaphor:** "drunk with power," "wine and dine," "small beer," "drunk on love" — NEGATIVE.

## Output format

Return your analysis in this exact JSON format. The top-level boolean key MUST be named `alcohol_mentioned`. No other format is allowed.

```json
{
  "alcohol_mentioned": true,
  "tp_terms": ["exact term 1", "exact term 2"],
  "fp_terms": ["lookalike term 1"],
  "tp_context": "EXACT sentence(s) containing the genuine alcohol term(s), separated by semicolons",
  "fp_context": "EXACT sentence(s) containing the lookalike/false-positive term(s), separated by semicolons"
}
```

If no alcohol-related content is present, return `alcohol_mentioned: false` with empty arrays and empty strings for context fields. Always populate `fp_terms` and `fp_context` when a lookalike was present and rejected, so the rejection reasoning is auditable.

## Example responses

**Text:** "The mother was arrested for OWI after she crashed the family vehicle with the children in the back seat. Her BAC was 0.18. She also admitted to drinking a fifth of vodka most evenings."

```json
{
  "alcohol_mentioned": true,
  "tp_terms": ["OWI", "BAC was 0.18", "drinking a fifth of vodka"],
  "fp_terms": [],
  "tp_context": "The mother was arrested for OWI after she crashed the family vehicle with the children in the back seat.; Her BAC was 0.18.; She also admitted to drinking a fifth of vodka most evenings.",
  "fp_context": ""
}
```

**Text:** "The nurse used an alcohol prep pad to clean the injection site before the child's vaccination. The family was instructed to use hand sanitizer before meals."

```json
{
  "alcohol_mentioned": false,
  "tp_terms": [],
  "fp_terms": ["alcohol prep pad", "hand sanitizer"],
  "tp_context": "",
  "fp_context": "The nurse used an alcohol prep pad to clean the injection site before the child's vaccination.; The family was instructed to use hand sanitizer before meals."
}
```

**Text:** "Mother attended a school assembly on the dangers of underage drinking last spring. She denies any current alcohol use and a recent breathalyzer at the supervised visit was negative."

```json
{
  "alcohol_mentioned": false,
  "tp_terms": [],
  "fp_terms": ["school assembly on the dangers of underage drinking", "denies any current alcohol use", "breathalyzer ... was negative"],
  "tp_context": "",
  "fp_context": "Mother attended a school assembly on the dangers of underage drinking last spring.; She denies any current alcohol use and a recent breathalyzer at the supervised visit was negative."
}
```

**Text:** "Father has a history of cocaine use and drinks heavily throughout the week, often becoming intoxicated and verbally aggressive toward the children. He named his daughter Brandy after his late grandmother."

```json
{
  "alcohol_mentioned": true,
  "tp_terms": ["drinks heavily", "intoxicated"],
  "fp_terms": ["Brandy"],
  "tp_context": "Father has a history of cocaine use and drinks heavily throughout the week, often becoming intoxicated and verbally aggressive toward the children.",
  "fp_context": "He named his daughter Brandy after his late grandmother."
}
```

Analyze the following text:

[INSERT TEXT HERE]
Opioids2 document(s)
Indicator prompt or specification
# Opioid Detection Prompt — construct-extraction style

This prompt detects opioid-related concerns specifically (a narrower
construct than substance-related problems broadly). Grounded in
Perron et al. 2022 definitional work. Output format matches the
construct-extraction JSON schema expected by the autonomous labeling
pipeline (`opioid_mentioned` boolean).

## Instructions

1. Carefully read the provided text.
2. Identify ANY mention of opioid-related concerns — heroin, fentanyl,
   prescription opioids misused or abused, methadone/suboxone treatment,
   neonatal abstinence syndrome from opioid exposure, opioid overdoses,
   opioid-related legal involvement.
3. Distinguish problem-level opioid involvement from prescribed
   medication use with no misuse signal, fully-resolved past opioid
   use, or non-opioid substance use.
4. Extract the exact terms used and full surrounding sentences as
   context.
5. When multiple sentences contain opioid-relevant terms, separate
   each sentence with a semicolon (;).

## What counts as an opioid mention (TRUE POSITIVES)

Inclusive: any of these terms counts as a true positive when the
involvement rises to a child-welfare or clinical concern.

- **Specific opioids:** heroin, fentanyl, carfentanil, morphine,
  codeine
- **Prescription opioids:** oxycodone, OxyContin, hydrocodone, Vicodin,
  Percocet, hydromorphone, Dilaudid, Tramadol — when described as
  misused, abused, illicitly obtained, or in the context of a
  substance-use disorder
- **Replacement / treatment medications:** methadone, suboxone,
  buprenorphine — when describing the caregiver's treatment status,
  diversion, or unaccompanied use
- **Reversal / overdose:** naloxone (Narcan) administration to a
  caregiver, opioid overdose, opioid-induced respiratory depression
- **Use disorder language:** opioid use disorder, opioid dependence,
  opioid addiction, opioid abuse, IV drug use (when context indicates
  opioids), shooting up
- **Neonatal/perinatal:** NAS (neonatal abstinence syndrome) from
  opioid exposure, drug-exposed infant where opioid is implicated,
  meconium positive for opioids, methadone-exposed newborn
- **Legal:** opioid-related arrest, felony possession of opioids,
  trafficking, drug court for opioid offense
- **Disclosure of current use:** "father reports daily heroin use",
  "mother continues to use fentanyl despite case plan"

## What does NOT count (FALSE POSITIVES)

- **Prescribed opioids used as directed** for documented chronic pain
  or post-surgical pain WITHOUT a misuse, abuse, or diversion signal.
- **Historical opioid use clearly resolved** with documented sustained
  sobriety and no current concerns.
- **Awareness or education programs** about opioids without an actual
  use event ("father attended a Narcan training" alone).
- **Non-opioid substance use** (alcohol, cocaine, methamphetamine,
  marijuana, benzodiazepines without opioids).
- **Medical or professional context** (the nurse administered morphine
  for hospitalized pain management, the EMT used naloxone on someone
  else not in the case family).
- **Person names** containing opioid-suggestive words (rare; e.g., a
  nickname like "Doc").
- **Hypothetical references** ("if opioid use were present...").

## Output format

Return your analysis in this exact JSON format. The top-level boolean
key MUST be named `opioid_mentioned`. No other format is allowed.

```json
{
  "opioid_mentioned": true,
  "opioid_terms": ["exact term 1", "exact term 2"],
  "true_positive_context": "EXACT sentence(s) containing genuine opioid-related term(s), separated by semicolons",
  "false_positive_terms": ["false positive term 1"],
  "false_positive_context": "EXACT sentence(s) containing the false positive term(s)"
}
```

## Example responses

**Text:** "Mother tested positive for fentanyl and morphine at the time of the child's birth. Infant was diagnosed with NAS and remained in NICU for 12 days."

```json
{
  "opioid_mentioned": true,
  "opioid_terms": ["tested positive for fentanyl and morphine", "NAS"],
  "true_positive_context": "Mother tested positive for fentanyl and morphine at the time of the child's birth.; Infant was diagnosed with NAS and remained in NICU for 12 days.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

**Text:** "Father takes prescribed Vicodin for chronic back pain following his 2022 surgery. Documentation of his prescription is on file and no misuse concerns were observed."

```json
{
  "opioid_mentioned": false,
  "opioid_terms": [],
  "true_positive_context": "",
  "false_positive_terms": ["prescribed Vicodin"],
  "false_positive_context": "Father takes prescribed Vicodin for chronic back pain following his 2022 surgery."
}
```

**Text:** "Mother attended a Narcan administration training at the community health center last month."

```json
{
  "opioid_mentioned": false,
  "opioid_terms": [],
  "true_positive_context": "",
  "false_positive_terms": ["Narcan administration training"],
  "false_positive_context": "Mother attended a Narcan administration training at the community health center last month."
}
```

## Text to analyze

[INSERT TEXT HERE]
Seed examples — used to retrieve candidate narratives
# AUTO-GENERATED SEEDS — Opioid construct (Perron 2022 definition)
# Generated by Claude (frontier model) from the published construct definition.
# Construct: identification of opioid-related concerns specifically (not
# substance-related problems broadly). Includes heroin, fentanyl,
# prescription opioids misused or abused, methadone, suboxone, NAS from
# opioids, opioid overdoses, opioid-related arrests.
# Claude was not shown any of the Qi 2026 / Perron 2022 gold test records.

positive_seeds:
  - "Mother tested positive for fentanyl and morphine at the time of the child's birth."
  - "Father has an active opioid use disorder and was discharged from suboxone treatment last month for non-compliance."
  - "The infant was diagnosed with neonatal abstinence syndrome secondary to maternal heroin use during pregnancy."
  - "Mother has a documented history of intravenous heroin use and was found unresponsive from a suspected opioid overdose."
  - "Father is currently enrolled at the local methadone clinic following a recent fentanyl-positive drug screen."
  - "The 16-year-old daughter reported finding her mother's hidden stash of oxycodone pills in the bathroom."
  - "Mother admitted to misusing her prescribed Vicodin and obtaining additional hydrocodone from acquaintances."
  - "Father was revived with naloxone at the residence after a heroin overdose witnessed by the children."
  - "Mother continues to test positive for fentanyl despite court-ordered substance use treatment."
  - "The maternal aunt reported that the father is actively selling oxycontin out of the home."
  - "Mother is on probation following a felony arrest for possession of heroin with intent to distribute."
  - "Father was hospitalized for an opioid overdose involving counterfeit Percocet pills laced with fentanyl."
  - "The toddler ingested a small amount of methadone that was left accessible by the mother on the coffee table."
  - "Mother reports daily use of suboxone purchased from non-medical sources to manage withdrawal symptoms."
  - "Father has multiple prior arrests for opioid-related charges and was recently released from drug court."

negative_seeds:
  - "Father takes prescribed Vicodin for chronic back pain with documented appropriate use and no concerns."
  - "Mother attended a community education session on opioid awareness and naloxone training last spring."
  - "Father reports a history of opioid use that was fully resolved with treatment in 2017 and there are no current concerns."
  - "The maternal grandmother works as a nurse and administers prescribed pain medications at her hospital."
  - "Mother uses prescribed tramadol post-surgery as directed by her physician with no signs of misuse."
  - "Father drinks alcohol heavily on weekends but reports no opioid use or other drug use."
  - "The teenager attended a school assembly about the dangers of fentanyl in the community."
  - "Mother is a recovering addict with 12 years of sustained sobriety from opioids."
  - "Father uses prescribed gabapentin for nerve pain but no opioids are involved in his medication regimen."
  - "The family has methadone-related training scheduled as part of a community parenting class."
Stimulants2 document(s)
Codebook — what counts as a positive
# Codebook — Stimulant Use

## Operational definition

Stimulant Use is any indication that a person connected to the case is using, has used, possesses, manufactures, distributes, tests positive for, or has documented problems involving a stimulant substance. The construct covers cocaine-class stimulants (cocaine, crack) and amphetamine-type stimulants (methamphetamine, illicit amphetamine, MDMA/ecstasy/molly, prescription stimulants used non-medically — Adderall, Ritalin, Vyvanse, Concerta, Dexedrine, Focalin). The trigger is the substance identity in a use, misuse, possession, distribution, intoxication, withdrawal, treatment, neonatal exposure, or stimulant-related legal context — at any point in time and for any subject (caregiver, child, household member, relative, or other named person). The construct is distinct from opioid use, alcohol use, marijuana use, or polysubstance terms that do not specifically implicate a stimulant. Prescribed stimulant medication taken as directed for documented ADHD (or other legitimate indication) with no diversion, misuse, or non-compliance signal is NOT positive.

## What counts as POSITIVE

- **Cocaine class:** cocaine, crack, crack cocaine, freebase, powder cocaine, coke, blow, snow, key/kilo, eight-ball, rock (in a drug context), bump, line, lines.
- **Amphetamine-type:** methamphetamine, meth, crystal, crystal meth, ice, glass, shards, tweak/tweaking, speed, crank, go-fast, amphetamine, dextroamphetamine.
- **MDMA / club stimulants:** MDMA, ecstasy, molly, X, rolling.
- **Prescription stimulants in a misuse context:** Adderall, Ritalin, Vyvanse, Concerta, Dexedrine, Focalin, methylphenidate, dextroamphetamine — when described as misused, abused, snorted, injected, sold, diverted, taken without a prescription, taken from another person's prescription, taken in excess of prescribed dose, or obtained illicitly.
- **Use disorder / problem language:** stimulant use disorder, cocaine use disorder, methamphetamine use disorder, amphetamine dependence, cocaine addiction, meth addiction, "addicted to coke", "addicted to meth", "binge using meth".
- **Toxicology / drug screens:** positive UA / urine drug screen / hair follicle / meconium for cocaine, methamphetamine, amphetamines, or MDMA; "tested positive for meth"; "BE-positive" (benzoylecgonine, cocaine metabolite).
- **Neonatal / perinatal:** infant born exposed to cocaine or methamphetamine, meconium positive for stimulants, neonatal stimulant exposure, "cocaine baby", "meth baby", in-utero exposure to stimulants, "mother used meth during pregnancy".
- **Intoxication / acute effects:** acute methamphetamine intoxication, stimulant-induced psychosis, "tweaking", "high on meth", "high on coke", stimulant overdose, cocaine-induced cardiac event.
- **Manufacturing / distribution / paraphernalia:** meth lab, cooking meth, manufacturing methamphetamine, pseudoephedrine purchases for meth production, selling/dealing/trafficking cocaine or meth, possession of crack pipes, glass pipes used for meth, baggies of white powder, rolled bills with residue, scale, presence of stimulant residue in the home.
- **Legal:** arrest, charge, or conviction for possession, distribution, manufacture, or trafficking of cocaine, crack, methamphetamine, amphetamine, or MDMA; drug court for stimulant offenses.
- **Disclosure of current or recent use:** self-report or admission of cocaine, crack, meth, or non-prescribed Adderall/Ritalin/Vyvanse use; "mother admitted to using meth last week"; "father reports daily cocaine use".
- **Treatment for a stimulant problem:** inpatient/outpatient/residential SUD treatment, intensive outpatient (IOP), or detox explicitly for cocaine or methamphetamine; contingency management for stimulant use disorder.
- Any subject (caregiver, parent, child, adolescent, household member, relative, or other named person) and any timeframe (current, recent, historical with current bearing).

## What does NOT count

- **Prescribed stimulants used as directed.** Documented ADHD with a current Adderall, Ritalin, Vyvanse, Concerta, Focalin, or Dexedrine prescription taken as directed, with no diversion, misuse, snorting, sharing, or non-compliance signal.
- **Caffeine and over-the-counter stimulants** (caffeine, coffee, energy drinks, NoDoz, pseudoephedrine taken as decongestant per directions, ephedra supplements) absent any misuse context.
- **Nicotine, vaping, tobacco** mentions — these are not in scope even though nicotine is technically a stimulant.
- **Non-stimulant substance use only.** Alcohol-only, marijuana-only, opioid-only, benzodiazepine-only, hallucinogen-only, or inhalant-only mentions with no stimulant named.
- **Generic "substance use" / "drug use" / "AOD" mentions** that do not name a stimulant or describe a stimulant-specific behavior. Polysubstance disclosures count ONLY if a stimulant substance is specifically named or strongly implied.
- **Historical use clearly resolved** with documented sustained sobriety, completed treatment, and no current concerns or current bearing on parenting capacity.
- **Awareness / education / prevention / training only** about cocaine or meth, with no actual use event ("teen attended a school assembly about the dangers of meth").
- **Medical or professional context** where the named party is administering, prescribing, or handling stimulants but is not the case subject (a pharmacist who dispenses Adderall; a nurse who manages a hospitalized patient's stimulant medication).
- **Person names / homographs / brand collisions** ("Crystal" as a first name; "Snow" as a last name; "Ice" as a nickname; the band/store/product "Coke" referring to Coca-Cola).
- **Hypothetical references** ("if meth use were present, we would..."; "the worker asked whether there was any cocaine in the home, and the mother denied").
- **Explicit negation** ("denies any cocaine or methamphetamine use", "no history of stimulant use", "all UAs negative for stimulants").
- **Slang collisions in non-drug context** ("we had a blast" — not "blast" as crack; "she was riding the speed train" idiomatic; "blow" meaning to exhale or to spend money).
- **Metaphor and idiom** ("the kids are bouncing off the walls like they're on speed"; "this case has been a rollercoaster").

## Edge cases — resolve by rule

The labeling prompt examples (in the corresponding
`stimulants_construct_published_style.md`) cover the canonical edge cases
for this construct. Apply this rule: **if a candidate record fits one of
the prompt's negative-example patterns, it is NEGATIVE**; **if it fits a
positive-example pattern, it is POSITIVE**; otherwise apply the
operational definition and the inclusion/exclusion lists above.

| Pattern | Rule |
|---|---|
| Resolved past with no current bearing | NEGATIVE |
| Hypothetical or speculative reference only | NEGATIVE |
| Explicit negation ("denies cocaine use", "UA negative for meth") | NEGATIVE |
| Metaphor, idiom, name overlap ("Crystal" as a person; "speed" as velocity) | NEGATIVE |
| Awareness, training, drill, or prevention education only | NEGATIVE |
| Prescribed stimulant used as directed for documented ADHD, no misuse | NEGATIVE |
| Caffeine, energy drinks, OTC pseudoephedrine taken as directed | NEGATIVE |
| Nicotine / vaping / tobacco only | NEGATIVE |
| Generic "substance use" with no stimulant named | NEGATIVE |
| Non-stimulant substance only (alcohol, marijuana, opioids only) | NEGATIVE |
| Genuine stimulant reference with current applicability | POSITIVE |
| Past stimulant episode whose effect on current functioning persists | POSITIVE |
| Diversion or misuse of prescribed stimulant (snorted Adderall, sold Ritalin) | POSITIVE |
| Positive UA / hair / meconium for cocaine, meth, amphetamine, or MDMA | POSITIVE |

## How to handle uncertainty

If the construct-related content is too sparse to apply the rules above,
or if the narrative is incomplete in a way that prevents a clear judgment
(for example, "drug paraphernalia found in the home" with no substance
named and no further context), mark **UNCERTAIN**. Default to UNCERTAIN
rather than guessing. The pipeline reports UNCERTAIN records separately
from POSITIVE and NEGATIVE and they are routed out of the LLM-labeled
training pool.
Indicator prompt or specification
# Stimulant Use Detection Prompt — construct-extraction style

This prompt detects stimulant-related concerns specifically — cocaine
class (cocaine, crack) and amphetamine-type stimulants (methamphetamine,
illicit amphetamine, MDMA/ecstasy, and prescription stimulants such as
Adderall, Ritalin, Vyvanse, Concerta, Focalin, Dexedrine used
non-medically). Grounded in DSM-5 stimulant use definitions and standard
child-welfare narrative conventions. Output format matches the
construct-extraction JSON schema expected by the autonomous labeling
pipeline (`stimulants_mentioned` boolean).

## Instructions

1. Carefully read the provided text.
2. Identify ANY mention of stimulant-related concerns — cocaine, crack,
   methamphetamine, amphetamine, MDMA/ecstasy/molly, or prescription
   stimulants (Adderall, Ritalin, Vyvanse, Concerta, Focalin, Dexedrine,
   methylphenidate, dextroamphetamine) used non-medically; positive UA
   or meconium screens for these substances; stimulant overdose,
   stimulant-induced psychosis, stimulant use disorder; meth labs,
   manufacturing, distribution, or trafficking; stimulant-related legal
   involvement.
3. Distinguish problem-level stimulant involvement from prescribed
   stimulants used as directed for documented ADHD with no misuse
   signal, fully-resolved past stimulant use, education-only mentions,
   caffeine/nicotine/energy drinks, or non-stimulant substance use
   (alcohol only, marijuana only, opioids only).
4. Treat the following LOOKALIKE concepts as NOT this construct: (a)
   prescribed Adderall/Ritalin/Vyvanse used as directed for ADHD; (b)
   caffeine, coffee, energy drinks, NoDoz; (c) over-the-counter
   pseudoephedrine taken as a decongestant with no manufacturing
   context; (d) nicotine, vaping, tobacco; (e) generic "drug use" /
   "substance use" / "AOD" mentions with no stimulant named; (f) person
   names or product names that collide with stimulant slang ("Crystal"
   as a first name, "Snow" as a surname, "Ice" as a nickname, "Coke" as
   Coca-Cola); (g) idioms and metaphors ("bouncing off the walls like
   they're on speed", "kids are wired"); (h) explicit negations
   ("denies cocaine use", "UA negative for meth").
5. Extract the exact terms used and full surrounding sentences as
   context.
6. When multiple sentences contain stimulant-relevant terms, separate
   each sentence with a semicolon (;).

## What counts as a stimulant mention (TRUE POSITIVES)

Inclusive: any of these terms counts as a true positive when the
involvement rises to a child-welfare or clinical concern.

- **Cocaine class:** cocaine, crack, crack cocaine, freebase, powder
  cocaine, coke, blow, snow, eight-ball, key/kilo, bump, line(s), rock
  (in drug context).
- **Amphetamine-type:** methamphetamine, meth, crystal, crystal meth,
  ice, glass, shards, tweak/tweaking, speed, crank, go-fast,
  amphetamine, dextroamphetamine.
- **MDMA / club stimulants:** MDMA, ecstasy, molly, X, rolling.
- **Prescription stimulants — when misused:** Adderall, Ritalin,
  Vyvanse, Concerta, Dexedrine, Focalin, methylphenidate,
  dextroamphetamine — when described as misused, abused, snorted,
  injected, diverted, sold, taken without a prescription, taken from
  another person's prescription, or obtained illicitly.
- **Toxicology / screens:** positive urine drug screen, hair follicle,
  or meconium for cocaine, methamphetamine, amphetamines, or MDMA;
  "tested positive for meth"; benzoylecgonine (BE) positive.
- **Use disorder language:** stimulant use disorder, cocaine use
  disorder, methamphetamine use disorder, amphetamine dependence,
  cocaine addiction, meth addiction, "addicted to coke", "binging on
  meth".
- **Neonatal / perinatal:** infant born exposed to cocaine or
  methamphetamine, meconium positive for stimulants, "cocaine baby",
  "meth baby", in-utero exposure to stimulants, maternal stimulant use
  during pregnancy.
- **Intoxication / acute effects:** acute methamphetamine intoxication,
  stimulant-induced psychosis, stimulant overdose, cocaine-induced
  cardiac event, "tweaking", "high on meth".
- **Manufacturing / paraphernalia:** meth lab, cooking meth,
  pseudoephedrine purchases for meth production, crack pipes, glass
  pipes used for meth, baggies of white powder with use context,
  cutting agents, scales with residue.
- **Legal:** arrest, charge, or conviction for possession,
  distribution, manufacture, or trafficking of cocaine, crack,
  methamphetamine, amphetamine, or MDMA; drug court for stimulant
  offenses.
- **Disclosure of current or recent use:** self-report of cocaine,
  crack, meth, or non-prescribed Adderall/Ritalin/Vyvanse use; "mother
  admitted to using meth last week"; "father continues to use cocaine
  despite case plan".
- **Treatment for a stimulant problem:** SUD treatment, inpatient,
  outpatient, IOP, residential, detox, or contingency management
  explicitly for cocaine or methamphetamine.

## What does NOT count (FALSE POSITIVES)

- **Prescribed stimulants used as directed** for documented ADHD or
  another legitimate indication, with no diversion, misuse, snorting,
  sharing, or non-compliance signal.
- **Caffeine and OTC stimulants:** coffee, energy drinks, NoDoz,
  ephedra supplements, pseudoephedrine taken as a decongestant per
  directions.
- **Nicotine, vaping, tobacco** — out of scope.
- **Non-stimulant substance use only:** alcohol-only, marijuana-only,
  opioid-only, benzodiazepine-only, hallucinogen-only, or
  inhalant-only mentions with no stimulant named.
- **Generic "substance use" / "drug use" / "AOD"** mentions that do
  not name a stimulant or describe a stimulant-specific behavior.
- **Historical stimulant use clearly resolved** with documented
  sustained sobriety and no current concerns.
- **Awareness or education programs** about cocaine or meth without an
  actual use event ("teen attended a school assembly on the dangers of
  meth").
- **Medical or professional context** where the named party is
  administering, prescribing, or handling stimulants but is not the
  case subject (a pharmacy technician dispensing Adderall, a nurse
  managing a hospitalized patient's medication).
- **Person names / homographs / brand collisions:** "Crystal" as a
  first name, "Snow" as a surname, "Ice" as a nickname, "Coke"
  referring to Coca-Cola.
- **Hypothetical references** ("if meth use were present, the case
  plan would include...").
- **Explicit negation:** "denies any cocaine or methamphetamine use",
  "no history of stimulant use", "all UAs negative for stimulants".
- **Metaphor and idiom:** "kids are bouncing off the walls like
  they're on speed", "case has been a rollercoaster", "she had a
  blast" (not crack).

## Output format

Return your analysis in this exact JSON format. The top-level boolean
key MUST be named `stimulants_mentioned`. No other format is allowed.

```json
{
  "stimulants_mentioned": true,
  "tp_terms": ["exact term 1", "exact term 2"],
  "tp_context": "EXACT sentence(s) containing genuine stimulant-related term(s), separated by semicolons",
  "fp_terms": ["false positive term 1"],
  "fp_context": "EXACT sentence(s) containing the false positive term(s), showing why the lookalike was rejected"
}
```

## Example responses

**Text:** "Mother tested positive for cocaine and methamphetamine on her court-ordered urine drug screen last week. The infant's meconium also returned positive for amphetamines, and mother admitted to using meth during the third trimester."

```json
{
  "stimulants_mentioned": true,
  "tp_terms": ["tested positive for cocaine and methamphetamine", "meconium also returned positive for amphetamines", "using meth during the third trimester"],
  "tp_context": "Mother tested positive for cocaine and methamphetamine on her court-ordered urine drug screen last week.; The infant's meconium also returned positive for amphetamines, and mother admitted to using meth during the third trimester.",
  "fp_terms": [],
  "fp_context": ""
}
```

**Text:** "Father takes prescribed Adderall 20 mg twice daily for his documented adult ADHD. His psychiatrist confirms appropriate medication compliance and there are no diversion or misuse concerns on file."

```json
{
  "stimulants_mentioned": false,
  "tp_terms": [],
  "tp_context": "",
  "fp_terms": ["prescribed Adderall 20 mg twice daily"],
  "fp_context": "Father takes prescribed Adderall 20 mg twice daily for his documented adult ADHD.; His psychiatrist confirms appropriate medication compliance and there are no diversion or misuse concerns on file."
}
```

**Text:** "The mother's name is Crystal and she has lived at the current address for three years. She denies any history of cocaine or methamphetamine use and her four most recent urine drug screens have all been negative for stimulants."

```json
{
  "stimulants_mentioned": false,
  "tp_terms": [],
  "tp_context": "",
  "fp_terms": ["Crystal", "denies any history of cocaine or methamphetamine use", "negative for stimulants"],
  "fp_context": "The mother's name is Crystal and she has lived at the current address for three years.; She denies any history of cocaine or methamphetamine use and her four most recent urine drug screens have all been negative for stimulants."
}
```

## Text to analyze

[INSERT TEXT HERE]
Sedatives, hypnotics, anxiolytics2 document(s)
Codebook — what counts as a positive
# Codebook — Sedative/Hypnotic/Anxiolytic Use

## Operational definition

Sedative/Hypnotic/Anxiolytic Use is any indication that a person connected to the case is using, has used, or is otherwise involved with a sedative, hypnotic, or anxiolytic medication in a way that signals problem-level involvement. The drug class includes benzodiazepines (alprazolam/Xanax, clonazepam/Klonopin, diazepam/Valium, lorazepam/Ativan, chlordiazepoxide/Librium, temazepam/Restoril, triazolam/Halcion, oxazepam, clobazam, midazolam/Versed), Z-drugs / non-benzodiazepine hypnotics (zolpidem/Ambien, eszopiclone/Lunesta, zaleplon/Sonata), barbiturates (phenobarbital, secobarbital/Seconal, butalbital, pentobarbital), carisoprodol (Soma), GHB and analogs (gamma-hydroxybutyrate, GBL, 1,4-butanediol), chloral hydrate, meprobamate, and similar CNS-depressant sedative/hypnotic/anxiolytic agents. Positive triggers are misuse, abuse, illicit acquisition, doctor-shopping, dependence, withdrawal, overdose, polysubstance combination (especially with opioids or alcohol), or any disclosure that the medication is being used outside of a legitimate, documented prescription. The construct covers any subject (caregiver, parent, child, sibling, relative, household member) and any timeframe (current, historical with current bearing, or past episode with persistent effect). The construct is distinct from opioid use, alcohol use, stimulant use, or general substance use language that does not specifically implicate a sedative/hypnotic/anxiolytic agent. Use of these medications as prescribed for documented anxiety, insomnia, seizure disorder, alcohol withdrawal, or perioperative care, with no misuse signal, is NOT positive.

## What counts as POSITIVE

- **Benzodiazepines:** alprazolam, Xanax, "bars", "footballs", "school buses", "zannies"; clonazepam, Klonopin, "K-pins"; diazepam, Valium, "blues"; lorazepam, Ativan; chlordiazepoxide, Librium; temazepam, Restoril; triazolam, Halcion; oxazepam, Serax; midazolam, Versed; clobazam, Onfi — when described as misused, abused, illicitly obtained, diverted, snorted, crushed, injected, taken outside of prescription, or in the context of a substance-use disorder.
- **Z-drugs / non-benzodiazepine hypnotics:** zolpidem, Ambien; eszopiclone, Lunesta; zaleplon, Sonata — when described as misused, abused, taken in excess, combined with alcohol, or otherwise used outside of prescription.
- **Barbiturates:** phenobarbital, secobarbital/Seconal, pentobarbital, butalbital, amobarbital, "downers", "barbs", "yellow jackets", "red devils", "blue heavens" — any non-medical use; legitimate barbiturate use is rare and warrants closer reading.
- **Other sedative-hypnotic / anxiolytic agents:** carisoprodol/Soma, meprobamate, chloral hydrate, methaqualone/Quaaludes/"ludes", buspirone in clearly non-prescribed contexts, GHB / gamma-hydroxybutyrate / "G" / "liquid X" / "liquid ecstasy", GBL, 1,4-butanediol.
- **Misuse, abuse, diversion, doctor-shopping behavior:** obtaining benzodiazepines from multiple prescribers, buying Xanax on the street, purchasing Ambien online without a prescription, taking another person's prescription, crushing or snorting pills, injecting benzodiazepines, selling or trading prescriptions, hoarding doses, escalating use without medical guidance.
- **Use disorder language:** sedative use disorder, benzodiazepine use disorder, benzo dependence, benzo addiction, benzo abuse, sedative dependence, hypnotic dependence, sedative withdrawal, benzodiazepine withdrawal syndrome.
- **Overdose / acute medical events:** benzodiazepine overdose, Xanax overdose, Ambien overdose, GHB overdose, mixed sedative overdose, sedative-related respiratory depression, flumazenil administration as reversal.
- **Polysubstance combination:** sedative/hypnotic/anxiolytic used in combination with opioids, alcohol, methadone, or other CNS depressants (the "Holy Trinity" of opioid + benzo + carisoprodol; "lean" with benzo addition; mixing Xanax with alcohol).
- **Perinatal / neonatal:** maternal benzodiazepine use during pregnancy, neonatal sedative withdrawal, infant born exposed to benzodiazepines, meconium positive for benzodiazepines.
- **Legal involvement:** arrest for possession of benzodiazepines without prescription, trafficking in Xanax or counterfeit benzodiazepine pills, DUI involving sedatives, charges related to GHB possession.
- **Disclosure of current problem use:** "mother takes Xanax that is not prescribed to her", "father has been buying Klonopin off the street", "caregiver admits to combining Ambien with alcohol to sleep".
- **Any subject:** caregiver, parent, child, adolescent, sibling, household member, relative, paramour.
- **Any timeframe:** current, historical with current bearing, or past episode whose effect on current functioning persists.

## What does NOT count (NEGATIVE / FALSE POSITIVES)

- **Prescribed benzodiazepine, Z-drug, or barbiturate used as directed** for documented anxiety, insomnia, panic disorder, PTSD, seizure disorder, alcohol withdrawal management, perioperative sedation, or similar legitimate indication, WITH NO misuse, diversion, escalation, or combination signal.
- **Historical sedative/hypnotic use clearly resolved** with documented sustained sobriety and no current bearing on the case.
- **Awareness, training, or education** about benzodiazepines, Z-drugs, or overdose response without an actual use event ("the family attended a community talk on benzo overdose").
- **Non-class substance use** (alcohol alone, opioids alone, cocaine, methamphetamine, marijuana, nicotine, hallucinogens) with no sedative/hypnotic/anxiolytic component named.
- **Medical or professional context** where the named party is not the case subject (a nurse who administers Versed in the operating room; an EMT who administered midazolam to someone outside the case family).
- **Person names, brand homographs, or non-drug uses** ("Ativan" appearing as a surname, "Soma" as a person's name, "Xanax" referenced in pop culture without a use event).
- **Hypothetical, ruled-out, or counterfactual references** ("if mother were taking benzos…"; "denies any benzodiazepine use"; "tested negative for benzodiazepines").
- **Generic 'sleeping pills' or 'nerve pills'** without any indication that the agent is sedative-class or that there is misuse — leave UNCERTAIN if the class cannot be inferred.
- **Other psychotropics that are NOT sedative/hypnotic/anxiolytic:** SSRIs (sertraline, fluoxetine, escitalopram), SNRIs (venlafaxine, duloxetine), antipsychotics (risperidone, quetiapine, olanzapine — even when used off-label for sleep), mood stabilizers, stimulants (Adderall, Ritalin), gabapentin, pregabalin (Lyrica), trazodone, hydroxyzine, melatonin, diphenhydramine (Benadryl). These are NEGATIVE for this construct even when described as misused.

## Edge cases — resolve by rule

The labeling prompt examples (in the corresponding
`sedatives_hypnotics_anxiolytics_construct_published_style.md`) cover the canonical edge cases for
this construct. Apply this rule: **if a candidate record fits one of the
prompt's negative-example patterns, it is NEGATIVE**; **if it fits a
positive-example pattern, it is POSITIVE**; otherwise apply the
operational definition and the inclusion/exclusion lists above.

| Pattern | Rule |
|---|---|
| Resolved past with no current bearing | NEGATIVE |
| Hypothetical or speculative reference only | NEGATIVE |
| Metaphor, idiom, name overlap (e.g., "Soma" as a name) | NEGATIVE |
| Awareness, training, drill, or preparedness only | NEGATIVE |
| Prescribed and used as directed with no misuse signal | NEGATIVE |
| Non-class substance (opioid only, alcohol only, stimulant only) | NEGATIVE |
| Genuine reference with current applicability | POSITIVE |
| Past episode whose effect on current functioning persists | POSITIVE |
| Polysubstance use where a sedative/hypnotic/anxiolytic is one of the named agents | POSITIVE |
| Doctor-shopping or diversion of a sedative/hypnotic/anxiolytic | POSITIVE |

## How to handle uncertainty

If the construct-related content is too sparse to apply the rules above
(for example, "mother takes a nerve pill" with no agent named and no
misuse signal), or if the narrative is incomplete in a way that prevents
a clear judgment, mark **UNCERTAIN**. Default to UNCERTAIN rather than
guessing. The pipeline reports UNCERTAIN records separately from POSITIVE
and NEGATIVE and they are routed out of the LLM-labeled training pool.
Indicator prompt or specification
# Sedative/Hypnotic/Anxiolytic Use Detection Prompt — construct-extraction style

This prompt detects sedative/hypnotic/anxiolytic-related concerns
specifically (a narrower construct than substance-related problems
broadly, and distinct from opioid, alcohol, or stimulant use). The drug
class includes benzodiazepines, Z-drugs (non-benzodiazepine hypnotics),
barbiturates, carisoprodol (Soma), GHB/GBL, methaqualone, and similar
CNS-depressant sedative agents. Grounded in DSM-5 sedative/hypnotic/
anxiolytic use scope and standard NIDA/DEA pharmacologic categorizations.
Output format matches the construct-extraction JSON schema expected by
the autonomous labeling pipeline (`sedatives_hypnotics_anxiolytics_mentioned`
boolean).

## Instructions

1. Carefully read the provided text.
2. Identify ANY mention of sedative/hypnotic/anxiolytic-related concerns —
   benzodiazepines (Xanax/alprazolam, Klonopin/clonazepam, Valium/diazepam,
   Ativan/lorazepam, Librium/chlordiazepoxide, Restoril/temazepam,
   Halcion/triazolam, Versed/midazolam, Onfi/clobazam, oxazepam), Z-drugs
   (Ambien/zolpidem, Lunesta/eszopiclone, Sonata/zaleplon), barbiturates
   (phenobarbital, Seconal/secobarbital, pentobarbital, butalbital),
   carisoprodol (Soma), GHB / gamma-hydroxybutyrate / GBL / 1,4-butanediol,
   methaqualone (Quaaludes/ludes), chloral hydrate, meprobamate — when used,
   misused, diverted, obtained illicitly, combined with other substances,
   or otherwise involved at a problem level.
3. Distinguish problem-level involvement (misuse, diversion, doctor-shopping,
   dependence, withdrawal, overdose, polysubstance combination, illicit
   acquisition, escalation beyond prescription) from prescribed
   medication used as directed with no misuse signal, fully-resolved past
   use with documented sobriety, or non-class substance use.
4. Reject lookalikes that are NOT this construct: SSRIs (sertraline,
   fluoxetine), SNRIs (venlafaxine, duloxetine), antipsychotics (risperidone,
   quetiapine, olanzapine — even when used off-label for sleep), gabapentin,
   pregabalin (Lyrica), trazodone, hydroxyzine, melatonin, diphenhydramine,
   buspirone in clearly prescribed contexts, opioids without a sedative,
   alcohol alone, cannabis, stimulants. These do NOT count.
5. Extract the exact terms used and full surrounding sentences as
   context.
6. When multiple sentences contain construct-relevant terms, separate
   each sentence with a semicolon (;).

## What counts as a sedative/hypnotic/anxiolytic mention (TRUE POSITIVES)

Inclusive: any of these terms counts as a true positive when the
involvement rises to a child-welfare or clinical concern (i.e., when
there is misuse, diversion, dependence, overdose, polysubstance
combination, or otherwise problem-level use).

- **Benzodiazepines:** alprazolam, Xanax, "bars", "footballs", "school
  buses", "zannies", "xans"; clonazepam, Klonopin, "K-pins", "pins";
  diazepam, Valium, "blues", "V"; lorazepam, Ativan; chlordiazepoxide,
  Librium; temazepam, Restoril; triazolam, Halcion; oxazepam, Serax;
  midazolam, Versed; clobazam, Onfi — when described as misused, abused,
  illicitly obtained, diverted, snorted, crushed, injected, taken outside
  of prescription, or in the context of a substance-use disorder.
- **Z-drugs / non-benzodiazepine hypnotics:** zolpidem, Ambien; eszopiclone,
  Lunesta; zaleplon, Sonata — when described as misused, abused, taken in
  excess, combined with alcohol, or otherwise used outside of prescription.
- **Barbiturates:** phenobarbital, secobarbital/Seconal, pentobarbital,
  butalbital, amobarbital, "downers", "barbs", "yellow jackets", "red devils",
  "blue heavens", "rainbows" — non-medical use; legitimate barbiturate use
  is rare in this population and warrants careful reading.
- **Other sedative-hypnotic / anxiolytic agents:** carisoprodol/Soma,
  meprobamate, chloral hydrate, methaqualone/Quaaludes/"ludes", GHB /
  gamma-hydroxybutyrate / "G" / "liquid X" / "liquid ecstasy" / "Georgia
  Home Boy", GBL, 1,4-butanediol.
- **Misuse / diversion / doctor-shopping behaviors:** obtaining
  benzodiazepines from multiple prescribers, buying Xanax on the street,
  purchasing Ambien online without a prescription, taking another person's
  prescription, crushing or snorting pills, injecting benzodiazepines,
  selling or trading prescriptions, hoarding doses, escalating use without
  medical guidance.
- **Use disorder language:** sedative use disorder, benzodiazepine use
  disorder, benzo dependence, benzo addiction, benzo abuse, sedative
  dependence, hypnotic dependence, sedative withdrawal, benzodiazepine
  withdrawal syndrome, "benzo'd out".
- **Overdose / acute events:** benzodiazepine overdose, Xanax overdose,
  Ambien overdose, GHB overdose, mixed sedative overdose, sedative-related
  respiratory depression, flumazenil reversal.
- **Polysubstance combination:** sedative/hypnotic/anxiolytic combined with
  opioids, alcohol, methadone, or other CNS depressants ("Holy Trinity" of
  opioid + benzo + carisoprodol; mixing Xanax with alcohol; "lean" with
  benzo addition).
- **Perinatal/neonatal:** maternal benzodiazepine use during pregnancy,
  neonatal sedative withdrawal, infant born exposed to benzodiazepines,
  meconium positive for benzodiazepines.
- **Legal:** arrest for possession of benzodiazepines without prescription,
  trafficking in Xanax or counterfeit benzodiazepine pills, DUI involving
  sedatives, GHB-related charges.
- **Disclosure of current problem use:** "mother takes Xanax that is not
  prescribed to her", "father has been buying Klonopin off the street",
  "caregiver admits to combining Ambien with alcohol".

## What does NOT count (FALSE POSITIVES)

These lookalikes must be rejected. The class-level vocabulary heavily
overlaps with legitimate prescription use, so a careful read of the
context qualifier is required.

- **Prescribed benzodiazepines, Z-drugs, or barbiturates used as directed**
  for documented anxiety, panic disorder, PTSD, insomnia, seizure disorder,
  alcohol withdrawal, or perioperative care, WITHOUT misuse, escalation,
  diversion, or combination signal.
- **Historical sedative/hypnotic use clearly resolved** with documented
  sustained sobriety and no current concerns.
- **Awareness, training, or education** about benzodiazepines or overdose
  response without an actual use event ("mother attended a benzo overdose
  community talk").
- **Non-class substance use:** alcohol alone, opioids alone (covered by the
  opioid construct), cocaine, methamphetamine, marijuana, hallucinogens,
  nicotine — when no sedative/hypnotic/anxiolytic agent is named.
- **Other psychotropics that are NOT sedative/hypnotic/anxiolytic:** SSRIs
  (sertraline/Zoloft, fluoxetine/Prozac, escitalopram/Lexapro), SNRIs
  (venlafaxine/Effexor, duloxetine/Cymbalta), antipsychotics
  (risperidone/Risperdal, quetiapine/Seroquel, olanzapine/Zyprexa — even
  when used off-label for sleep), mood stabilizers, stimulants
  (Adderall/Ritalin), gabapentin (Neurontin), pregabalin (Lyrica),
  trazodone, hydroxyzine (Vistaril/Atarax), melatonin, diphenhydramine
  (Benadryl). These are NEGATIVE even when described as misused.
- **Medical or professional context** where the named party is not the
  case subject (a nurse administering Versed in surgery; an EMT giving
  midazolam to a non-family member).
- **Person names / homographs** ("Soma" or "Ativan" appearing as a name;
  "Halcion" referenced as a brand in a non-drug context).
- **Hypothetical, ruled-out, or counterfactual references** ("if mother
  were taking benzos…"; "denies any Xanax use"; "tested negative for
  benzodiazepines").
- **Generic, unspecified medication language** without class identification
  and without misuse signal ("mother takes a nerve pill", "father takes
  something to sleep") — treat as UNCERTAIN, not POSITIVE.

## Output format

Return your analysis in this exact JSON format. The top-level boolean
key MUST be named `sedatives_hypnotics_anxiolytics_mentioned`. No other
format is allowed.

```json
{
  "sedatives_hypnotics_anxiolytics_mentioned": true,
  "tp_terms": ["exact term 1", "exact term 2"],
  "tp_context": "EXACT sentence(s) containing genuine sedative/hypnotic/anxiolytic-related term(s), separated by semicolons",
  "fp_terms": ["false positive term 1"],
  "fp_context": "EXACT sentence(s) containing the false positive term(s), showing why the lookalike was rejected"
}
```

## Example responses

**Text:** "Mother was found unresponsive in the bedroom with empty Xanax bottles on the nightstand. EMS suspected a benzodiazepine overdose and administered flumazenil before transporting her to the emergency department. She does not have an active alprazolam prescription on file."

```json
{
  "sedatives_hypnotics_anxiolytics_mentioned": true,
  "tp_terms": ["Xanax", "benzodiazepine overdose", "flumazenil", "alprazolam"],
  "tp_context": "Mother was found unresponsive in the bedroom with empty Xanax bottles on the nightstand.; EMS suspected a benzodiazepine overdose and administered flumazenil before transporting her to the emergency department.; She does not have an active alprazolam prescription on file.",
  "fp_terms": [],
  "fp_context": ""
}
```

**Text:** "Mother takes prescribed Ativan as directed for her documented generalized anxiety disorder. Her psychiatrist confirmed appropriate use, the prescription is current, and there are no signs of escalation, diversion, or combination with other substances."

```json
{
  "sedatives_hypnotics_anxiolytics_mentioned": false,
  "tp_terms": [],
  "tp_context": "",
  "fp_terms": ["prescribed Ativan as directed"],
  "fp_context": "Mother takes prescribed Ativan as directed for her documented generalized anxiety disorder.; Her psychiatrist confirmed appropriate use, the prescription is current, and there are no signs of escalation, diversion, or combination with other substances."
}
```

**Text:** "Father takes prescribed Seroquel at bedtime for sleep and sertraline daily for depression. He denies any benzodiazepine, Z-drug, or barbiturate use, and the most recent toxicology panel was negative for all sedative-hypnotic agents."

```json
{
  "sedatives_hypnotics_anxiolytics_mentioned": false,
  "tp_terms": [],
  "tp_context": "",
  "fp_terms": ["Seroquel", "sertraline", "denies any benzodiazepine, Z-drug, or barbiturate use", "negative for all sedative-hypnotic agents"],
  "fp_context": "Father takes prescribed Seroquel at bedtime for sleep and sertraline daily for depression.; He denies any benzodiazepine, Z-drug, or barbiturate use, and the most recent toxicology panel was negative for all sedative-hypnotic agents."
}
```

## Text to analyze

[INSERT TEXT HERE]

Co-occurring concerns

Homelessness2 document(s)
Codebook — what counts as a positive
# Codebook — Homelessness (McKinney-Vento meeting)

## Operational definition

**Homelessness** is any indication that a family or child connected to the case is currently homeless under the **McKinney-Vento Homeless Assistance Act (42 USC §11434a(2))**. The construct is binary: the record either documents an M-V-meeting housing situation for a case-relevant individual, or it does not.

McKinney-Vento defines homelessness as **lacking a fixed, regular, and adequate nighttime residence**. This includes:

1. **Sharing housing due to loss of housing, economic hardship, or similar reason** ("doubled up by hardship"). NOT voluntary cohabitation.
2. **Living in motels, hotels, trailer parks, or camping grounds** due to lack of alternative adequate accommodations. NOT vacation or chosen travel.
3. **Living in emergency or transitional shelters** (including DV shelters when residence is for housing purposes).
4. **Awaiting foster care placement** (M-V edge — applies to children whose primary nighttime residence is not yet established).
5. **Living in cars, parks, public spaces, abandoned buildings, substandard housing, bus or train stations**, or similar settings.
6. **Children with primary nighttime residence in a hospital, treatment facility, or similar institution** where no discharge housing is documented.

The scope is the **current** housing state of any case-relevant subject (caregiver, child, sibling, household member). Historical homelessness that has fully resolved (≥12 months stably housed at the time of the narrative) is NEGATIVE.

This construct is binary and broad: any single subject in a M-V-meeting situation makes the record POSITIVE. Severity grading is out of scope.

---

## What counts as POSITIVE

### Literal homelessness (M-V Category 5)
- "Sleeping in a car / vehicle / van / RV not used as a residence"
- "Living in a tent / encampment / under a bridge / in a park"
- "Sleeping outside / on the street / on a bench"
- "Camping" or "staying in the woods" where shelter is the explicit context
- "Living in an abandoned house / abandoned building / condemned property"
- "Substandard housing" — no running water, no heat in winter, structurally unsafe to occupy
- Cases referenced as "literally homeless" or "no fixed address"

### Emergency / transitional shelter (M-V Category 3)
- "Salvation Army shelter," "Coalition for the Homeless," named emergency shelters
- "Transitional housing program," "transitional living"
- "Family shelter," "homeless shelter," "warming center"
- **DV shelter when residence is for housing**: "Family resides at the DV shelter because they have no other place to go" → POSITIVE. (Not just receiving DV services while housed elsewhere.)
- Domestic violence safe house being used as primary nighttime residence

### Motel/hotel due to lack of alternatives (M-V Category 2)
- "Family staying at a motel because they can't find an apartment"
- "Moved into a hotel after eviction"
- "Living in a motel for the past 3 months"
- Voucher-funded motel stays (red flag for M-V)
- Extended-stay hotels documented as primary housing

### Doubled-up by hardship (M-V Category 1)
- "Family is staying with grandma because they got evicted"
- "Couch surfing at various friends' houses"
- "Living with [relative] temporarily until they can find their own place"
- "Bouncing between relatives" / "moving from house to house"
- "Mother and children are residing with the boyfriend's mother because they have no other options"
- "Father is staying at his cousin's because he lost his job"

### Awaiting placement / institutional homelessness (M-V Category 4 + 6)
- "Children placed in shelter pending foster care placement"
- "Family residing at the hospital because the social worker has not yet found housing"
- Children whose primary nighttime residence is a treatment facility with no documented discharge plan
- Caregivers in residential treatment whose own housing has lapsed

### Explicit homelessness language
- The narrative uses the words "homeless," "homelessness," "lacks housing," "without housing," "no place to live," "displaced from housing" — any of these in active context = POSITIVE

### Any subject, any timeframe (except resolved-past)
- Caregiver, parent, child, sibling, relative — any case-relevant person counts
- Currently homeless OR homeless within the case window (i.e., the homelessness is documented as part of the current case)
- Confirmed, suspected, self-reported, observed by worker — all count

---

## What does NOT count (NEGATIVE / FALSE POSITIVES)

### Sub-threshold housing concerns (these are INSTABILITY, not homelessness)
- "Family is behind on rent" — instability, not homelessness (unless eviction has resulted in displacement)
- "Eviction was filed but family is still in the home"
- "Family is facing foreclosure"
- "Housing is substandard" (no heat, etc.) but family is still occupying the unit
- "Frequent moves due to economic pressure" but stable at the moment

### Voluntary doubled-up
- Adult child moves in with parent for caregiving
- College student home for the summer
- Multi-generational household by cultural preference
- Vacation, travel, work-related temporary stay
- Romantic partner moving in for relationship reasons (not economic)
- Family member moving in to provide childcare while parent works

### Negated or fully resolved past
- "Mother was homeless 3 years ago but has been in stable housing since"
- "Family experienced homelessness 18 months ago, now in their own apartment for 14 months"
- "No history of homelessness," "denies being homeless," "ruled out homelessness"
- Historical homelessness with ≥12 months of documented stable housing → NEGATIVE

### Non-housing contexts
- "Mother attended a homelessness awareness presentation"
- "DARE program covered homelessness as a topic"
- "Worker mentioned the local shelter in case of future need"
- "School provides resources for homeless students" (general resource reference, no specific subject)
- A clinician mentioning M-V screening as routine protocol without a positive finding

### Hospital / treatment facility (when discharge housing exists)
- Parent in inpatient treatment with stable home to return to
- Child hospitalized for medical reasons with the family home intact
- Routine medical hospitalizations

### Non-residential alcohol/substance-related "shelter" terms
- "Shelter from the storm" (idiomatic)
- "Shelter-in-place" (emergency order context)
- "Animal shelter," "tax shelter," etc.

### Brand-name / homonym false positives
- "Mr. Homeless" as a person's name (highly unlikely but flagged for completeness)
- Place names that include "Park" or "Hotel" without an occupancy context

### Hypothetical references
- "If she loses housing again, she may need shelter services"
- "In case of relapse, they would be at risk of homelessness"
- These are NEGATIVE unless paired with a concrete current or recent positive event

---

## Edge cases — resolve by rule

Apply this rule: **if a candidate record fits one of the prompt's negative-example patterns, it is NEGATIVE**; **if it fits a positive-example pattern, it is POSITIVE**; otherwise apply the operational definition + inclusion/exclusion lists above.

| Pattern | Rule |
|---|---|
| Family meets ANY of the 6 M-V categories above with current applicability | POSITIVE |
| Resolved past with ≥12 months stable housing and no current bearing | NEGATIVE |
| Doubled-up by hardship (eviction, job loss, can't afford rent) | POSITIVE |
| Doubled-up by choice (caregiving, cultural, vacation, relationship) | NEGATIVE |
| DV shelter as primary nighttime residence (no other place to go) | POSITIVE |
| DV shelter referenced as a service in a violence-focused narrative (housing not the issue) | NEGATIVE |
| Hospital/treatment with NO documented discharge housing | POSITIVE |
| Hospital/treatment with stable home to return to | NEGATIVE |
| Motel/hotel due to lack of alternatives or post-eviction | POSITIVE |
| Motel/hotel for vacation, travel, work | NEGATIVE |
| Negated / hypothetical / awareness-only reference | NEGATIVE |
| Substandard housing but family still occupying | NEGATIVE (this is INSTABILITY) |
| Substandard housing where family has been displaced or unit is uninhabitable in current narrative | POSITIVE |
| Awaiting foster care placement with no nighttime residence established | POSITIVE |
| Idiom, metaphor, brand-name | NEGATIVE |

---

## Cross-construct boundary with INSTABILITY

The companion construct is `instability` — sub-threshold housing risk. The hard rule is:

**If homelessness = 1, instability MUST equal 0.** M-V meeting subsumes the at-risk state. The instability got *realized* — it's no longer a risk, it's a present condition.

Examples to disambiguate:

| Scenario | homelessness | instability |
|---|---|---|
| Currently in shelter due to eviction | 1 | 0 |
| Eviction filed, family still in home | 0 | 1 |
| Behind on rent, eviction warned but not filed | 0 | 1 |
| Couch-surfing due to job loss | 1 | 0 |
| Adult child living with parent for caregiving | 0 | 0 |
| Living in motel due to no alternatives | 1 | 0 |
| Foreclosure proceedings but family still in home | 0 | 1 |
| No heat in winter, family still occupying | 0 | 1 |
| No heat in winter, family displaced to a shelter | 1 | 0 |
| Resolved homelessness, 18 months in stable apartment | 0 | 0 |
| Resolved homelessness 6 months ago, now back behind on rent | 0 | 1 |

When in doubt: **does the family currently lack a fixed, regular, adequate nighttime residence?** If yes → homelessness. If no but they're at documented risk → instability. If no and no risk → neither.

---

## Subjects covered

- Caregiver(s) / parent(s)
- Child / children of the case
- Sibling(s) in the household
- Other household members named in the narrative
- Extended family who reside with the case family

A homelessness mention about a non-case-relevant person (e.g., the worker mentions a neighbor's housing situation incidentally) is NEGATIVE unless that person is part of the household.

---

## Confidence levels (all count as POSITIVE)

- Worker-observed and documented
- Self-disclosed by parent/caregiver
- Collateral-reported (school, hospital, relative, etc.)
- Suspected by worker and noted in case file
- Documentary evidence (eviction filings, shelter records)

The labeler does not need to grade confidence — any genuine documented M-V meeting counts.
Seed examples — used to retrieve candidate narratives
# Seeds — Homelessness (McKinney-Vento meeting)
# Used by 01_retrieve_candidates.py + 01b_embedding_augment.py
# Categories: pos_pure (clear positives), pos_mixed (positive with context), lookalike_only (FP risk), no_match (clear negatives)

pos_pure:
  # Explicit homelessness language
  - "homeless"
  - "homelessness"
  - "no fixed address"
  - "no permanent housing"
  - "displaced from housing"
  - "without housing"
  - "lacks housing"
  - "lacking a residence"

  # Shelter (M-V Cat. 3)
  - "homeless shelter"
  - "emergency shelter"
  - "transitional shelter"
  - "transitional housing"
  - "family shelter"
  - "warming center"
  - "Salvation Army shelter"
  - "Coalition for the Homeless"

  # Literal homelessness (M-V Cat. 5)
  - "sleeping in a car"
  - "sleeping in the car"
  - "living in a vehicle"
  - "sleeping outside"
  - "sleeping on the street"
  - "living in a tent"
  - "living in an encampment"
  - "under a bridge"
  - "living in an abandoned building"
  - "living in an abandoned house"
  - "condemned property"

  # Doubled-up by hardship (M-V Cat. 1)
  - "doubled up"
  - "couch surfing"
  - "couch-surfing"
  - "staying with friends because"
  - "staying with relatives because"
  - "bouncing between houses"
  - "moving from house to house"
  - "no place to stay"
  - "nowhere to go"

  # Motel/hotel (M-V Cat. 2)
  - "staying in a motel because"
  - "living in a motel"
  - "living in a hotel"
  - "extended-stay hotel"
  - "motel voucher"
  - "voucher hotel"

pos_mixed:
  # Need context to disambiguate
  - "shelter"  # could be homeless, DV, animal, weather
  - "doubled up"
  - "no place to live"
  - "between places"
  - "in-between housing"
  - "transitional"  # could be transitional housing or transitional job
  - "couch"  # couch surfing or just couch
  - "Salvation Army"  # services, shelter, or donation
  - "displaced"  # housing-displaced or other
  - "evicted"  # eviction is instability, BUT post-eviction homelessness is homelessness
  - "lost housing"
  - "lost their home"
  - "lost the apartment"

  # Hospital / treatment context
  - "no discharge plan"
  - "awaiting placement"
  - "hospital with no discharge housing"
  - "treatment facility no place to return"

  # Foster care
  - "awaiting foster care"
  - "in shelter pending placement"

lookalike_only:
  # Look like homelessness but usually aren't
  - "shelter from the storm"
  - "shelter in place"
  - "shelter-in-place"
  - "animal shelter"
  - "tax shelter"
  - "tornado shelter"

  # DV shelter where DV is the focus, not housing
  - "DV shelter for safety"
  - "domestic violence shelter for protection"
  - "fled to a shelter"  # could be DV protection, not housing

  # Voluntary doubled-up
  - "moved in with grandparents to help"
  - "lives with parents"  # adult child
  - "multigenerational household"
  - "extended family living together"

  # Hypothetical homelessness
  - "could become homeless"
  - "might be at risk of homelessness"
  - "if she loses housing"
  - "in case of homelessness"

  # Awareness / education
  - "homelessness awareness"
  - "homeless services pamphlet"
  - "DARE program covered homelessness"
  - "school provides resources for homeless students"

  # Resolved past
  - "was homeless 3 years ago"
  - "history of homelessness now resolved"
  - "previously homeless"

  # Idioms / metaphors
  - "shelter from criticism"
  - "shelter her from"

  # Vacation, travel
  - "staying at a hotel for vacation"
  - "traveling and staying at"
  - "out of town at a motel"

no_match:
  # Clear negative housing references
  - "rents a 2-bedroom apartment"
  - "owns the home"
  - "lives in a 3-bedroom house"
  - "has stable housing"
  - "moved to a new apartment"  # routine move
  - "purchased a home"
  - "lives in HUD-subsidized housing"  # Section 8 alone is stability
  - "long-term residence"
  - "current address since"
Housing instability2 document(s)
Codebook — what counts as a positive
# Codebook — Housing Instability (sub-threshold to McKinney-Vento)

## Operational definition

**Housing Instability** is any indication that a family or child connected to the case is **at risk of homelessness** without meeting the McKinney-Vento (M-V) definition. The construct captures the precursor / risk-of state: documented financial precarity, eviction proceedings, substandard housing conditions, frequent moves driven by economic pressure, or other case-worker-documented housing risk that has not yet resulted in an M-V-meeting situation.

This construct is **strictly sub-threshold to homelessness**. If the family currently meets any M-V category (see `codebook_homelessness.md`), this construct is NEGATIVE — the at-risk state has been realized into homelessness and is captured by the homelessness construct.

The scope is the **current** housing situation of any case-relevant subject (caregiver, child, sibling, household member). Historical instability that has fully resolved (≥12 months stably housed with no current housing concern) is NEGATIVE. Hypothetical "what if" risks without concrete current indicators are NEGATIVE.

This construct is binary and broad: any single subject in a documented at-risk housing state, without an M-V-meeting situation, makes the record POSITIVE.

---

## What counts as POSITIVE

### Financial precarity in current housing
- "Family is behind on rent" / "rent is overdue" / "in arrears on housing payments"
- "Can't afford the rent / mortgage" while still in the unit
- "Working multiple jobs to keep up with housing" (documented economic pressure)
- "Receiving emergency rental assistance" (signal of precarity)
- "Lost income / lost job and is having trouble paying rent"
- "Spending more than 50% of income on housing" (cost-burdened)
- "Mortgage delinquency / behind on mortgage"
- "Utility shutoff" or threat of utility shutoff specifically tied to inability to pay

### Eviction / foreclosure proceedings (family still in home)
- "Eviction notice received" / "eviction filed" / "served with eviction papers"
- "Pay-or-quit notice" / "30-day notice to vacate"
- "Court date for eviction" while family still occupying
- "Eviction pending"
- "Foreclosure proceedings initiated" / "received foreclosure notice"
- "Sheriff's sale date" while still in home
- "Notice of intent to foreclose"

### Substandard or unsafe housing conditions (family still occupying)
- "No heat in winter" / "no running water" / "no electricity" while occupying
- "Roof collapsing" / "severe structural damage" / "uninhabitable conditions" but family is still there
- "Code violations in the home" — significant ones that threaten habitability
- "Bedbug infestation" / "rodent infestation" / "mold" — severe enough to be a case concern
- "Overcrowded living conditions" — too many people for the dwelling size
- "Black mold" / "lead paint" hazards documented as ongoing
- "Holes in the walls" / "no functional plumbing" while occupying

### Frequent moves driven by economic pressure
- "Family has moved 4 times in the past year due to financial issues"
- "Frequent relocations" tied to inability to pay
- "Cannot maintain stable housing"
- Multiple addresses within the case window driven by hardship (NOT job relocations, divorce, etc.)

### Imminent risk language from caseworker
- "At risk of homelessness"
- "Housing situation is precarious"
- "Family is in danger of losing housing"
- "Imminent eviction"
- "On the verge of homelessness"
- "Housing instability is a concern in this case"
- "May lose housing in the near future"

### Doubled-up that does NOT meet M-V threshold
- Adult living with parent voluntarily but caseworker notes housing concerns (some friction, financial reliance)
- Doubled-up arrangement that is voluntary today but caseworker documents the underlying instability
- Family member intends to move out but cannot afford to

### Documented housing assistance dependency
- "Receives Section 8 voucher" + concern about losing it
- "Receives emergency rental assistance" — by itself signals precarity
- "On waiting list for affordable housing"
- "Recently lost housing voucher"

---

## What does NOT count (NEGATIVE / FALSE POSITIVES)

### Currently M-V-homeless (captured by homelessness construct)
- Anything that meets the M-V definition (see `codebook_homelessness.md`) → NEGATIVE for instability
- If a record has homelessness=1, instability MUST equal 0
- "Family is staying in a motel because they can't afford an apartment" → homelessness=1, instability=0
- "Currently homeless after eviction" → homelessness=1, instability=0

### Stable housing with no documented risk
- "Family resides in a 3-bedroom home" (no risk mentioned)
- "Lives in stable housing" / "no housing concerns"
- A routine housing reference without any precarity signal
- "Owns home" with no mortgage trouble mentioned

### Routine housing assistance with no precarity signal
- "Family receives Section 8 housing" — by itself, NEGATIVE (Section 8 itself is stability, not instability)
- "Lives in HUD-subsidized housing" without any precarity language
- Mention of housing benefits without case-worker concern

### Resolved past (≥12 months stable, no current concern)
- "Was behind on rent 2 years ago, has been on time since"
- "Mortgage was delinquent in 2020, is current now"
- "Family used to move a lot but has been at the current address for 18 months"

### Hypothetical or speculative risk
- "If she loses her job, she might fall behind on rent" — NEGATIVE unless concrete current indicators are also present
- "In case of relapse, housing may become unstable" — NEGATIVE
- "Could become at risk of homelessness if the boyfriend leaves" — NEGATIVE

### Non-housing financial issues
- "Family struggles financially" without housing-specific indicator → NEGATIVE for THIS construct
- "Can't afford groceries" without housing-cost framing → NEGATIVE
- "On public assistance" without housing-specific concern → NEGATIVE

### Awareness / education / training
- "Mother attended a financial literacy class that covered eviction prevention" → NEGATIVE
- "Family was given a list of housing resources for future reference" → NEGATIVE unless current crisis is also described

### Negation
- "No housing concerns" / "denies financial trouble" / "rent is paid up to date"
- "Family is current on all housing payments"
- "Housing situation is stable"

### Minor or normal housing wear-and-tear
- "House needs some repairs" — NEGATIVE unless severity rises to substandard
- "Garden needs maintenance" → NEGATIVE
- Trivial maintenance issues that don't threaten habitability

### Voluntary multi-generational households
- "Family chooses to live with grandparents to share expenses" — NEGATIVE unless additional precarity is documented
- "Extended family household by cultural preference" → NEGATIVE
- "Adult son living with mother to help with caregiving" → NEGATIVE

### Hypothetical eviction
- "Landlord said he might evict them if they have any more issues" — NEGATIVE unless an actual notice has been filed
- "Worried about possibly being evicted" without concrete documentation — NEGATIVE

---

## Edge cases — resolve by rule

Apply this rule: **if a candidate record fits one of the prompt's negative-example patterns, it is NEGATIVE**; **if it fits a positive-example pattern, it is POSITIVE**; otherwise apply the operational definition + inclusion/exclusion lists above.

| Pattern | Rule |
|---|---|
| Currently M-V-homeless (any category) | NEGATIVE (homelessness=1 takes priority) |
| Behind on rent, eviction not yet filed | POSITIVE |
| Eviction filed but family still in home | POSITIVE |
| Eviction executed, family displaced to shelter or doubled-up by hardship | NEGATIVE for instability (NOW homelessness=1) |
| Foreclosure proceedings, family still in home | POSITIVE |
| Foreclosure complete, family forced out | NEGATIVE for instability (NOW homelessness=1) |
| Substandard housing, family still occupying | POSITIVE |
| Substandard housing, family displaced | NEGATIVE for instability (NOW homelessness=1) |
| Frequent moves due to financial hardship | POSITIVE |
| Frequent moves due to job changes / divorce / lifestyle | NEGATIVE |
| Caseworker documents "at risk of homelessness" | POSITIVE |
| Hypothetical "could become at risk" | NEGATIVE |
| Section 8 / housing voucher without precarity | NEGATIVE |
| Section 8 voucher with documented threat of loss | POSITIVE |
| Doubled-up by choice (caregiving, cultural, college) | NEGATIVE |
| Doubled-up by hardship | NEGATIVE for instability (this is homelessness=1) |
| Resolved past ≥12 months stable | NEGATIVE |
| Awareness / training / hypothetical only | NEGATIVE |
| Substance use, mental illness, DV mentioned without housing impact | NEGATIVE |

---

## Cross-construct boundary with HOMELESSNESS

The companion construct is `homelessness` — meets the McKinney-Vento definition. The hard rule is:

**If homelessness = 1, instability MUST equal 0.**

Conversely:
- **If instability = 1, homelessness = 0** (sub-threshold means below the M-V bar)
- **Both can equal 0** (no housing concerns documented in this record)
- **Both should not equal 1** (mutually exclusive by definition)

The driving question: **does the family currently lack a fixed, regular, adequate nighttime residence?**
- Yes → homelessness=1, instability=0
- No, but documented housing risk exists → homelessness=0, instability=1
- No, no risk → both=0

---

## Subjects covered

Same as homelessness:
- Caregiver(s) / parent(s)
- Child / children of the case
- Sibling(s) in the household
- Other household members named in the narrative
- Extended family residing with the case family

Non-case-relevant references (a worker mentioning a neighbor's eviction incidentally) are NEGATIVE.

---

## Confidence levels (all count as POSITIVE)

- Worker-observed and documented in case notes
- Self-disclosed by parent/caregiver
- Collateral-reported (landlord, school, relative, agency)
- Documentary evidence (eviction filings, code-enforcement records, late rent notices)
- Suspected by worker and noted

The labeler does not need to grade confidence — any documented current housing risk that is sub-threshold to M-V counts.
Seed examples — used to retrieve candidate narratives
# Seeds — Housing Instability (sub-threshold to McKinney-Vento)
# Used by 01_retrieve_candidates.py + 01b_embedding_augment.py
# Categories: pos_pure (clear positives), pos_mixed (positive with context), lookalike_only (FP risk), no_match (clear negatives)

pos_pure:
  # Eviction proceedings (family still in home)
  - "eviction notice"
  - "eviction filed"
  - "served with eviction"
  - "pay or quit notice"
  - "pay-or-quit"
  - "30-day notice to vacate"
  - "court date for eviction"
  - "eviction pending"
  - "eviction proceedings"
  - "summons for eviction"

  # Foreclosure
  - "foreclosure notice"
  - "foreclosure proceedings"
  - "behind on mortgage"
  - "mortgage delinquency"
  - "in arrears on the mortgage"
  - "sheriff's sale"
  - "notice of intent to foreclose"

  # Rent burden
  - "behind on rent"
  - "behind in rent"
  - "rent is overdue"
  - "in arrears on rent"
  - "can't afford the rent"
  - "cannot afford rent"
  - "owes back rent"
  - "owed back rent"
  - "missed rent payments"

  # Substandard housing (still occupying)
  - "no heat in the home"
  - "no running water"
  - "no electricity in the home"
  - "uninhabitable conditions"
  - "severe code violations"
  - "roof collapsing"
  - "structural damage"
  - "black mold"
  - "rodent infestation"
  - "bedbug infestation"
  - "lead paint hazard"
  - "overcrowded living conditions"

  # Caseworker risk language
  - "at risk of homelessness"
  - "imminent risk of losing housing"
  - "housing situation is precarious"
  - "in danger of losing housing"
  - "imminent eviction"
  - "on the verge of homelessness"
  - "housing instability"
  - "unstable housing"
  - "may lose housing"

  # Frequent moves
  - "moved multiple times in the past year"
  - "frequent moves due to"
  - "moved 4 times this year"
  - "unable to maintain stable housing"

  # Voucher / assistance dependency with threat
  - "lost housing voucher"
  - "Section 8 was revoked"
  - "voucher at risk"
  - "received emergency rental assistance"

pos_mixed:
  # Context-dependent
  - "behind on bills"  # could be housing or not
  - "utility shutoff"  # threat-of vs already-shut-off matters
  - "received late notice"
  - "warned about eviction"  # warning vs formal filing
  - "landlord said"
  - "needs housing assistance"
  - "applied for emergency assistance"
  - "fell behind"  # behind on what?
  - "struggling to pay rent"
  - "rent assistance"
  - "back rent"
  - "rental arrears"
  - "moved frequently"  # why?
  - "code violations"  # severity matters
  - "house needs repairs"  # severity matters

  # Voluntary doubled-up with friction
  - "living with mother but"
  - "doubled up by choice but having issues"

  # Section 8 with precarity signal
  - "Section 8 housing about to expire"
  - "housing voucher being reviewed"

lookalike_only:
  # Look like instability but aren't
  - "had eviction 5 years ago"  # resolved past
  - "previously behind on rent"
  - "history of eviction now resolved"
  - "used to move a lot"

  # Hypothetical
  - "if she loses her job"
  - "could fall behind on rent"
  - "might face eviction"
  - "in case of financial hardship"

  # Awareness
  - "attended financial literacy class"
  - "eviction prevention workshop"
  - "housing resources provided"

  # Non-housing financial
  - "struggles financially"  # without housing context
  - "low income"  # alone doesn't = instability
  - "on public assistance"  # alone doesn't = instability
  - "food insecurity"
  - "can't afford groceries"

  # Minor wear-and-tear
  - "needs minor repairs"
  - "house could use some work"
  - "garden needs maintenance"

  # Voluntary multigenerational
  - "lives with grandparents"  # by choice
  - "multigenerational household by choice"
  - "extended family"  # cultural

  # Section 8 routine
  - "lives in HUD-subsidized housing"  # alone = stability
  - "receives Section 8"  # alone = stability
  - "housing voucher recipient"

  # Currently M-V-homeless
  - "currently in shelter"
  - "sleeping in car"
  - "couch surfing due to eviction"  # these are HOMELESSNESS=1

  # Idioms
  - "rocky foundation"  # metaphor
  - "shaky ground"

no_match:
  # Clear stable housing
  - "rents a stable apartment"
  - "owns the home outright"
  - "no housing concerns"
  - "rent is paid up"
  - "current on all housing payments"
  - "stable in the same residence for"
  - "well-maintained home"
  - "housing is stable"
  - "lives in their own home"
  - "lives in a 3-bedroom"  # neutral housing reference
  - "lives in a single-family home"
Firearms in the home2 document(s)
Indicator prompt or specification
# Firearms Detection Prompt — Sokol-aligned

This prompt aligns with the operational definition used by the Sokol et al. (2020) firearms benchmark (the gold labels in `firearm.jsonl`). The Sokol dictionary counts BB guns, pellet guns, airsoft guns, paintball guns, and similar non-firearm projectile devices as POSITIVE "firearm-related" mentions because the rule-based dictionary did not distinguish them from firearms. This prompt mirrors that behavior to provide a faithful autonomous replication of the published benchmark.

A parallel, stricter prompt (`firearms_published.md`) excludes those non-firearm projectile devices and is used for downstream research where the construct should match registered/regulated firearms only.

## Instructions

1. Carefully read the provided text.
2. Identify ANY mention of firearms or firearm-related items — including BB guns, pellet guns, airsoft guns, and paintball guns, which the Sokol dictionary treats as positives.
3. Distinguish actual firearm-related references from non-weapon uses (person names, metaphors, etc.).
4. Extract the exact terms used.
5. For EVERY term (true or false positive), include the complete sentence containing that term.
6. When multiple sentences contain firearm-related terms, separate each sentence with a semicolon (;).

## What counts as a firearm-related mention (TRUE POSITIVES)

Inclusive: any of these terms counts as a true positive when used in its weapon sense.

- **Generic terms:** gun, firearm, weapon (when context indicates a firearm), pistol, handgun, revolver, rifle, shotgun, sidearm
- **Specific models / manufacturers:** Glock, Smith & Wesson, AK-47, AR-15, M16, M4, Uzi, Remington (e.g. Remington 870), Beretta, Sig Sauer, Ruger, Colt (gun), Winchester (gun), Mossberg, semi-automatic, automatic, bolt-action
- **Caliber references:** 9mm, .45, .38, .22, .380, .357 Magnum
- **Components / ammunition:** bullets, ammunition, ammo, rounds, cartridges, clips, magazines (in firearm context), shells, brass, gunpowder, chamber
- **Actions:** shoot, shot, fired, discharge, brandish, draw (a weapon), holster (a weapon)
- **Storage / licensing:** gun safe, holster, gun lock, CPL, CCW, FOID, gun permit
- **Non-firearm projectile devices (INCLUDED per Sokol dictionary):**
  - BB guns, BB rifles, BB pistols
  - Pellet guns, air guns, air rifles, air pistols
  - Airsoft guns, airsoft pistols, airsoft rifles
  - Paintball guns, paintball markers
  - CO2 guns

## What does NOT count (FALSE POSITIVES)

- **Person names** (e.g., "Remington" as a surname, "Gunner"/"Hunter"/"Colt" as a first name)
- **Place names** (e.g., "Gun Lake", "Gun Lake Tribe")
- **Metaphorical uses** ("trigger" for emotions, "shot" as in photo/drink, "smoking gun" as evidence, "in the crosshairs")
- **Non-weapon contexts** ("gun it" meaning accelerate, "shotgun wedding", "shotgun seat", "ride shotgun")
- **Medical terms** ("trigger point therapy", "vaccine shot", "flu shot")
- **Starter pistols used only at sporting events**
- **Cap guns / toy guns explicitly described as toys with no projectile capability** (e.g., "the child's plastic cap gun"). Note: BB guns, pellet guns, airsoft, paintball are still POSITIVE per Sokol.
- **Stun guns, tasers** (these are weapons but not firearm-related in the Sokol dictionary)
- **Knives, blunt weapons, swords** (not firearms)
- **Hypothetical references** ("if there had been a gun in the home...")
- **Past firearms explicitly framed as no longer in the home AND no current firearm context** ("father got rid of all his guns in 2015 and there are none currently")

## Output format

Return your analysis in this exact JSON format:

```json
{
  "firearms_mentioned": true/false,
  "firearm_terms": ["exact term 1", "exact term 2"],
  "true_positive_context": "EXACT sentence(s) containing genuine firearm-related term(s), separated by semicolons",
  "false_positive_terms": ["false positive term 1", "false positive term 2"],
  "false_positive_context": "EXACT sentence(s) containing the false positive term(s), separated by semicolons"
}
```

## Example responses

**Text:** "Officer Remington responded to the call. The trigger for the incident was a noise complaint. Mr. Gunner Smith was the complainant."

```json
{
  "firearms_mentioned": false,
  "firearm_terms": [],
  "true_positive_context": "",
  "false_positive_terms": ["Remington", "trigger", "Gunner"],
  "false_positive_context": "Officer Remington responded to the call.; The trigger for the incident was a noise complaint.; Mr. Gunner Smith was the complainant."
}
```

**Text:** "The child found his father's BB rifle in the basement closet. The siblings have airsoft pistols they use in the backyard."

```json
{
  "firearms_mentioned": true,
  "firearm_terms": ["BB rifle", "airsoft pistols"],
  "true_positive_context": "The child found his father's BB rifle in the basement closet.; The siblings have airsoft pistols they use in the backyard.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

**Text:** "Father owns a Remington 870 shotgun kept in a gun safe. The teenager also has a paintball gun."

```json
{
  "firearms_mentioned": true,
  "firearm_terms": ["Remington 870 shotgun", "gun safe", "paintball gun"],
  "true_positive_context": "Father owns a Remington 870 shotgun kept in a gun safe.; The teenager also has a paintball gun.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

**Text:** "He shot photos at the wedding. The rifle was found in the closet. Hunter Winchester attended the event."

```json
{
  "firearms_mentioned": true,
  "firearm_terms": ["rifle"],
  "true_positive_context": "The rifle was found in the closet.",
  "false_positive_terms": ["shot", "Hunter Winchester"],
  "false_positive_context": "He shot photos at the wedding.; Hunter Winchester attended the event."
}
```

## Additional edge-case examples for Sokol-style inclusion

The Sokol convention is strict: any BB, pellet, air, airsoft, or paintball device in the narrative is POSITIVE, regardless of context (discipline, school, brief mention, criminal context, recreational use, or anywhere else). These examples make that explicit.

**Text:** "The mother reported using a paintball gun on her children when they misbehaved. Welts were observed on the eight-year-old's back."

```json
{
  "firearms_mentioned": true,
  "firearm_terms": ["paintball gun"],
  "true_positive_context": "The mother reported using a paintball gun on her children when they misbehaved.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

**Text:** "School staff confiscated a pellet gun from the student's locker. The parents stated they bought it for him last birthday."

```json
{
  "firearms_mentioned": true,
  "firearm_terms": ["pellet gun"],
  "true_positive_context": "School staff confiscated a pellet gun from the student's locker.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

**Text:** "Among items recovered during the robbery were a B.B. pistol, a knife, and a stolen credit card. The B.B. pistol had been altered to look like a real firearm."

```json
{
  "firearms_mentioned": true,
  "firearm_terms": ["B.B. pistol"],
  "true_positive_context": "Among items recovered during the robbery were a B.B. pistol, a knife, and a stolen credit card.; The B.B. pistol had been altered to look like a real firearm.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

**Text:** "The grandfather kept an old air rifle in the shed that the grandsons sometimes shot cans with. There was no ammunition in the home for any real firearm."

```json
{
  "firearms_mentioned": true,
  "firearm_terms": ["air rifle"],
  "true_positive_context": "The grandfather kept an old air rifle in the shed that the grandsons sometimes shot cans with.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

## Reminder before labeling

If you encounter a BB / pellet / air / airsoft / paintball device anywhere in the narrative, the answer is POSITIVE. This is true even when:
- The mention is brief or appears once in a long document
- The device is used for discipline, recreation, school activities, or any other context
- The device is not a "real" firearm in any conventional sense
- The narrative also discusses real firearms (the answer is still POSITIVE based on either signal)

The only exception is cap guns or toy guns explicitly described as having NO projectile capability (e.g., "a plastic cap-only toy gun"). When in doubt, label POSITIVE.

Analyze the following text:

[INSERT TEXT HERE]
Seed examples — used to retrieve candidate narratives
# Synthetic seeds for Firearm-construct embedding retrieval.
# Sokol-aligned: BB / airsoft / paintball / pellet count as POSITIVES.

positive_seeds:
  - "Father owns a Remington 870 shotgun and a Glock 19 handgun, both stored in a locked gun safe in the basement."
  - "The child found a loaded .22 caliber rifle leaning against the wall in the bedroom closet."
  - "Mother reported that her boyfriend keeps a 9mm pistol in the glove compartment of his vehicle."
  - "Police responded to a domestic incident and recovered a stolen handgun and ammunition from the home."
  - "Stepfather has a valid concealed pistol license and frequently carries his firearm when leaving the home."
  - "The teenage son was found with a BB rifle in the schoolyard, pointing it at other students."
  - "Father's airsoft pistol collection is stored on an open shelf within reach of the toddler."
  - "Two paintball markers and several CO2 canisters were observed in the family's living room."
  - "The five-year-old discharged a pellet gun in the backyard and grazed the neighbor's window."
  - "The home was found to contain multiple firearms, including a shotgun, a rifle, and a revolver, all unsecured."

negative_seeds:
  - "Officer Remington responded to the welfare check call and met with the mother in the kitchen."
  - "The maternal grandfather, Hunter Williams, has been the primary caregiver for the past six months."
  - "Mother stated the family had 'jumped the gun' on enrolling the child in the new school."
  - "Father took the children to the track meet, which began with the starting gun at noon."
  - "The teenage daughter received her annual flu shot at the school clinic."
  - "Father was a smoking gun in the broader fraud investigation, but no firearms were involved."
  - "The family lives near Gun Lake and frequently visits the state park there."
Domestic violence2 document(s)
Indicator prompt or specification
# Domestic Violence Detection Prompt — construct-extraction style

This prompt extracts evidence of **domestic violence (DV)** in Michigan
child-welfare disposition narratives using the construct-extraction JSON
schema expected by the autonomous labeling pipeline. The construct
definition is grounded in Victor et al. (2021) and Perron et al. work on
DV/IPV in child-welfare text: physical or psychological abuse between
current or former intimate partners (adult-to-adult), distinguished from
child physical abuse where the child is the primary target.

## Instructions

1. Carefully read the provided text.
2. Identify ANY mention of domestic violence between adult intimate
   partners (current or former), including physical or psychological
   abuse, threats, or use of weapons against the partner.
3. Distinguish DV (adult-to-adult intimate-partner) from child physical
   abuse (adult-to-child). When the violence is directed at a child
   rather than an intimate partner, it is NOT DV for this construct.
4. Extract the exact terms and full surrounding sentences for every term
   you classify as true-positive or false-positive.
5. When multiple sentences contain DV-relevant terms, separate each
   sentence with a semicolon (;).

## What counts as a domestic-violence mention (TRUE POSITIVES)

Inclusive: any of these terms counts as a true positive when the act is
between adult intimate partners (current or former spouses, dating
partners, romantic partners, fiancés, or co-parents in an active or
recently-ended romantic relationship).

- **Generic DV terms:** domestic violence, DV, domestic abuse, intimate
  partner violence, IPV, partner abuse, spousal abuse, dating violence,
  domestic dispute, domestic incident (when context indicates violence)
- **Physical abuse acts (between partners):** hit, hitting, hits, struck,
  punched, slapped, kicked, choked, strangled, shoved, pushed, grabbed,
  threw, beat, beaten, attacked, assaulted, stabbed, burned, dragged,
  bit, bitten
- **Weapon use (between partners):** threatened with a knife, pulled a
  gun on, fired at (a partner), brandished a weapon at (a partner)
- **Psychological/verbal abuse (between partners):** threatened to kill,
  threatened to harm, verbal degradation, controlling behavior, stalking,
  harassment, intimidation
- **Protective-order language tied to intimate partners:** PPO (personal
  protection order), restraining order, no-contact order, EPPO — when
  context indicates the protected party is or was an intimate partner
- **Past intimate-partner violence:** descriptions of historical or prior
  DV episodes between the same adults — both `Current` and `Historical`
  are POSITIVE for the binary `dv_mentioned` field

## What does NOT count (FALSE POSITIVES)

- **Child physical abuse (adult-to-child).** Hitting, slapping,
  spanking, beating, or any physical violence directed at a child by a
  caregiver is NOT DV. Even when severe (broken bones, head injuries),
  if the child is the target, it is child physical abuse, not DV.
- **Sibling violence** (child-to-child).
- **Violence between roommates or housemates** who are not in an
  intimate-partner relationship.
- **Violence at school, daycare, or institutional settings** between
  non-partners.
- **Mentions of DV in someone else's family** (e.g., "neighbor has a DV
  history") when not the case-family adults.
- **Mention of DV services or training** without an actual DV event
  ("father attended a DV awareness class" alone is not POSITIVE).
- **Hypothetical references** ("if there had been DV in the home...").
- **Person names** containing DV-suggestive words (e.g., "Mr. Hunter").
- **Verbal arguments without abuse or threats** ("they had a heated
  disagreement").
- **Self-harm** (the partner injuring themselves, not the other partner).

## Output format

Return your analysis in this exact JSON format. The top-level boolean
key MUST be named `dv_mentioned`. No other format is allowed.

```json
{
  "dv_mentioned": true,
  "dv_terms": ["exact term 1", "exact term 2"],
  "true_positive_context": "EXACT sentence(s) containing genuine DV-related term(s), separated by semicolons",
  "false_positive_terms": ["false positive term 1", "false positive term 2"],
  "false_positive_context": "EXACT sentence(s) containing the false positive term(s), separated by semicolons"
}
```

## Example responses

**Text:** "Mother reported that father punched her in the face during an argument last week. Mother has a PPO against father. The 6-year-old child witnessed the incident."

```json
{
  "dv_mentioned": true,
  "dv_terms": ["punched her in the face", "PPO against father"],
  "true_positive_context": "Mother reported that father punched her in the face during an argument last week.; Mother has a PPO against father.",
  "false_positive_terms": [],
  "false_positive_context": ""
}
```

**Text:** "Father struck the 8-year-old child on the back of the head with an open hand. The bruising is documented in the medical examination."

```json
{
  "dv_mentioned": false,
  "dv_terms": [],
  "true_positive_context": "",
  "false_positive_terms": ["struck the 8-year-old child on the back of the head"],
  "false_positive_context": "Father struck the 8-year-old child on the back of the head with an open hand."
}
```

**Text:** "Maternal grandmother attended a domestic violence awareness training session last month. No DV concerns identified in the case family."

```json
{
  "dv_mentioned": false,
  "dv_terms": [],
  "true_positive_context": "",
  "false_positive_terms": ["domestic violence awareness training", "DV concerns"],
  "false_positive_context": "Maternal grandmother attended a domestic violence awareness training session last month.; No DV concerns identified in the case family."
}
```

**Text:** "Police were called when the parents got into a verbal argument. No physical contact was reported."

```json
{
  "dv_mentioned": false,
  "dv_terms": [],
  "true_positive_context": "",
  "false_positive_terms": ["verbal argument"],
  "false_positive_context": "Police were called when the parents got into a verbal argument."
}
```

## Text to analyze

[INSERT TEXT HERE]
Seed examples — used to retrieve candidate narratives
# Synthetic seeds for Domestic Violence construct embedding retrieval.
# Violence/threats BETWEEN adult intimate partners. Children may witness.

positive_seeds:
  - "Father pushed mother against the wall during an argument while the children watched from the hallway."
  - "Stepfather threatened to harm the mother if she contacted her family or attempted to leave the relationship."
  - "Mother reported a long history of domestic violence by her current boyfriend, including being slapped and choked."
  - "Police responded to a 911 call after the father struck the mother in the face, leaving visible bruising."
  - "The maternal grandmother stated she witnessed the stepfather verbally degrading the mother and threatening her in front of the children."
  - "Mother obtained a personal protection order against her ex-husband following multiple incidents of physical abuse."
  - "Father was arrested for domestic assault after he kicked and punched the mother during an argument over finances."
  - "The family resides in a domestic violence shelter where mother is receiving survivor services."
  - "Stepfather grabbed mother by the hair and threw her into the kitchen table during a heated dispute."
  - "Mother reported that her partner has a pattern of coercive control, isolating her from family and monitoring her phone."

negative_seeds:
  - "Mother struck her eight-year-old son with a belt as discipline, leaving marks on his back and legs."
  - "Father slapped the toddler across the face when the child refused to eat dinner."
  - "The parents had a heated verbal disagreement about household finances but no physical contact occurred."
  - "Mother reported that she and the father argue frequently but neither has ever been physically aggressive toward the other."
  - "Father had a history of domestic violence in a prior relationship over fifteen years ago and has had no incidents since."
  - "Maternal grandmother described the parents' marriage as having relationship struggles but denied any partner violence."

How the dashboards organize the indicators

The dashboard separates the indicators into two groups for this audience:

How to read the dashboards

Maps

County color encodes the indicator's mention rate for that county across all stable years. Darker = more mentions per case. Each indicator has its own color scale — do not compare colors across two different maps. Hover any county for the exact rate and case count.

Trends

Solid lines connect stable years. Open diamonds mark the in-progress 2025 year. Diamond markers are shown for completeness but should not be read as trend.

Top counties

Counties with at least 1,000 stable-year cases are ranked by the indicator's mention rate. The maize dashed line marks the statewide rate so you can see which counties are above or below average.

What "Present" does not mean

Mention rate, not diagnosis

A "Present" label means an indicator was mentioned in the case narrative — substantiated or alleged, first-hand or second-hand, current observation or recorded history. Treat these as mention rates, not a diagnostic rate. For substance indicators in particular, a narrative that mentions alcohol does not mean the case meets clinical use-disorder criteria.

Denominators and exclusions

Updates and versioning

Each indicator carries a version number. When an indicator's definition or model is updated, every affected county-by-year total is re-computed in place, with the change recorded in the lab's change log.