specgate/docs v0.20.0

From scratch · 4 — Prove it#

In this phase

When you finish: REQ-002 marked Implemented — which Specgate only does after the gate has checked it — the whole gate green, and a page that tells anyone where the product stands.

WhoDoes what in this phase
YouAsk for the requirement to be closed
The gateDecides: the specification is complete, a test names the requirement, and your suite passes — or nothing is written
The reportTurns the matrix into a page a product owner can read

1. Close the requirement — specgate done#

bash
specgate done REQ-002
Terminal
$ specgate done REQ-002
  ◆ specgate · done REQ-002   Implemented
 
  ✔  Specification   the gate, for REQ-002
  ✔  Tests           node --test
 
  ✔  REQ-002 → Implemented (1 row updated)
 
  Next ───────────────────────────────────────────────────
  ➜  specgate status
     what is left, and the next requirement

Before writing Implemented, done ran the gate for REQ-002 and your test command. A missing test, a <placeholder> left in a scenario or a red suite, and it refuses — and writes nothing.

2. Watch it refuse what is not finished#

REQ-004 is waiting for the client's answer about the late-cancellation fee:

bash
specgate done REQ-004
Terminal
$ specgate done REQ-004
  ✖  REQ-004  not marked Implemented: REQ-004 is waiting for an answer (Needs Clarification).  [done_needs_clarification]
     fix: Answer the question that blocks it in its change's questions.md, remove `status="Needs Clarification"` from its `specgate:trace`, write its test, then run `done`.

That refusal is the point. An agent asked to "finish the bookings module" cannot close it by inventing the fee; the question stays open until a person answers it.

3. Run the whole gate — what CI will run#

bash
specgate check
Terminal
$ specgate check
  ◆ specgate · check   court-bookings
 
  ✔  Specification   validate --strict
  ✔  Tests           node --test
 
  ✔  Gate passed — the specification and `node --test`

check is validate --strict and then your tests. Requirements still in Draft owe nothing and are counted as exempt, so a pass never hides its own scope.

4. Show where it stands — specgate report#

bash
specgate report --out report.html
Terminal
$ specgate report --out report.html
  ◆ specgate · report
 
  ✔  Wrote report.html
 
  █████░░░░░░░░░░░░░░░  1 of 4 implemented   25%

One self-contained HTML page: what is done, what is pending, what is missing a test, and what is waiting for an answer — readable without the repository. Here is the same report on one of the pilots:

The specgate report for the HealthTech pilot: 23 of 24 requirements implemented, each with its feature, test and code, and one waiting for an answer.

You're done when…#

  • specgate done REQ-002 printed → Implemented.
  • specgate check ends with ✔ Gate passed.
  • report.html opens and shows your requirements.

If something goes wrong#

You seeIt meansDo
[TDD-1] Test artifact is TBD but status is 'Implemented'No test names the requirementMention REQ-NNN in its test — a comment or the test name
unfilled placeholder in "given <the state before the action>"A scenario still has the template's <placeholders>Write the real Given/When/Then
not marked Implemented: the project's tests failed. [done_tests_failed]Your suite is redMake it pass, then done again
REQ-004 is waiting for an answer (Needs Clarification). [done_needs_clarification]An open question blocks itGet the answer, record it, remove the status, then test and close

Next: phase 5 — every day →