Dowsing: Lost Item Finder

What it is

Dowsing is a SKILL.md agent skill that turns a traditional Chinese divination method — Meihua Yishu (梅花易数, Plum Blossom Yi-ology) "lost item" reading — into a deterministic, scriptable search heuristic. Give it an item name and the context where you last had it (home, a public place, a vehicle/plane/train, or a missing pet), and it runs a Python engine (scripts/shiwu_calc.py) that casts a hexagram from the current time, a date, or numbers you think of, then outputs a structured JSON SearchReport.

The problem it solves

When something goes missing, people search the same two or three "obvious" spots over and over. This skill breaks that loop by handing the agent a ranked, direction-first checklist of places to check next — derived from the hexagram's Bagua (八卦) directions, not from guessing.

How it works

• Deterministic casting from time, date, or numbers — no randomness, no hand-calculation by the LLM.
• Context-aware scene mapping: the same hexagram maps to different real-world places depending on whether the item was lost at home, in public, in transit, or is a lost pet (a washing machine at home vs. a river/drain in public, for the same "water" trigram).
• Ti-Yong (体用) Five Elements analysis judges how easy the item is to recover.
• Mutual (互卦) and transformed (变卦) hexagrams infer a second search zone and whether the item has likely moved, including compound directions (e.g. South + West = Southwest) when both halves agree.
• Always ends with a concrete next-step recommendation — never a vague "it depends."
• Language follows the user. A Chinese request gets the Chinese report only. An English (or other-language) request gets that same Chinese report first, then a translation of the same casting. The translation does not recast the hexagram or change the direction or the findability verdict.

What's included

• SKILL.md — full agent instructions and output template
• scripts/shiwu_calc.py — the deterministic casting engine (Python standard library + lunardate, no network calls)
• references/ — Bagua direction/scene tables, Ti-Yong interpretation rules, and verified case studies (including the bracelet-in-the-washing-machine case used in the demo below)
• tests/test_shiwu.py — regression tests for the engine
• README.md — usage guide

Requirements

Python 3, plus pip install -r requirements.txt (single dependency: lunardate). No network access, no API keys.

Honest framing

This is a structured search heuristic, not fortune-telling. It never predicts death or catastrophic loss, never gives a timing prediction for when you'll find the item, and always recommends also contacting the police for valuable lost items. Report language uses "likely" / "suggest checking first," never "certainly."