Bringing hi to a repo

hi is worth reaching for when someone decides the shape of a thing, which is usually before any code exists and always before a spec does. On an existing codebase you are doing something harder: recovering the want from an implementation that has already made a hundred decisions. That is still worth doing, but expect it to feel like archaeology.

Start with one feature

Do not try to describe the whole product. Pick the feature you are about to change, write the ## Intent prose for it first, then the criteria. The prose is the part a spec can never carry, and it is the part you will be glad of in six months.

cd your-repo
hi CHECKOUT-1 "I can pay without making an account."
hi CHECKOUT-1.a "If my card is declined I am told why, and my basket survives."
# then open hi/checkout.md and write the ## Intent block by hand

Writing a criterion well

• Say what it should be, not what it does. These are directions. A criterion that is false today means the code has not arrived yet.
• Try putting As a ___, in front of it. If you cannot finish that sentence, you wrote a fact about the system rather than something somebody wants. The test is for you; do not leave the words in the file.
• Say who only when who matters. On a product with a paying side and a using side, name the subject in the sentence. On a product with one audience, do not.
• Name the person, not the permission. If your codebase says admin, the sentence probably wants an operator. admin is a permission bit; an operator is someone with a job to do.
• One want per line. If the sentence has an "and" holding two wishes together, it is two criteria.

In CI

hi check is safe to add on a Friday afternoon. It fails only on a structurally broken file, never on unfinished intent, so it cannot turn red because somebody wrote down a want that is not built yet.

- run: hi check

There is also a fledge plugin, so hi can be a step in a verify lane alongside your tests and spec-sync.

Putting hi in front of an agent

hi export is the payload. It carries the sentences, the ids, and the ## Intent prose, with retired criteria kept apart so nothing downstream builds something you dropped.

hi export CHECKOUT | your-agent "write the spec for this feature"

The useful instruction to give an agent is narrow and worth stating plainly: the criteria are the directions, not a status report. Nothing in the payload says whether anything is built, and an agent that treats an unmet criterion as a bug has misread the document. What hi claims is that a person can read what the thing should be, and an agent can read the same sentence and get the same answer, without either of them reverse-engineering intent from an implementation.

When an agent changes behavior, it should capture the intent first, in one plain sentence, and retire rather than delete. That is the same discipline hi applies to itself.

hi describes itself

hi's own intent lives in its hi/ directory, across nine families in six files, and the feature list in its INTENT.md is generated by hi index with the count per feature. This page does not restate the total, because a number maintained by hand in three places is a number that ends up saying three different things, which is exactly what happened. If you want to see what a real hi repository looks like before committing to one, that is the honest example, including the parts where it changed its mind.

It also has a blind spot worth borrowing the lesson from. hi has one audience and one voice. A product with an operator on one side and a member on the other has voices that actually contradict each other, and that is a gap hi could never have found in its own files. It took someone using it on their own product to find it. Dogfooding finds the failures your product has, and is silent about the ones your users have and you do not.

More

The repository's DECISIONS.md records what was deliberately left out and why, including the rules that were tried and reversed. Most apparent gaps in hi are decisions rather than omissions, and that file is where to check before proposing one be filled.