sentinela — Case Study
backThe question
irs-pt answers a tax question using numbers that Parliament changes every December. A tool built on a law has a quiet failure mode that a tool built on an API does not: nothing breaks. No test goes red, no request 500s. The skill keeps answering, confidently, with last year's thresholds. So who tells you the ground moved?
What I built
A watchman that runs on a schedule, reads the official pages the skill is built on — CIRS, CIVA, Social Security, e-Fatura — and opens a GitHub issue with the diff when the text changes. It never edits the skill. Deciding what a changed article means is the human's job; the watchman's only job is to make sure nobody finds out by accident.
- Runs on the 1st of each month, plus 15 January and 10 July — the dates the law actually moves
- Opens one issue per run, carrying the diff of every source that changed
- Watches PDFs (the practical guides) by hash of their bytes
- A source that stops responding also opens an issue — a dead URL means the portal was rebuilt
- First run writes the baseline and stays quiet
Technical decisions
Alert first, baseline second — the run compares, then publishes the issue, and only then commits the new snapshots. If publishing fails, the baseline is not updated and the next run catches the same change again. A change is never absorbed in silence, which is the one outcome that would make the whole thing worse than nothing.
Every source carries a marker — a string that has to be present for the page to count as read. A page that answers 200 with a cookie banner and a menu is a failure, not an all-clear. Pages on the tax portal are cropped from "Artigo N" onwards, so a SharePoint redesign doesn't register as the law changing.
Scheduled, not real-time — the law moves on predictable dates: the budget in December and January, the IAS in December, rarely mid-year. Reading the source on a timer and having a person confirm it beats scraping on every request, which breaks without telling you.
Adding a source is one line — sources live in a JSON file, so watching something new is a data change, not a code change.
Where it went
A watchman that files issues is useful to one developer. The same engine, pointed at the people the law actually lands on, is a product — so it became one. Sentinela Fiscal watches the same official pages and sends a short email instead: what changed, whether it affects your tax regime, and what it is worth in euros for your case. The November 2026 one reads “IRS brackets up 3.88%” and, for fifteen thousand euros of taxable income, “about ninety-five euros a year less”.
Taking money changes what you have to build. There is a sole trader behind it with a tax number on the page, card payments through Stripe, invoices issued through the tax portal, fourteen days to cancel with no reason given, and a full refund if the service does not launch by 15 January 2027. The privacy notice names the controller, the legal basis and the fact that card details never reach me. None of that is code, and all of it had to exist before the first euro.
One decision shaped the rest: a person reads every alert before it is sent. The repetitive part — fetching, diffing, drafting — is software. The part where someone could act on a wrong number is not. That is slower and it does not scale, and it is the only version I was willing to charge for.
What I learned
Most monitoring tells you a system is down. The interesting kind tells you a system is now wrong — still up, still fast, still answering, just no longer true. Building the second kind meant deciding, in advance, what evidence counts as "I really did read the page", and then being strict enough to call a 200 a failure. The ordering of three steps turned out to matter more than the diffing itself.
The second lesson came later: the gap between a tool and a product is almost never the code. It was the refund policy, the invoice, the sentence explaining who is liable if the number is wrong. Writing those took longer than the watchman did.