Write A Spec
Extend a core journey in evals/core or write a one-off proof in evals/proofs that...
Install
npx skills add different-ai/openwork --skill write-a-spec -g -a claude-code -y- Repository
- different-ai/openwork24.4k
- Category
- Git and review
- Updated
- 3d ago
- License
- See repository
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- No, instructions only
What it does
Extend a core journey in evals/core or write a one-off proof in evals/proofs that proves a PR's change to a human reviewer. Use when a PR changes user-visible behaviour, when a reviewer asks "show me", or when the coverage decision says a journey is missing.
Skill: Write a Spec
Every evals/core/*.e2e.test.ts or evals/proofs/*.proof.test.ts a PR adds or
changes runs in CI on the PR head and is published as that PR's proof (private report + one PR comment).
Write the spec for the person who will read that report in thirty seconds,
not for the machine that runs it.
Map: from change to reviewed proof
| Moment | Skill | Output |
|---|---|---|
| Decide whether a journey is needed and design it | write-a-spec (this) | a spec whose titles, steps, and evidence read as the report |
| Run it and read your own record | run-tests | evals/results/test-runs/<latest>/ with the captions in order |
| Let a reviewer click through the change | preview-my-work | a sandbox link in the report's Show sandbox panel |
| Describe it on the PR | open-a-pr | an ## Evidence line naming the spec and its before → after |
| A proof or check is red | diagnose-a-red-run | classification before any code change |
| Extra screenshots or a video outside the spec | record-a-demo, upload-photo | PR attachments (these are not proof) |
Which lane runs your spec (and when to tag)
CI picks the lane from the file name and tags alone. Pick the lane first: it decides the world you can build.
| If the spec… | Name / tag | CI lane |
|---|---|---|
| proves your change (default) | evals/proofs/<name>.proof.test.ts | the dev push that adds or changes it ("Core journeys"); on demand with PR change proof |
changes one of the nine core journeys in evals/journeys.ts | evals/core/<journey>.e2e.test.ts | core journeys on every dev push and nightly |
| needs a reviewer to reopen the running browser at a screenshot | add { tags: ["checkpoints"] } to the test(...) options | protected checkpoint lane on Freestyle (not run by manual proof runs) |
