> ## Documentation Index > Fetch the complete documentation index at: https://docs.dotready.org/llms.txt > Use this file to discover all available pages before exploring further. # Write High-Quality Primitive Records in Ready Standard > A practical how-to for writing .ready.yml primitive records — premises, intents, standards, services, and question cards — with full YAML examples. 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`. 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 ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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`: ```yaml theme={null} 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: ```yaml theme={null} 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. ```yaml theme={null} # 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.