Repository navigation
Add or Change a Rule
This page walks you through changing a rule value in a state adapter, such as an income limit, with a cited source and a test case. It is for contributors who are comfortable editing JSON and running a few commands. If you would rather not touch code, use Report a rule problem instead, and a maintainer will make the change.
Never invent a number. Every value must come from an official source you actually read. If you cannot find one, leave the value as it is and say so in an issue.
- The code set up on your computer. See Developer setup.
- The official source for the value: a web page or document from the agency, with its publication or effective date.
- A short read of
.kiro/steering/eligibility-rules.md.
-
Find the official source. Prefer primary sources: HHS for the poverty line, USDA FNS for SNAP, and the state agency or Medicaid.gov for Medicaid. Note the URL and the date it was published.
-
Open an issue first if there is not one already. Use the "Eligibility rule correction" template. Changing a rule value needs a maintainer's explicit yes before it merges (
AGENTS.mdsection 5). -
Make a branch, for example
data/oh-wic-limit. -
Edit the value in
data/states/<code>/adapter.json(for exampledata/states/oh/adapter.json). Keep the units: money in whole cents (...Cents), and percentages of the poverty line as whole numbers (...Pct, so185means 185%). See State adapters for what each field means. -
Add or update the
sources[]entry for that field:field(the path, likewic.incomeLimitPct),sourceName,url,publishedDate(YYYY-MM-DD), and an optionalnote.If an expert sent a proposal file from the community rule toolkit, steps 4 and 5 are one command. It checks the proposal against today's values, sets each value, records the citation, and keeps the state
draft:npm run rules:apply -- path/to/proposal.json --dry-run # preview npm run rules:apply -- path/to/proposal.json # apply
-
Leave
verificationStatusasdraft. Only a human expert setsverified, after a sign-off indocs/SME_SIGNOFF.md. -
Add or update a golden test case in
data/states/<code>/fixtures/that shows the change: for a limit change, a household just under and just over the new limit. See Golden test cases. -
Run the checks from the repository root:
npm run validate:adapters npm run test:fixtures
If an existing test case now fails, do not change its expected result just to make it pass. Work out whether the rule or the test case is wrong, explain it in your pull request, and get a maintainer to agree.
-
Run the full gate before you open the pull request:
npm run verify
-
Add a line to
CHANGELOG.mdunder## [Unreleased], in aDatagroup. -
Commit with a
datatype, for exampledata(oh): update WIC income limit. If an AI agent wrote or drafted it, add anAssisted-by: <agent or model>trailer. -
Open a pull request using the template. Tick "Eligibility rule or reference data", paste the source link, and paste the commands you ran with their results.
From AGENTS.md section 5, propose these and wait for a yes:
- changing any rule value or threshold, or the outcome ladder in
decideOutcome(); - deleting data, test cases, or tests;
- adding a runtime dependency.
Every pull request is reviewed by a human maintainer before it merges.
If the rule needs new logic (a new deduction, a new kind of test), that is an engine change in
packages/eligibility-engine/src/programs,
not a data change. Write the failing test first, keep the engine pure, decide through
decideOutcome(), and give any new reason code an English string. Read
How the rules engine works before you start.
OpenBridge is a prototype. Its rules are drafts that experts have not verified yet, and results are
estimates, not decisions. It is not legal advice. Need help applying for benefits? Call 211 or visit
211.org. This wiki is edited in the wiki/ folder of the repository.
Questions: openbridge@starlingtek.com.
Start here
Use OpenBridge
- Using OpenBridge
- Understanding your results
- Guide for navigators
- Privacy and your data
- Run it on your computer
- Host it for others
- Use it with an AI assistant
Help without code
- Ways to help
- Review rules as an expert
- Record a test case
- Report a rule problem
- Translate OpenBridge
- Test accessibility
- Community rule toolkit
Rules and policy (with code)
- How the rules engine works
- State adapters
- Add or change a rule
- Add a new state
- Golden test cases
- Yearly data updates
Developers