Write High-Quality Primitive Records in Ready Standard

Primitives are the atoms of a product tree. Every value that an app, compiler, validator, search index, or coding agent must read goes in YAML. Reader-friendly views — PM summaries, developer briefs, designer views, customer-facing docs — are compiled from these records, not authored alongside them. This guide shows you how to write each type well.

The core principle

Put product truth in structured fields, not in prose summaries. A summary is useful for humans skimming the tree, but tools cannot reliably parse prose. If a value shapes scope, acceptance criteria, a dependency, or a measurement rule, it belongs in fields or refs.

Premise
Intent
Standard
Service
Question Card

A premise explains why the product (or a feature within it) should exist. Write premises before intents. Every intent should ultimately serve at least one premise.Key fields for a premise:

evidence_confidence: low, medium, or high — how certain you are the premise is true
evidence_provenance: where the evidence came from (interview, analytics, research, doc)
product_implication: what the product must or must not do if this premise holds

schema: readyroom/primitive/v1
kind: primitive
id: P-001
type: premise
title: Users abandon multi-step onboarding before completing step 3
milestone: m1
status: active
summary: >
  Activation data shows 68% of new users exit the onboarding flow
  at or before step 3, resulting in incomplete profile setup and
  lower feature discovery rates.
fields:
  evidence_confidence: high
  evidence_provenance: "Product analytics export, 2024-03-01; confirmed by product lead"
  product_implication: >
    The onboarding flow must be completable in fewer than three steps
    OR must make the value of continuing obvious at each step.
    Features that require a complete profile cannot be gated behind
    a broken funnel.
refs: []
artifacts:
  - SA-001   # sanitized funnel export used as fixture
owner_notes:
  - "Step 3 drop-off worsened after the March password policy change."

Do not raise evidence_confidence to high until a product lead or stakeholder explicitly confirms the premise. A premise inferred from a design doc alone starts at low or medium.

An intent is a product promise: what the product commits to doing for a specific actor. A committed intent needs an actor, action, expected end state, value, scope, non-scope, failure behavior, input and output data, required services, and required standards.When behavior can vary materially after release, add an operating_envelope block for quality-bearing intents.

schema: readyroom/primitive/v1
kind: primitive
id: I-001
type: intent
title: User completes onboarding in a single session
milestone: m1
status: active
summary: >
  A new user can finish account setup, confirm their profile, and
  reach the home screen without leaving the app or restarting the flow.
fields:
  actor: New user (unauthenticated → authenticated)
  action: Complete all onboarding steps and confirm their profile
  expected_end_state: >
    The user has a confirmed profile, a verified email, and sees
    the home screen with at least one feature prompt visible.
  value: >
    Completing onboarding in one session increases feature discovery
    and reduces support contacts about missing profile data.
  scope: >
    Steps 1–3 of the current onboarding funnel for web and iOS.
  non_scope: >
    Onboarding for invited team members; enterprise SSO flows;
    password reset during onboarding.
  failure_behavior: >
    If any step fails, show a contextual error with a retry action.
    If the session expires mid-flow, restore progress from local
    draft on next open. Do not restart from step 1.
  input_data: Email address, display name, optional avatar upload
  output_data: Confirmed user record, verified email flag, session token
  operating_envelope:
    step_completion_p95_ms: 2000
    total_flow_p95_s: 90
    error_rate_max_pct: 2
refs:
  - from: I-001
    role: serves
    to: P-001
  - from: I-001
    role: requires
    to: SV-001
  - from: I-001
    role: governed_by
    to: ST-001
artifacts: []
owner_notes:
  - "iOS and web share the same acceptance criteria; native Android is out of scope for M1."

Completion Proof does not live on intent bodies. It belongs on the seed or delta flag that gates coding work. Keep intents focused on the product promise, not the implementation lifecycle.

A standard states a concrete, measurable rule for how the product must be built, measured, judged, or maintained. Avoid vague standards like “make it clean” or “handle errors gracefully.” Every standard must be falsifiable.

schema: readyroom/primitive/v1
kind: primitive
id: ST-001
type: standard
title: Onboarding flow error states must be self-recoverable
milestone: m1
status: active
summary: >
  Every error state in the onboarding flow must present a
  user-actionable recovery path without requiring a support contact
  or a full flow restart.
fields:
  rule: >
    Each error state must display: (1) a plain-language description
    of what went wrong, (2) a retry or corrective action button,
    and (3) a way to skip the step if it is optional.
  measurement: >
    QA must be able to trigger every error state in a test environment
    and confirm the recovery path resolves without restarting from step 1.
  applies_to: All onboarding steps for web and iOS
  enforcement: Blocking for release — no error state may ship without a recovery path
refs: []
artifacts: []
owner_notes: []

A service captures a dependency the product needs to build, prove, run, or monitor. Write one service record per external or internal system you depend on. Be explicit about readiness gaps — a service with unknown credential location blocks coding claims.

schema: readyroom/primitive/v1
kind: primitive
id: SV-001
type: service
title: Auth service — email verification
milestone: m1
status: active
summary: >
  The email verification API that sends one-time codes during
  onboarding and confirms user email ownership.
fields:
  environments:
    staging:
      url: "https://auth-staging.example.com"
      status: available
    production:
      url: "https://auth.example.com"
      status: available
  access: API key required per environment
  credential_location: "1Password vault > Engineering > Auth Service API Keys"
  proof_policy: >
    Integration test must send a real OTP to a test inbox and confirm
    receipt within 30 s before the intent can be marked complete.
  failure_modes:
    - OTP delivery delayed beyond 60 s → show resend option
    - API returns 503 → block onboarding step, show retry, log incident
  simulation_rules: >
    Use magic code "000000" in staging for automated test flows.
    Never commit magic codes to production config.
  observability: "Datadog dashboard: Auth Service SLOs"
  privacy: OTP codes are single-use and expire in 10 minutes
  owner: "Platform team — @platform-oncall"
  readiness_gaps:
    - "Staging rate limit is 10 req/min — may block parallel test runs."
refs: []
artifacts: []
owner_notes: []

List every readiness gap you know about. A gap you document here prevents a coding agent from hitting a wall mid-implementation. Undocumented gaps are the most common cause of blocked flags.

A question card holds product-shaping ambiguity. Use one whenever an open question would change the scope, actor, or acceptance criteria of an intent if answered differently. When the question is answered, apply the resulting edits to the affected primitives and remove the active question card — history lives in Git.

schema: readyroom/primitive/v1
kind: primitive
id: QC-001
type: question_card
title: Should email verification be required before step 2?
milestone: m1
status: active
summary: >
  It is unclear whether email verification must block onboarding
  progress or can be deferred to post-signup. The decision changes
  the scope of I-001 and the failure behavior of SV-001.
fields:
  resolution_path: >
    Product lead and security lead to decide by 2024-04-10.
    Check whether deferred verification increases fraudulent
    profile creation in comparable products.
  blocking:
    - I-001
    - SV-001
  options:
    - id: A
      description: "Require verification before step 2 — strictest, fewest fraud vectors"
    - id: B
      description: "Defer to post-signup — faster funnel, requires fraud monitoring"
refs: []
artifacts: []
owner_notes:
  - "Security team leans toward option A. Product team is investigating funnel impact."

Refs: storing relationships correctly

Relationships between primitives go in refs, not in summary prose. There are five approved ref roles. The four canonical tree edges for primitive relationships are:

Edge	Meaning
`intent --serves--> premise`	The intent addresses a root product premise
`intent --contains_premise--> premise`	The intent owns a subordinate premise
`intent --requires--> service`	The intent depends on a service
`intent --governed_by--> standard`	The intent must obey a standard

The fifth role, questions, is used on refs where a question card or flag explicitly references the primitives it is questioning or blocking. Store only the outgoing edge from the source record. Do not store inverse edges. Views derive inverse labels automatically. If you write premise --serves--> intent, you are duplicating the edge and making the tree harder to validate. Explicit refs include from, role, and to:

refs:
  - from: I-001
    role: serves
    to: P-001

Compact refs infer from as the current primitive id. Use compact refs only for outgoing edges:

refs:
  - role: requires
    id: SV-001

What NOT to put in primitives

The following do not belong in .ready.yml primitive records:

Coding lifecycle state — use seed or delta flags for that
Local chat logs or raw provider transcripts — these are local cache, not product truth
Secrets or credentials — store the credential location (e.g., vault path), never the value
Raw logs or unreviewed scratch content — promote to a primitive only after review
Large binaries or source diffs — use artifact refs instead

Artifacts: when to use refs instead of inline content

Store bulky samples, mockups, screenshots, snippets, and generated outputs as artifacts. Reference them by id or path in the primitive’s artifacts field rather than inlining their content.

# In the primitive
artifacts:
  - SA-001   # compact ref by artifact id

# In ready/m1/artifacts/manifest.yaml
id: SA-001
artifact_type: sample_data
path: ready/m1/artifacts/samples/SA-001.json
privacy: sanitized_fixture
used_by:
  - I-001
roles:
  - input_sample

Small sanitized samples are allowed inline when they are intentionally product fixtures and their presence is meaningful for review. When in doubt, use an artifact ref.

​The core principle

​Refs: storing relationships correctly

​What NOT to put in primitives

​Artifacts: when to use refs instead of inline content

The core principle

Refs: storing relationships correctly

What NOT to put in primitives

Artifacts: when to use refs instead of inline content