Inspiration

A friend moved out of a rented flat and lost an evening hunting for the receipt that would release her deposit. The document had been on her NAS the whole time, backed up for two years. What failed was retrieval. Folder search matches filenames, and a filename almost never contains the amount that decides the question.

That gap is the part I found interesting. An AI NAS is already good at storing, tagging, and organizing. But the moment someone needs one specific document as proof — a reimbursement, a tax deduction, a deposit dispute, a warranty claim — organizing stops helping. The real question is not "where are my receipts" but "which of these proves I paid 1,280 in March".

What it does

receipt-tracer takes a clue the way people actually remember one — an amount, a rough month, a counterparty, a purpose — and returns the document that proves the payment, quoting the fields it read: amount, date, counterparty, purpose. When nothing survives verification, it says so, reports how many documents it inspected, and names the single constraint most likely to be wrong.

Refusing to guess is the feature, not a fallback. A confident wrong answer in a dispute is worse than no answer.

How I built it

A UGOS Skill is an orchestration contract, not a program, so the work was mapping intent onto the capabilities the platform actually exposes, then writing boundaries around them.

Three steps, one expert each. find narrows the folder to candidates. extract reads each candidate and verifies it field by field against the clue. save-text writes an optional search record, behind an explicit confirmation. The workflow, the failure states, and the approval stop are declared in SKILL.md; no script is shipped.

Judgment was separated from retrieval. A reference file holds the field weights — amount decisive, date and counterparty strong, purpose only a tie-breaker — and five hard rules. The most important: a contradicting amount excludes a candidate instead of down-ranking it, and a filename is never evidence. A file named for the counterparty that reads a different amount is excluded by the same rule.

Then I iterated against the official static checker until the package reported zero errors and zero warnings.

Challenges

The first was resisting the obvious answer. The easy path always returns the closest document. Designing the exit path took longer than the happy path, because the wording has to leave the user certain that nothing matched without sounding like a system failure.

The second was a coverage limit I did not expect: one extraction call inspects at most sixty documents. A receipts folder is bigger than that. The Skill now slices the date window, merges the results, and reports the inspected count honestly instead of implying the whole folder was searched.

The third was a documentation trap. The starter kit suggests a README at the package root; the official checker rejects it as an unsupported resource and marks the package not uploadable. I trusted the checker, and documented the conflict, because a package that fails validation is worth nothing to a judge.

What I learned

Failure states are harder to specify than success, and more valuable. Writing five named states — completed, failed, cancelled, waiting for a user value, waiting for approval — forced every ambiguous step into a decision I had to make in advance, rather than an improvisation at runtime.

I also learned to keep the instruction file short and push rules into a reference that is read only when needed. A long instruction file reads like documentation. A short one behaves like an instruction.

What is next

The workflow has not run on a real device yet; that is what a finalist testing day is for. The open question is scanned receipts. A photographed receipt may yield partial fields, and the package reports those as related rather than proven. Tightening that boundary, and supporting more than one folder per search, is the next piece of work.

A note on tools. The documentation was drafted with an AI assistant, which also mapped each step onto the declared platform actions and ran the official checker; I set the scope and reviewed and edited the workflow, the field weights, and the matching rules. The package contains no third-party code, so there is no third-party licence to declare.

Built With

  • agent-skills
  • ai-agents
  • document-extraction
  • expense-management
  • knowledge-management
  • markdown
  • receipts
  • ugos
  • ugreen-ai-nas
Share this project:

Updates

Submission history