docs(quickstart): rewrite for fresh-user clarity#230
Open
Conversation
Two clean-room dogfood passes (round 1 + round 2 fresh-user agents,
both ignoring CLAUDE.md / memory / rivet source) surfaced six concrete
issues in the embedded quickstart:
1. No "What is rivet?" preamble — readers assembled the mental model
by osmosis from example commands.
2. Step 9 referenced Mythos red-team scaffold ("if you cloned the
rivet repo") — out of scope for first-contact, confused readers.
3. Step 1 install said `cargo install --path rivet-cli` without
noting that requires a clone of the rivet repo.
4. Step 2's goal claimed `init` scaffolds `schemas/` (it doesn't)
and didn't mention the seed `artifacts/requirements.yaml` that
collides with step 3's REQ-001.
5. Step 7's Python oracle used `error_count` key (vacuously true);
actual JSON key is `errors` — a real broken link wasn't caught.
6. Existing-repo overlay snippet elided "all other base fields" with
a placeholder, setting up the very G.2 trap it warned about.
Changes:
- Add 6-line "What is rivet?" preamble (typed YAML + schema +
graph + four interfaces; DOORS/Polarion/Jira analogy).
- Step 1: explicit "from a clone of the rivet repo" caveat on
`cargo install --path`; npm + binary-release alternatives.
- Step 2: drop schemas/ from goal sentence; add preset glossary
(dev, aspice, stpa, eu-ai-act, safety-case); mention the seed.
- Step 3: prepend `rm artifacts/requirements.yaml` to clear seed.
- Step 7: fix Python oracle key (`error_count` → `errors`).
- Step 9: replace Mythos with "Add a living document" walking
markdown frontmatter + `{{stats}}` / `{{coverage}}` / `[[ID]]`
embeds; explicit `rivet serve` restart since step 8 killed it.
- Step 10: drop deep-audience acronyms (Kani/Verus/Rocq) from the
docs list; gloss MCP and LSP one-liner each.
- New Existing-repo bring-up appendix: pick preset, curate ~5
artifacts per layer, dump base type with `rivet schema show`,
write a complete copy-pasteable overlay (extends `requirement`
from dev preset with `polarion_id`, all base fields and
link-fields explicitly listed — no "..." placeholders).
- New Common gotchas appendix G.1–G.7: LSP overlay blindness,
overlay merge field-drop, forward/inverse link types, doc vs
artifact refs, imported-stub honesty, lifecycle severity intent,
schema-show preset locality.
Net: 251 → 535 lines. The oracle-gated 10-step rhythm is preserved;
new material is in two appendices that readers opt into.
Verified: round-2 fresh-user dogfood ran all 10 oracles green and
confirmed the broken-link demo (changing target REQ-001 → REQ-999
makes the step-7 oracle exit 1 with a real error).
Implements: REQ-007
Refs: FEAT-001
📐 Rivet artifact deltaNo artifact changes in this PR. Code-only changes (renderer, CLI wiring, tests) don't touch the artifact graph. |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…t contract Three parallel scenario-based fresh-user dogfood agents (STPA safety, Polarion-import compliance, MCP integrator) all reached their goals but surfaced four cross-cutting issues: 1. Step 2 oracle didn't tell non-`dev` users their seed file IS a worked example (e.g. `artifacts/safety.yaml` for `stpa` ships a complete loss/hazard/uca chain). Non-`dev` users either deleted it following step 3's `rm`, or didn't realize they could skip steps 3+6 entirely. 2. Step 3's `rm artifacts/requirements.yaml` is correct for `dev` but actively wrong for non-`dev` presets — it nukes their pre-built domain example. 3. Existing-repo appendix's overlay example is `dev`-flavored. ASPICE `sw-req` has a *required* `derives-from` link to system-req/arch — a category difference, not just a quantity difference. Hand-waving "the same pattern applies, lists are longer" sets up the very G.2 trap the appendix warns against. Compliance leads importing from Polarion are the primary audience for this section. 4. No written promise of `rivet init` non-destructiveness on a non-empty repo. A real Polarion-import lead won't run a foreign CLI on 10k files without that contract in writing. Changes: - Step 2: add a callout distinguishing `dev` (seed is placeholder, follow steps 3+6 to write your own) from non-`dev` presets (seed is a worked example in domain vocabulary, read it and skip to step 4). Pointer to `rivet docs schema/<your-preset>` for the type catalogue. Tip about `rivet schema show <bad-type>` errors as a free schema dump. - Step 3: gate the seed `rm` with "`dev` preset only" callout; point non-`dev` readers to step 4. - Existing-repo appendix: add "What `rivet init` touches in a non-empty repo" section stating the non-destructiveness contract explicitly (rivet.yaml + artifacts/ + docs/ + one seed file; nothing else). - Existing-repo appendix: add a complete copy-pasteable ASPICE overlay (sw-req extended with polarion_id / polarion_status / asil, listing all base fields and the required `derived-from` link-field with target-types and cardinality verbatim from `rivet schema show sw-req`). - Existing-repo appendix: document the stub-parent tradeoff — curating one `sw-req` from a Polarion export forces a parent stub on `system-req`. Pattern: `status: imported-stub` (WARN via G.5) rather than faking content. Verified: - Scenario A (STPA) reached PASS in 13min on prior version; the step-2 callout would have collapsed the scenario's "I didn't know the seed was the tutorial" wall-clock. - Scenario B (Polarion → ASPICE) reached PASS in 7min with an ASPICE overlay matching the new appendix snippet (modulo formatting); the worked example replaces the hand-wave. - `rivet schema show sw-req` from a fresh `aspice` project on rivet 0.4.3 confirms the field/link-field shape used in the overlay matches the binary 1:1. Implements: REQ-007 Refs: FEAT-001
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
⚠️ Performance Alert ⚠️
Possible performance regression was detected for benchmark 'Rivet Criterion Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.
| Benchmark suite | Current: 5fcc4a2 | Previous: 92ad95d | Ratio |
|---|---|---|---|
query/10000 |
140295 ns/iter (± 824) |
109024 ns/iter (± 1298) |
1.29 |
This comment was automatically generated by workflow using github-action-benchmark.
…stub chain Round-3 fresh-user dogfood (sandbox /tmp/legacy-repo-3) verified the 4-of-5 round-2 fixes landed cleanly, but caught one partial-impact gap: the existing-repo appendix's stub-parent tradeoff section documents the sw-req → system-req hop but not the transitive system-req → stakeholder-req requirement. Result: when a compliance lead curates one sw-req from a Polarion export, they add a system-req stub (per the appendix), validate, and hit a *second* error: `[SYSREQ-PRODUCER] link 'derives-from' requires at least 1 target` because system-req's own ASPICE rule requires a derives-from to a stakeholder-req. They have to add a second stub they didn't expect. Changes: - Stub-parent tradeoff section now spells the full two-hop chain (stakeholder-req → system-req → sw-req) with both stubs in YAML, showing the system-req stub's `derives-from: STKHR-*` link explicitly. - Pointer to `rivet schema show <type>` to discover further required derives-from chains for any other base type. - Cross-reference to gotcha G.3 (forward vs inverse link-type direction) inline next to the overlay, since the same `aspice` schema's `allocated-from` is registered only as an inverse and the seed itself trips this — readers writing similar links into their own arch components will hit the same error. Verified: round-3 dogfood reached PASS in 3.8min (vs 7min round 1, 5min round 2). All 5 step-2/3 + appendix fixes verified in place via explicit grep checks before the dogfood walked the doc. Separate finding (NOT fixed in this PR — needs a binary patch): `rivet init --preset aspice && rivet validate` ships a seed that fails validation with 2 errors (SYSREQ-001 missing derives-from target; SWARCH-001 uses undeclared `allocated-from` link). Filed separately. Implements: REQ-007 Refs: FEAT-001
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The embedded
rivet docs quickstart(shipped in 0.5.0) was written from inside the rivet repo and assumed the reader was working there too. Two clean-room fresh-user dogfood passes — both with explicit instructions to ignore CLAUDE.md, auto-memory, and any rivet source files — surfaced six concrete issues that confuse a real first-contact user.This PR rewrites the quickstart to fix all six, preserving the oracle-gated 10-step rhythm.
What changed
cargo install --path rivet-cliassumes you're inside the rivet checkoutinitscaffoldsschemas/(it doesn't); no mention of seedrequirements.yamlcolliding with step 3's REQ-001rm artifacts/requirements.yamlerror_countkey (vacuously true); actual JSON key iserrors{{stats}}/{{coverage}}/[[ID]]embeds + explicitrivet serverestartNew material (appendices, opt-in)
rivet schema show, write a complete copy-pasteable overlay extendingrequirementfrom thedevpreset withpolarion_id. All base fields and link-fields listed explicitly — no# ...placeholders.imported-stubhonesty, lifecycle severity scaling intent,rivet schema showpreset locality.Verification
Round-2 fresh-user dogfood (clean-room agent ignoring CLAUDE.md / memory / rivet source) ran all 10 oracles green and confirmed step 7 catches a real broken link (changing
target: REQ-001→REQ-999makes the assertion fail and the oracle exit 1).Test plan
cargo test -p rivet-clipasses (no logic changed; quickstart isinclude_str!'d at build time)rivet docs quickstart | head -3renders the new "What is rivet?" preamble🤖 Generated with Claude Code