# Add a rule [#add-a-rule]

Use this guide when you need a source-backed calculation rule, threshold,
coefficient formula, parameter table or derived fact.

## Before you start [#before-you-start]

* Read [Rules and parameters](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/rules-and-parameters.md).
* Read [Testing and quality](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/testing-and-quality.md).
* Find the rule package that owns the tax area:
  `@taxkit/rules-au-pay`, `@taxkit/rules-au-income-tax` or
  `@taxkit/rules-au-stsl`.

The rule package owns the rule layer, parameter service, descriptor, source
references, graph metadata, rule-pack composition and golden tests.

## Proposal [#proposal]

Before implementation, write down:

* the official source and section, table, schedule or page range
* the effective period and tax year
* the input facts and parameter services the rule requires
* the facts, traces or ledger components the rule provides
* the rounding mode and edge cases
* whether the change needs API compatibility tests or SDK compatibility tests

## Implementation [#implementation]

Rules are Effect `Layer`s. Parameter tables are services, not imported
globals. The existing Schedule 1 parameter file uses this definition:

```ts
export const AtoSchedule1_2025_26_Live =
  Layer.succeed(AtoSchedule1Table)(table2025_26);
```

This is an excerpt from
[the owning parameter source](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/rules/au/pay/src/parameters/schedule1.ts).
That file imports `Layer`, defines `AtoSchedule1Table` and checks `table2025_26`
with its owning schema. The excerpt needs those definitions; it is not a
complete application example.

Keep algorithm code separate from yearly data. Most tax-year updates should
add schema-validated parameter data and golden tests without rewriting the
rule algorithm.

## Tests [#tests]

Your evidence should include:

* source reference validation for each official source
* effective-date overlap checks for parameter descriptors
* graph cycle and duplicate-provider checks
* golden tests from official examples or known scenarios
* date-boundary tests when thresholds change across periods
* trace snapshot tests when rule IDs, source references or ledgers change
* package export or type tests when public exports change

## Pull request evidence [#pull-request-evidence]

Use [Source citation standards](/contributing/source-citation-standards) and
[PR evidence checklist](/contributing/pr-evidence-checklist). Explain whether the
rule changes public API or SDK behaviour, even when endpoint shapes do not
change.