---
name: reconcile-setup
description: Idempotent run-once setup should be reconciled, not trusted - verify it continuously with an event-triggered, fail-loud QA drift-check.
---

# Reconcile Setup

## Use This Skill When

Authoring setup steps, tooling, generated or config files, or QA config — anytime you create a
"run once" operation. If something is worth doing once, decide how it gets re-verified.

## Principle

Worth doing once is worth repeating. Anything set up once drifts: a teammate edits the file, a fresh
checkout never ran it, a tool's output changes. So do not trust setup — reconcile it: re-verify the
desired state continuously, as a reminder and catch-all. This is the convergence pattern behind
Terraform, Ansible, and Kubernetes controllers, which run on a loop precisely to catch drift.

## Gate on idempotency

Reconcile only **idempotent** operations — where running twice produces the same result as running
once (checks, generators, validators). Never auto-repeat operations with accumulating side effects:
migrations, seed scripts, publishes, anything that appends or mutates. The discriminator is one
question: does run-twice equal run-once? Yes → safe to reconcile. No → never repeat by habit.

## Form: a drift-check in QA

Make reconciliation an **event-triggered** check, not a timer — run it when the thing it guards could
change (CI, or a hook on the relevant paths). It must be **silent on success and loud on drift**; a
check that constantly says "still fine" trains everyone to ignore it, and the reminder becomes noise.
Fail the build on drift; say nothing when clean.

Put the check where the artifact lives:

- **Producer side**, where the thing is authored — validate the source.
- **Consumer side**, where it is consumed — verify the installed or generated state still matches.

## Example

Intent skills: `intent validate` in the library repo (producer — validates the `SKILL.md` files),
and a `skills:check` QA step in each consumer that re-runs the generator and fails if the committed
block drifted from its output (consumer). Silent when current, loud when clobbered.

## Avoid

A timer when an event trigger exists; reconciling non-idempotent operations; checks that mutate as an
undeclared side effect; and success-noise that becomes background hum.