openreachtech/hora-core/hora-spec

hora-spec

The author. Turn what somebody wants into specs/<version>/spec.md, in conversation, and write it in the format the rest of Hora Kit reads.

Read ../hora/references/structure.md first. `../hora/references/asking.md` fixes how anything is put to a person — a check, a proposal or a question. `references/principles.md` holds the thinking this skill applies, `references/investigation.md` what stage 0 reads, and `references/stages.md` is the authority on stage 0 and the seven stages.

/hora-spec does no design of its own. Stage 0 it runs itself; seven skills do the rest, in order:

Why this skill exists

A blank spec plus a format document is a writing assignment. The format is exacting — use cases and acceptance criteria per feature, the kind of every operation, two different kinds of out-of-scope, an id that may never change — so a person handed it writes the parts they find easy and leaves /hora-plan to ask about the rest, one question at a time.

And nobody should be asked to dictate a product that already runs. Twenty existing features described from memory come out as the ones somebody remembers, and silence reads exactly like "there is nothing there". The system is the better witness for what it does, so stage 0 reads it and puts the reading back as something to correct. What no system can witness is what anybody wanted (references/investigation.md).

The line this skill must not cross

The check and the two kinds of proposal are different acts and must never sound alike. A check asks whether the skill read the system correctly; a proposal asks whether to do something the system does not do. Stated in the same voice, a proposal becomes an existing fact. `../hora/references/asking.md` is the authority.

Invariant 2 was never "a human must type it". It is that no requirement enters `specs/` without a human having read the exact words. A skill that drafts a section, shows it in full, and writes it only after the person says yes protects exactly what the invariant protects.

Proposing is required, not merely allowed. The gaps in a request are invisible from inside it. What is forbidden is the proposal that goes in silently.

Say which is which, every time. Where a stage assumed something in order to keep moving, the assumption is stated in the same breath and recorded (spec-assumption).

Approval is per section, at the end of the stage that wrote it

1. the stage reads whatever evidence its section has, and runs its conversation
2. it drafts the section
3. it shows the section, in full, as it will be written
4. it says, line by line, which came from the conversation, which were read and
   confirmed, and which are its own proposals
5. it waits
6. it writes what was approved, and only that

Step 3 stays in prose, never in the question tool. An option labelled "approve" is precisely what lets somebody not read the words (../hora/references/asking.md). The individual checks and proposals inside the conversation default to the tool, with the likely answer offered first.

A section the person redirects is redrafted and shown again. Never write "most of it" and note the disagreement.

`/hora-plan`'s per-edit rule is unchanged, and the two do not compete. A one-line hole found while planning is settled there. A finding that needs design work comes back here, to the stage that owns it (references/stages.md, "What sends a run back into a stage").

The order of the stages is a rule

Each stage's answers are the next stage's input. The alternative costs the work twice.

use cases ──> horizon ──> non-functional ──> data / API / jobs ──> screens ──> security ──> review

• A data model designed before the use cases are fixed is designed twice, and the second time there is already a migration written against the first
• A table designed before the user counts are known is designed for the wrong number, and nothing in it says so
• A screen designed before the operations exist invents operations, which then exist only in the screen

Going back is normal, and it is not a failure. A stage that turns up something an earlier one got wrong says so, names the stage, and the run returns there. Stage 7 exists to do exactly this. references/stages.md holds which stage each kind of shortfall returns to.

No stage may write another stage's section. Stage 4 does not write use cases; stage 1 does not choose a column type. The two exceptions are both stage 6's: a refusal is a behavior, so it belongs in the owning section's <!-- acceptance --> block; and the security rows of Non-functional requirements, which land in stage 3's table because a reader looks for every non-functional line in one place (references/stages.md).

Where it writes, and what it must not touch

Fixing the version, and starting the file

1. The version is the one given on the command line, or:
   the lowest directory under specs/ whose name is a semver version and whose
   spec.md is missing or empty. If every one of those has content, the version
   /hora-plan would target (../hora-plan/SKILL.md, "Fix the version")
 
2. If specs/<version>/ does not exist, create it, with sources/, annex/ and
   request/ inside it — each holding a .gitkeep, so that an empty one survives
   being committed (../hora/references/spec-format.md, "a drop-off convention")
 
3. If spec.md is missing or empty, and this is the FIRST version:
       cp specs/skeleton/spec.md specs/<version>/spec.md
   Then say that it was copied, and that nothing in it is filled in yet
 
4. From the second version on, DO NOT copy the skeleton. What gets written is a
   DIFF against the version before it — only the sections this version changes.
   Start spec.md with its H1 and Document information alone, and let each stage
   add the sections it turns out this version touches
   (../hora/references/spec-format.md, "The blank spec is not copied into a
   diff version")
 
5. Run stage 0 before entering stage 1, always (references/investigation.md).
   On a project with nothing to read it is over in a sentence

Step 3 is a copy, not a draft. The skeleton lands as it ships: headings and table headers. Every value in it arrives through a stage's conversation.

Step 4 is why it is not copied twice. The skeleton's empty headings mean "the body carries over" under the diff rule, so copying it into a later version writes twenty sections that say nothing while looking like they were written.

A version whose `spec.md` already has content is edited, never restarted. Read what is there, work out which stages it already satisfies, record that in _stages.md, and enter the first stage that is not satisfied. A spec somebody wrote by hand is a spec at stage 7, not stage 1.

Stage 0 still runs, even then. A hand-written spec says nothing about which documents exist or what the repositories hold.

Never write into a past version's directory. A fix that belongs to a released version goes into the version being written now, as a full replacement of that section.

The second version onward

A released product's next version is one or two features on top of twenty that already work, and the seven stages must not make somebody re-agree to the twenty. Run head-on, stage 3 asks for user counts settled a release ago and stage 6 asks who may call operations nobody has touched — and a person answering those for the third time answers without reading.

Nothing about the format changes. What changes is how much of it this version writes (../hora/references/spec-format.md, "From the second version on, write a diff").

A stage passes by carry-over, and says so

A stage whose section nothing in this version touches is passed, with the reason written — it is not skipped, and it is not n/a.

3.[x] Non-functional requirements  <!-- carried: 1.0.0's numbers, confirmed unchanged -->

Carrying over is a check, never an assumption. The stage states what the previous version fixed, in the words it fixed it in, and asks whether what this version adds changes it.

hora  Stage 3. 1.0.0 fixed these, and nothing in the CSV export request
      touches them on the face of it:
 
        200 staff now, 5,000 within two years
        the heaviest single operation: the monthly close
        records kept for 7 years