# Before You Build a File Health Checker: A Brief for Your AI Agent From "My System's Health Check Said 'Up to Date'. While Some Files Were Falling Months Behind" at emmanuelquintero.com/blog. **How to use this.** Fill in the blanks in Part 1 yourself (five minutes). Then give the whole file to your AI agent along with your request, for example "Build a check that tells me which of my notes are overdue for review." Part 2 is written for the agent. You can read it too, so you know what to expect back. It works for any tool that watches files and tells you what's current: a freshness check, a sync or backup monitor, a stale-document report, a dashboard of "last updated" dates. --- ## Part 1. For you: fill these in | Question | Your answer | |---|---| | What is being watched? (which files, folders or notes) | | | What event makes an item "up to date"? (a review, an approval, a sync, a fresh copy) | | | Where is the date of that event recorded? (a line in the file, a log, a field) | | | How old is too old? (days) | | | What should happen when something is too old? (listed in a report, a message, nothing) | | | Who reads the result, and how often? | | | What should happen if the check itself doesn't run? | | If you can't answer the second or third question, stop there. That gap is exactly what made my check give good grades to files that were months behind. --- ## Part 2. For the agent: build to these rules ### 1. Definitions come first - Before writing any code, restate in one sentence each what "up to date", "too old" and "unknown" mean, using the answers in Part 1. Show them to the person and wait for a yes. - Never treat "the file was modified" as "the file was reviewed" unless the person said those mean the same thing. A sync, copy, rename or unrelated edit changes a file without anyone reviewing it. ### 2. One source of truth for the date - Read the date from the place named in Part 1, not from the file system, unless the person chose the file system. - If a second date is available (for example, the file's last change), compare the two. When they disagree by more than a few days, flag the item as "dates disagree" instead of picking one quietly. ### 3. Unknown is never a pass Every item ends in exactly one of these states: | State | Meaning | |---|---| | Current | The recorded date is within the limit | | Overdue | The recorded date is past the limit | | Dates disagree | The recorded date and another date tell different stories | | Unknown | No date, an unreadable date, or a date in the future | "Unknown" counts as a problem in the summary, never as fine. ### 4. Samples with known answers - Create a small set of sample files whose correct result is known in advance. - One reviewed recently (expect Current) - One long overdue (expect Overdue) - One edited yesterday but not reviewed in months (expect Overdue, or Dates disagree) - One with no date at all (expect Unknown) - One with a date written in an odd format (expect Unknown or a correct read, never a silent pass) - Run the samples first on every run. If any sample gives the wrong result, mark the whole report "not trustworthy" at the top and say which sample failed. ### 5. Show the work For every item, the report shows: - The state - The date used, and where it came from - How many days old that date is - The second date, when one exists A report that only says "all good" is not acceptable. A reader should be able to check any line in seconds. ### 6. The checker proves it is alive - Every report starts with the time it ran and how many items it looked at. - If the number of items drops sharply from the last run, say so. Files that vanish from view look the same as files that are fine. - Agree with the person on what happens when a report doesn't arrive on time, and set that up too. A missing report is an alert, not a quiet day. ### 7. Ready for a second opinion - Write down, in plain words, what the checker does and does not catch. - Suggest one way someone else could try to fool it, so a second person or agent can test it. - Do not mark your own checker as verified. Say "built and passing its samples", and leave "verified" to whoever tests it next. --- ## Acceptance checklist The checker is done when every box can be ticked: - [ ] The definitions were written down and approved before the build - [ ] The date comes from the agreed source of truth - [ ] Items with two dates that disagree are flagged - [ ] Missing or unreadable dates show as Unknown, and Unknown counts as a problem - [ ] All samples give their expected results, and a failed sample marks the report untrustworthy - [ ] Every line shows its state, its date, the date's source and its age - [ ] Every report shows when it ran and how many items it checked - [ ] A missing report triggers the agreed alert - [ ] Someone other than the builder has tried to fool it If any box is empty, treat the checker's "all good" as "unknown" until it's fixed.