Human Intent
hi
Acceptance criteria in human words, with permanent ids.
Specs drift into coding intent: modules, contracts, API shapes. That is the right thing for a spec to do. But by the time something is a spec, the thing a person actually wanted has usually been quietly translated away. hi is where the untranslated version lives.
--- hi: 1 families: [SEND, SPEND] --- ## Intent I want to talk to people I trust without anyone in the middle being able to read it. ## Criteria - **SEND-1** I hit enter and it shows up right away. - **SEND-1.a** If I am offline it queues and says so. - **SEND-1.b** If the thread is gone, it warns me. - **SPEND-1** An operator can cap the daily spend.
What it is for
Criteria are directions, not a status report.
A criterion says what the thing should be. 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.
Whether the code has arrived is a different question, and it
belongs to something that reads code. hi hands that layer the
sentences through hi export and stays out of its way.
Where are we going
A person, in their own words
Where is the car now
Tools that read the code
How we get there
Whoever is driving
The format
One sentence, one line, one id that never moves.
A criterion is a markdown list item: a bold id, two spaces, a
sentence. You write the id yourself, because you are the one who has
to say it out loud. Letters are cases, numbers are steps, alternating
strictly, so reading SEND-1.a.1 tells you what kind of
thing it is.
Human first
The file is markdown a person would have typed anyway. Delete the binary tomorrow and nothing is lost.
Append first
hi never renumbers, refuses an id that is taken, and keeps a
retired id reserved. Changing your mind is normal, and
## Retired is where it goes.
Generated downstream
Tickets and specs are generated from the sentences instead of written alongside them, so there is one place to change your mind.
Seven verbs
Small enough that you keep using it.
- hi SEND-1 "..."
Capture. The family picks the file; a new family starts one.
- hi check
Structural problems only. Exits 1 on a broken file, never on unfinished intent.
- hi ls
Read back what you have agreed to.
- hi retire ID
Change your mind. The id stays reserved forever.
- hi issue ID
Print a ticket, or open a real GitHub issue.
- hi export
JSON for an agent, intent prose included.
- hi view
One self-contained HTML page for people who do not read markdown.
Every acceptance-criteria tool that died, died at authoring time: a form appeared and the person went back to Slack. So capturing is one command with no prompts, no wizard, no required fields and no init.
$ hi SEND-1 "I hit enter and it shows up right away." hi/send.md +SEND-1 $ hi check 1 criterion · 1 family · 1 file
What it refuses to do
The omissions are the design.
Every one of these is a thing you would have to maintain, and a tool
you maintain is a tool you stop writing in. hi check
fails on exactly six things, all structural, and never on unfinished
intent.
Nothing is stored about a criterion except the criterion.
Nothing is draft, approved, in progress or done.
A criterion is never wired to a test that proves it.
Requirements-smell detection runs about 59% precision. A checker wrong two times in five is one people learn to ignore.
Write one sentence down.
Install it, capture the thing you have been meaning to write down, and see what the page looks like.
$ brew install corvidlabs/tap/hi $ cargo install human-intent