reconify-engine-reconcile

Files (1)

• SKILL.md

SKILL.md (first lines)

# Reconify Engine Reconcile

Produce a correct, reproducible reconciliation, not a high match rate. Complete the checkpoints in
order from the directory that will contain `reconify.yaml`.

## Routing

| Situation | Skill |
|---|---|
| Unfamiliar files, or one task spanning discovery through explanation | stay here |
| No `reconify.yaml` yet, and the outcome is a first validated config plus a first result | `reconify-engine-bootstrap` |
| A `reconify.yaml` exists and needs creation detail, correction, or validation | `reconify-engine-config` |
| A run succeeded but the counters contradict the business scenario | `reconify-engine-debug` |
| Memory, wall time, or artifact size is the binding constraint | `reconify-engine-performance` |
| The workflow must run unattended with an exit-code policy | `reconify-engine-ci` |

This skill owns the end-to-end sequence. Delegate only for config detail at checkpoint 3, a large
input at checkpoint 4, and diagnosis at checkpoint 5 or 6, then return here. Do not hand the whole
task to another skill.

## Artifact convention

| File | Meaning |
|---|---|
| `reconify.yaml` | the validated config; commit it |
| `result.json` | the retained reconciliation artifact; regenerate it, and commit only as a reviewed baseline |
| `explanation.json` | the explanation of that result; regenerate it alongside |

Any other file you create is scratch. Say so in the final report rather than leaving it unexplained.

## 1. Discover the build and inputs

Locate every input before inspecting it, then query the installed binary:

```bash
reconify capabilities
reconify inspect INPUT_LEFT
reconify inspect INPUT_RIGHT
```

Inspect every counterpart in a multi-source run. This checkpoint is complete when the actual input
paths are known and `capabilities` confirms the commands, formats, schemas, and passes needed by the
task.

## 1a. Repair an existing workspace

If discovery finds a `reconify.yaml` already present, repair it rather than replacing it.

Preserve the original first — copy it to `reconify.yaml.bak` and leave that copy uncommitted. Never
overwrite the file before diagnosing it.

Then diagnose in this order, because each command sees a different class of failure:

```bash
reconify config validate --config reconify.yaml
reconify config check-source --config reconify.yaml --source SOURCE --file INPUT
reconify reconcile --config reconify.yaml --pair PAIR --format json \
  --result-mode all --deterministic --out result.json
```

| Command | What its failure means |
|---|---|
| `config validate` | The config shape is wrong: a missing required field, an unknown key, an invalid enum |
| `config check-source` | The parser mapping no longer fits the file you named: a renamed header, an unparseable date layout, a wrong column |
| `reconcile` | Everything above is consistent, but a `file_pattern` resolves to no file, or the pair is misnamed |

`check-source` takes an explicit `--file` and therefore cannot detect a stale `file_pattern`; only
`reconcile` resolves the pattern. Compare each configured `file_pattern` against the paths found in
checkpoint 1 before assuming the mappings are at fault.

Make the smallest change that clears the reported diagnostic, rerun from `validate`, and repeat. Do
not rewrite mappings that already pass `check-source` against the real inputs.

Treat any pre-existing `result.json` as stale evidence, not an answer key; regenerate it at
checkpoint 4. Once validation and every source check pass but the counters still contradict the
business scenario, read `../reconify-engine-debug/SKILL.md`.

## 2. Record the evidence and policy

From each profile, record the candidate date, amount, reference, name, currency, and grouping
columns; copy exact date layouts and note ambiguous inferences. Settle these business decisions with
the user or state an explicit assumption:

- the shared transaction identifier;
- the amount difference that is acceptable, expressed in minor units;
- the permitted date offset;
- whether repeated references represent duplicates, one-to-many groups, or many-to-many groups;
- whether gross, net, fees, taxes, or other effects must satisfy a financial expectation; record the
  expected sign operation and tolerance in minor units.

Classify every such decision before acting on it:

| Tier | Definition | Action |
|---|---|---|
| Proven | The value is visible in `inspect` output or a source file | Use it and cite the evidence |
| Safe default | Ambiguous, but every plausible reading produces the same matching outcome | Choose it and record it as an assumption |
| User decision | Plausible readings produce different matching outcomes | Ask the user before proceeding |

A repeated reference is the canonical user decision: read as a duplicate it raises
`duplicate_count`, read as a one-to-many settlement group it raises `grouped_matched_count`, and
the two answers are not interchangeable. A tolerance wide enough to absorb a real fee is the same
kind of decision.

This checkpoint is complete when every mapping and tolerance is proven, defaulted with a recorded
assumption, or decided by the user.

## 3. Build and prove the config

Read `../reconify-engine-config/SKILL.md` and follow its workflow. Keep each `file_pattern` relative
to the config file, then run:

```bash
reconify config validate --config reconify.yaml
reconify config check-source --config reconify.yaml --source SOURCE --file INPUT
```

Run `check-source` for every configured source. This checkpoint is complete only when validation and
all source checks pass against the real inputs.

From reconifyhq/reconify, MIT.

More from reconifyhq/reconify