backup-check

---
name: backup-check
description: Compares your machine against your backup and reports which files exist in only one place, when the backup last actually changed, and what a restore today would miss.
---

# Prove your files are actually backed up, not just supposed to be

You give it the folder that matters and the place it is supposed to be backed up to. You get back the files at risk, the real date the backup last changed, and the answer to one question: if the machine died now, what would you not get back.

## What it does

1. **Write down both sides before touching anything:** the live folder path, and the backup location exactly as the tool sees it (an external drive letter, a mounted network path, or a cloud remote name). If the drive is not mounted or the remote does not answer, stop and say so. An unreachable backup is the finding, not a reason to skip the check.
2. **Produce a full file list for each side, with sizes and dates:** every file, its full path, its byte size and its last-modified time, written to two lists. Print the count of each list. A backup folder that exists and a backup folder that exists and is empty look identical in a file browser, and only the count separates them.
3. **Find the newest modified date inside the backup and compare it to today:** this single number catches the failure that everything else misses. If the most recent file in the backup is older than the most recent file on the live machine by more than a day, the backup stopped running on that date, and it has been failing silently ever since.
4. **Compare content, never names:** compute a checksum for each file on both sides. For a cloud or remote destination use `rclone check --checksum`, which compares sizes and hashes (MD5 or SHA1), and add `--download` when the remote cannot supply a hash of its own. Two files with the same name and the same size can still differ.
5. **Split the differences into three named lists:** files present only on the live machine (these are what you would lose), files present only in the backup (deleted from the machine, which may be a mistake or may be the point), and files present in both but different (print both hashes). rclone writes these three directly with `--missing-on-dst`, `--missing-on-src` and `--differ`.
6. **Make the backup tool read its own data, not just its index:** if the backup is a repository rather than a plain copy, run the tool's data check. `restic check` on its own only verifies structural consistency of snapshots, trees and pack files, so use `restic check --read-data-subset=5%` to actually read pack files back. `borg check` verifies by size and CRC by default, so use `borg check --verify-data` for a full cryptographic read. An index can be perfect while the data underneath it is rotten.
7. **Restore one real file and check it came back whole:** pick the largest file changed in the last month, restore it into a new empty folder, and compare its checksum to the live copy. Until a file has come out of the backup and matched, nothing has been proven.
8. **Score the setup against the 3-2-1 rule, using the file lists:** keep 3 copies of any important file, 1 primary and 2 backups; keep the files on 2 different media types; store 1 copy offsite, outside the home or business premises (US-CERT, Data Backup Options, 2012). Say which of the three the setup fails and name the copies you can actually see, not the ones the plan describes.
9. **Report in this order and stop:** the date the backup last genuinely changed, the number and total size of files at risk, the files that differ, what a restore today would miss, and the one next action.

## Then it checks

1. Both file lists have their counts printed, and a zero count on the backup side is reported as a failure rather than as a clean match.
2. Every claim that two files are the same is backed by a checksum comparison, never by a matching name, size or date alone.
3. The newest modified date inside the backup is printed as a real date and compared against today's date in days.
4. At least one file has been restored into a separate empty folder and its checksum matched the live copy.
5. Nothing outside the scratch restore folder was written, moved, renamed or deleted during the check.
6. Any folder or remote that could not be read, because of permissions, an unmounted drive or a sleeping connection, is listed by name as unknown, and is never counted as matching.

Any check fails: name it, redo that step once. Failed twice: say what is wrong and stop.

## Rules
- Public information only.
- Never invent a fact, a number or a quote.
- Read only. This skill never deletes, moves, re-syncs or repairs anything. The only thing it writes is the restored test file, into a new empty folder.
- The existence of a folder, a scheduled task, or a green tick in a backup app is not evidence. A backup that silently stopped looks exactly like one that is working, so only file content and modified dates count as proof.
- Report paths, sizes, dates and checksums. Never print file contents, passwords, keys or customer personal data into the report.
- If the folders hold customer or employee personal records, the report prepares the facts for the person responsible for data protection to check. It is not legal or compliance advice and must never be presented as such.

Run it in one pass over your own files:

```
codex exec -C "the folder" - < the-prompt.md
```

## Built from
- US-CERT and Carnegie Mellon University, Data Backup Options, Paul Ruggiero and Matthew A. Heckathorn, 2012, https://www.cisa.gov/sites/default/files/publications/data_backup_options.pdf: the exact wording of the 3-2-1 rule quoted in step 8, and its reason for existing, that "Saving just one backup file may not be enough to safeguard your information".
- restic documentation, Working with repositories, https://restic.readthedocs.io/en/stable/045_working_with_repos.html, read 7 September 2026, repository restic/restic 35914 stars: the distinction in step 6 between the default structural check and `--read-data` or `--read-data-subset`, which actually reads the pack files back.
- rclone check, https://rclone.org/commands/rclone_check/, read 7 September 2026, repository rclone/rclone 59634 stars: the size-and-hash comparison in step 4, the `--download` fallback for remotes with no hash, and the three separate output flags that became step 5.
- borg check, https://borgbackup.readthedocs.io/en/stable/usage/check.html, read 7 September 2026, repository borgbackup/borg 13696 stars: the point that the default check verifies size and CRC only, and that `--verify-data` performs the full cryptographic read, which is the second half of step 6.
- addyosmani/agent-skills, https://github.com/addyosmani/agent-skills, 92765 stars: the evidence rule this whole skill is built on, that a skill ends with proof rather than confidence, which became checks 1 to 4 and the read-only rule.