Research claims and evidence

Outcome

Create a disposable claims bundle, file one measurable claim with reproducible provenance, cite it from a report, challenge and verify it with compare-and-swap, then supersede it without erasing the history. This tutorial is for researchers and analysts who need numbers to remain reviewable across sessions and outputs.

The package-shipped claims recipe is verified against the current stable release.

Starting state

Use an empty disposable directory and an actor name you will keep throughout the example. The recipe ships as an inspectable package reference rather than a short built-in name. Resolve its installed path first:

mkdir claim-demo
CLAIMS_RECIPE="$(npm root --global)/superbee/references/recipes/claims"
test -f "$CLAIMS_RECIPE/recipe.md"
superbee init --dir claim-demo/.superbee --recipe "$CLAIMS_RECIPE" --create-only
superbee kinds --dir claim-demo/.superbee

In PowerShell, the equivalent recipe-path check is:

$ClaimsRecipe = Join-Path (npm root --global) "superbee/references/recipes/claims"
Test-Path (Join-Path $ClaimsRecipe "recipe.md")
superbee init --dir claim-demo/.superbee --recipe $ClaimsRecipe --create-only

If Superbee is installed in a project prefix instead of globally, replace npm root --global with that install's npm root result. A plain --recipe claims is not a supported spelling.

Confirm Claim requires title, progress_status, and reason, permits the provenance fields evidence_command, evidence_commit, and artifacts, and declares the lifecycle values active, challenged, locked, and deprecated.

1. File a specific claim

The title is the claim and includes the measured number. The reason explains how it was derived.

superbee new "Claim" onboarding-completion \
  --dir claim-demo/.superbee \
  --title "8 of 10 participants completed onboarding without assistance" \
  --progress_status active \
  --reason "Counted successful completions in the reviewed session table." \
  --evidence_command "node scripts/count-completions.mjs fixtures/sessions.csv" \
  --evidence_commit "0123456789abcdef0123456789abcdef01234567" \
  --actor analyst/a

Checkpoint:

superbee doc read claims/onboarding-completion --dir claim-demo/.superbee

The document ID is beneath claims/, its title carries the actual finding, and its state is active. The example commit is illustrative; real work must record the exact commit used by the evidence command.

2. Add evidence and a citation

Create a source record and a report, then relate both to the claim:

superbee doc write sources/onboarding-sessions \
  --dir claim-demo/.superbee \
  --type Source \
  --title "Reviewed onboarding session table" \
  --body "Ten consented sessions, reviewed under the study protocol." \
  --actor analyst/a

superbee doc write reports/onboarding-summary \
  --dir claim-demo/.superbee \
  --type Report \
  --title "Onboarding summary" \
  --body "The completion result remains provisional until independent verification." \
  --actor analyst/a

superbee link add claims/onboarding-completion sources/onboarding-sessions \
  --dir claim-demo/.superbee --text evidence --actor analyst/a
superbee link add reports/onboarding-summary claims/onboarding-completion \
  --dir claim-demo/.superbee --text cites --actor analyst/a

Inspect both directions:

superbee link show claims/onboarding-completion --dir claim-demo/.superbee

The source appears as an outbound evidence link and the report appears as a derived backlink. That backlink is the impact list when the claim changes.

3. Challenge and independently verify

Capture the exact version you reviewed:

CLAIM_VERSION="$(superbee doc read claims/onboarding-completion \
  --dir claim-demo/.superbee --field head_version)"
superbee doc update claims/onboarding-completion \
  --dir claim-demo/.superbee \
  --progress_status challenged \
  --expected-version "$CLAIM_VERSION" \
  --actor reviewer/b

The reviewer reruns evidence_command against evidence_commit, checks the source and exclusions, then locks the fresh version:

CLAIM_VERSION="$(superbee doc read claims/onboarding-completion \
  --dir claim-demo/.superbee --field head_version)"
superbee doc update claims/onboarding-completion \
  --dir claim-demo/.superbee \
  --progress_status locked \
  --reason "Independent rerun reproduced 8 successful completions from 10 reviewed rows." \
  --expected-version "$CLAIM_VERSION" \
  --actor reviewer/b

Only a verified locked claim should support the final numeric statement. STALE_HEAD means the claim changed during review; inspect the fresh version and rerun any affected evidence.

4. Supersede instead of rewriting a locked claim

When new sessions change the result, preserve the locked claim and file a successor:

superbee new "Claim" onboarding-completion-expanded \
  --dir claim-demo/.superbee \
  --title "17 of 20 participants completed onboarding without assistance" \
  --progress_status active \
  --reason "Expanded the reviewed sample from 10 to 20 sessions." \
  --evidence_command "node scripts/count-completions.mjs fixtures/sessions-20.csv" \
  --evidence_commit "fedcba9876543210fedcba9876543210fedcba98" \
  --link "supersedes=claims/onboarding-completion" \
  --actor analyst/a

CLAIM_VERSION="$(superbee doc read claims/onboarding-completion \
  --dir claim-demo/.superbee --field head_version)"
superbee doc update claims/onboarding-completion \
  --dir claim-demo/.superbee \
  --progress_status deprecated \
  --reason "Superseded by the expanded 20-session sample." \
  --expected-version "$CLAIM_VERSION" \
  --actor analyst/a

Update citing reports only after the successor is independently locked. link show on the old claim identifies every citation needing review.

Final verification

superbee list --type Claim --dir claim-demo/.superbee --limit 0
superbee link show claims/onboarding-completion --dir claim-demo/.superbee
superbee link show claims/onboarding-completion-expanded --dir claim-demo/.superbee
superbee status --dir claim-demo/.superbee

The final bundle preserves the original locked finding, its evidence and citations, a related successor, attributed lifecycle changes, and an inspectable current state.

Cleanup and adaptation

Remove the disposable claim-demo directory when the tutorial is complete. In real work, keep the bundle under the chosen privacy and Git-sharing policy, replace illustrative commands and commits with executable evidence, and use Query, links, and backlinks to review active, challenged, locked, and deprecated claims.

Governing evidence

The model is defined by the tagged claims recipe and the stable versioned document and link commands.