Documentation
hi
Acceptance criteria in human words, with permanent ids. A format first, and a small CLI that keeps the format honest.
hi (Human Intent) holds the sentences a person said they wanted, each with an address that never moves. Tickets and specs are generated from those sentences instead of written alongside them, so there is one place to change your mind.
It is a format first. A hi/*.md file is markdown a person would have typed anyway:
frontmatter, an ## Intent block of prose, and a list of criteria. Delete the binary
tomorrow and nothing is lost, because there is nothing of hi's stored anywhere else.
Where it sits
Specs drift into coding intent: modules, contracts, API shapes. That is the right thing for a spec to do, and it is what spec-sync already checks. But by the time something is a spec, the thing a person actually wanted has usually been quietly translated away. hi sits upstream of that, next to whoever decided the shape.
| Layer | Question it answers | Owned by |
|---|---|---|
| hi | Where are we going | A person, in their own words |
| Specs and code checks | Where is the car now | Tools that read the code |
| The code | How we get there | Whoever is driving |
Criteria are directions
A criterion says what the thing should be, not what it currently does. Directions stay correct through a wrong turn: a criterion that is false today means the code has not arrived yet, not that the criterion is wrong. A line can describe something true today, something a year out, or something that was true and has since been revised. In every case it says where you are going, which is the only claim hi ever makes.
That is why nothing on a hi page or in a hi file says whether anything is built. Answering
is this met is a question about where the car currently is, and it belongs to something
that reads code. hi feeds that layer through hi export and stays out of its way.
What it refuses to do
- No state. Nothing is stored about a criterion except the criterion.
- No lifecycle. Nothing is draft, approved, in progress or done.
- No evidence binding. A criterion is never wired to a test that claims to prove it.
- It never fails a build because a criterion is unproven. Incomplete intent is the normal state of intent.
- No prose linter. Requirements-smell detection, the published state of the art at flagging a vague sentence, measures about 59% precision. A checker wrong two times in five is one people learn to ignore, and a checker you ignore is worse than none because it still looks like coverage.
Those are not omissions, they are the design. Every one of them is a thing you would have to maintain, and a tool you maintain is a tool you stop writing in.
Next
- Quickstart: install it and capture a sentence.
- The HI/1 format: what a file looks like and why.
- Ids: the grammar, and why they are permanent.
- CLI reference: all seven verbs.
- Bringing hi to a repo: including one an agent works in.