goldspec documentation
The gold-spec methodology — how to write a spec in it, and why it is shaped this way.
| Page | For | What it is |
|---|---|---|
| Getting started | anybody writing their first chapter | one complete chapter walked part by part, with the rules the gate enforces stated where an author looks for them |
| From decision records to user stories | anybody deciding whether to adopt | a case study of a real conversion — what went wrong with prose, what the conversion cost, and what it found |
| Converting a chapter | anybody holding a spec written before the node format | what moves where, in what order, and what the conversion finds |
example/ |
anybody who would rather read a file than a page | the worked chapter from the tutorial, as a spec directory you can run goldspec against — with example/before/ holding the same chapter in the older shape |
The example is checked by this project's own suite on every run, so it cannot quietly stop being correct — an example that fails when copied teaches the conventions wrongly, to the one reader who has no way yet to tell.
The short version
- A spec is markdown a person reads. There is no vocabulary to import and no module a runner has to collect.
- One chapter is one process flow, and it holds many user stories — one for every step in it. Each is written from a person's side: as a \<role\> I want \<something\> so that \<goal\>.
- A subject is anything with an id — a node, an open unknown, a parameter, an NFR — and it is declared where it is written, never in a list beside it. A second list of ids is a second home, and it drifts.
- A chapter never carries status. What is proven is derived from a run. A status somebody typed is true because they typed it.
- An open question is anchored to the subject it affects. Anything anchored to nothing is not undefined, it is uncommitted — drop it. There is no backlog; an unproven subject is the work item.
- The conventions are yours. Ids namespaced
REQorsh, flows in a directory named to suit you: say so in agoldspec.tomland the same checks run against your layout.
Not this, and deliberately
goldspec has many opinions about your workflow, and you opted into every one by installing it. Plumb has none — it observes a test run and derives whether a story is proven, works for any project with any workflow, requires no spec, and does not know this package exists. Neither requires the other, and the boundary is enforced by a test rather than promised.