openreachtech/hora-core/hora-spec-usecases

hora-spec-usecases

Stage 1 of `/hora-spec`. Nothing else in a spec can be decided until this is: a table has nothing to hold, an operation has nobody calling it, and a screen has no reason to exist.

Read ../hora/references/structure.md and ../hora-spec/references/principles.md first. `../hora-spec/references/stages.md` is the authority on this stage's exit condition, and ../hora/references/spec-format.md on the format of everything written here.

What this stage decides

who uses this product, what each of them is called, and how each is identified
what each of them comes here to complete, start to finish
which of those this release will serve at all
what the product is called
what the words mean
what already exists, whether it may be used, and how much of it this version accepts

What it must not decide

Collect more than this release will build. A use case that stage 2 defers is what stage 2 weighs, and it is where stage 3's foreseen numbers come from.

The conversation

Where stage 0 found something running, start from what it read, not from a blank page. Put the implied feature list and actor candidates up as checks, batched per area. A conversation about a list somebody is amending is far shorter than one about a list they must produce (../hora-spec/references/investigation.md).

What no surface implies is question 1, 3, 5 and 6. Why it exists, what somebody is trying to accomplish, what they do without it, and what must never happen are not in any tree.

Ask in this order. Each answer narrows the next question.

1. What is this for, in one sentence? Who is worse off if it does not exist?
 
2. Who uses it? For each one:
     what do you call them (their word, not a generic one)
     how are they identified — a login, an invitation, a device, nothing at all
     roughly how many of them
     inside the organisation, or outside it
 
3. For each of those: what do they come here to do?
     Push for whole sentences. "Attendance" is a heading; "a member of staff
     who forgot to clock in files yesterday's hours the next day" is a use case
 
4. Which of those happens every day, and which once a month?
 
5. What do they do today, without this? Is there code, and may it be used?
   And where there is code: when it and the spec disagree, which one is right —
   as-built (what runs is what this version is) or to-spec (the spec is; the
   code catches up)? And how much of what already runs does this version's tag
   claim — verified (every inherited feature specified and accepted before it)
   or inventoried (a feature may be listed unaccepted, one at a time)?
 
6. What must never happen?
 
7. What is the product called?
 
then, before 8, and only where Baseline: inventoried was declared: which
features are listed rather than specified? Per feature, four at a time, and
never an option inside 8 (below)
 
8. Only where something is already running: how far is each feature actually
   built? Under as-built the derived table goes up whole, then each feature
   is confirmed by selection; under to-spec it is never asked; without a
   declaration, it is asked per feature, open (below)

Question 3 is the stage. Everything else supports it.

Question 4 is not small talk. Frequency decides what a screen puts first at stage 5, and the once-a-month operation that touches everything is usually the heaviest one stage 3 is about to ask for.

Question 5 has four parts wherever code exists, and two on a new project. What exists; whether it may be read (which one it is may never be inferred — ../hora/references/structure.md, invariant 2); which side is authoritative when the code and the spec disagree; and how much of what already runs this version's tag claims (../hora/references/spec-format.md, "Existing assets"). One question each, two options each, and Authority is overridable per feature (<!-- authority: -->).

The last two are both asked before question 8, never after, because each decides how question 8 is asked at all. Authority decides its shape — a derived table to confirm, or an open question per feature. Baseline decides whether the listing question is asked at all, and what a built: answer then does: acted on, or merely recorded.

`verified` is required wherever code exists, and it is what adoption has always done. Writing the line down turns it from an unstated default into a choice somebody made; inventoried is that choice going the other way.

Both lines are approved in prose, on their own, and neither is ever folded into an option (../hora/references/asking.md). `Baseline` carries one rule beyond that: it goes into spec.md itself, since a declaration that leaves features unaccepted is legitimate only while every later reader sees it (../hora/references/spec-format.md, "Required sections").

Question 6 becomes one of three things: an acceptance criterion in the owning feature's block, a permission at stage 6, or — where the answer is about the product rather than one feature — a criterion handed to stage 2. Write the answer down where it is given; do not decide yet which it becomes.

Question 7's answer becomes the prefix of every repository name. Confirm the spelling — changing it renames every repository.

The listing question — asked before question 8, and never inside it

Asked only where `Baseline: inventoried` was declared. Under verified there is nothing to ask. Where the permission exists, each feature gets one of two answers — specified this version, or listed: not specified, and not accepted (../hora/references/spec-format.md, "baseline").

It is never an option inside question 8, and that is a rule about form. Under as-built, question 8's options are checks on a value derived from the tree. "This feature will not be verified" is a decision, not a reading — put beside three derived gates it becomes a proposal wearing a check's clothing, and nothing afterwards distinguishes the two (../hora/references/asking.md, "What is never asked").

Lay out the evidence, batch at most four features per exchange, and recommend nothing. Authority: as-built lifts nothing here.

"Baseline: inventoried lets a feature be listed rather than specified. For
 #payroll stage 0 found 6 resolvers, 2 migrations, 4 screens and no tests.
 
   specified   its use cases and its acceptance criteria get written this
               version, and acceptance covers it
   listed      a name and one line. No checkpoint of it is ever marked, no
               acceptance run has it in scope, and the version that next
               changes it writes both blocks then"

One yes over a table of seventeen features is not an answer, and it is forbidden by name (../hora/references/structure.md, invariant 1). Four per exchange, each one selected.

Question 8 still runs for a listed feature, and its answer lands differently.

Record every listing decision in `.hora/spec/<version>/_stages.md`, with the name of whoever made it. The annotation says a feature is unaccepted; nothing in specs/ says who chose that, or against what evidence — and paying the debt later begins by asking exactly that.

Question 8 — built:, and how the Authority answer changes its shape

`built:` records how far a feature was implemented before Hora Kit was adopted, and it is what lets an existing product be accepted rather than rebuilt (../hora/references/spec-format.md).

Skip question 8 entirely where stage 0 found nothing running.

Question 5's `Authority` answer decides which of the two shapes below this takes. A to-spec feature is skipped in both: it never carries built:, and its checkpoints all run. What it gets instead is not silence — its use cases are settled in conversation and its divergences routed, put to the person per feature with prepared options, but with more of the answer left to them.

Under as-built: present the derived table whole, then confirm feature by feature

The declaration already answered the direction; what remains is each feature's gate, and the exceptions.

"You said the implementation is authoritative. Stage 0 found code for all
 20 features. The gates I derived from the tree:
 
   #attendance    frontend   (screens call its resolvers)
   #export-api    backend    (no screen calls it)
   ...
 
 I will confirm each one with you below — answer `not finished` on any
 feature still being worked toward a spec rather than describing itself."

Then confirm feature by feature, by selection, with the derived gate as the default. Four features per exchange; every feature's options are the derived gate first, the other gates, and not finished (to-spec). The person mostly selects — composing is never asked for.

A feature answered not finished becomes <!-- authority: to-spec --> — no built:, all checkpoints open. The derivation is allowed by the declaration and by nothing else (../hora/references/asking.md, "What is never asked"), and every derived value is still confirmed before it is written.

Over-declaring is the recoverable direction (below), which is why drafted defaults are safe here.

Where no declaration exists: asked, never concluded

No amount of reading settles it. A half-built screen and a finished one look identical from a file listing. Offer the evidence and leave the choice open — do not recommend an option.

"For #attendance I found: 4 resolvers, a migration, 31 tests, and two screens
 that call them. What the tree cannot tell me is whether that is finished.
 
   spec       nobody can use it yet; only the specification exists
   backend    every part of it runs on the server, but no screen reaches it yet
   frontend   it has its screens in every app it targets
   not built  none of it counts as done"

This and the listing question are the only two things in this stage asked per feature rather than per area. Each is a different answer per feature, and getting one wrong changes which seventeen gates run — or whether any of them runs at all.

Use the question tool, four features per exchange, with not built always present as an option.

Which way an error goes