> ## 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.
# How to Version and Review a Ready Product Tree with Git
> Use Git to branch product experiments, review primitive edits, merge accepted truth, and keep an auditable history of product decisions.
Ready Standard is built for Git from the ground up. Because every primitive is a plain YAML file with a distinct extension, the same branching, review, merge, and fork tools your team uses for code work identically for product truth. A pull request reviewing a changed intent is structurally no different from a pull request reviewing a changed interface — the diff is meaningful, the history is auditable, and the merge represents a deliberate decision.
## What Git handles
Git is the backbone of the product tree. Use it for all of the following:
Create a branch to explore a different scope, actor, or product approach without affecting the main product truth. Merge if it is accepted; close the branch if it is not.
Open a pull request when a primitive changes. Reviewers see exactly which fields changed and can comment on specific lines — the same workflow as a code review.
A merge into the main branch means the team has accepted the change as product truth. Merges are the authoritative record of decisions.
Fork the tree to explore a radically different product direction or to run a spike. Forks can be merged back, used as references, or discarded.
Use `git diff` between branches to compare two milestone plans or two versions of an intent side by side.
Every accepted primitive edit lives in Git history with author, timestamp, and message. You can reconstruct the product at any point in time.
## What the app layer adds
The Ready Room app layers workflow on top of the Git-backed tree. It does not replace Git; it interprets the tree and manages the Git operations for teams that want a UI.
| App responsibility | Description |
| -------------------- | ------------------------------------------------------------------- |
| **Compiled views** | Interprets the tree for PM, developer, designer, and customer views |
| **Git management** | Manages pulls, rebases, commits, and branches on your behalf |
| **Local agents** | Runs product agents and coding handoff locally |
| **Portal targets** | Displays local or remote portal targets for publishing views |
| **Commit frequency** | Configurable commit cadence to match team latency preferences |
Your tree is valid without the app. If you prefer to use Git directly, every workflow in this guide works with standard Git commands.
## Branch conventions
Use feature branches for product experiments and decisions in progress. Merge into the main branch only when a change is accepted product truth.
```bash theme={null}
# Start a new product experiment
git checkout -b product/onboarding-skip-step2
# Work on primitives, then open a PR
git add ready/m1/intents/i-001-onboarding.ready.yml
git commit -m "intent(I-001): scope onboarding to 2 steps — skip step 2 experiment"
git push origin product/onboarding-skip-step2
```
```bash theme={null}
# After acceptance, merge to main
git checkout main
git merge product/onboarding-skip-step2
```
Commit messages that name the primitive id and type of change (`intent(I-001): ...`, `premise(P-003): ...`) make the log scannable. A reader can reconstruct product history from commit messages alone.
## What NOT to commit to Git
Local cache is not product truth and must never be committed to the product tree repository.
Do not commit any of the following:
* **Chats with agents** — these are transient and private
* **Search indexes** — these are derived and regeneratable
* **Scratch run context** — intermediate work before a decision is made
* **Raw provider transcripts** — the raw output of AI sessions before review
* **Raw local process logs** — generated by tools, not reviewed product content
* **Temporary evidence bundles** — pre-review artifacts that have not been promoted
Add a `.gitignore` entry for your local cache directory to prevent accidental commits:
```text theme={null}
# .gitignore
.ready-cache/
.local-cache/
*.scratch.md
*.raw-transcript.txt
```
## When local cache becomes product truth
Local cache is ephemeral by design. When a conversation, agent run, or scratch session produces something durable, it does not go directly into Git. Instead, the app or product agent promotes it into the right primitive type:
| Cache content | Promoted to |
| ----------------------------------- | ------------------------------------------------- |
| Agreed product decision from a chat | Premise or intent primitive |
| Resolved question from a session | Primitive edit + question card removal |
| Evidence from a discovery run | Evidence summary or artifact ref |
| Coding agent output | Flag status update + completion evidence artifact |
The promotion step is the moment of review. Only reviewed, accepted content enters the committed tree.
## Sensitive and bulky material
The committed product tree stores references to sensitive or bulky content — not the content itself.
```yaml theme={null}
# ✅ Store the credential location, not the credential
fields:
credential_location: "1Password vault > Engineering > Auth Service API Keys"
# ❌ Never commit this
fields:
api_key: "sk-live-abc123xyz..."
```
```yaml theme={null}
# ✅ Store an artifact ref for a large binary
artifacts:
- id: DS-001
path: "ready/m1/artifacts/designs/DS-001-onboarding-flow.pdf"
# ❌ Do not inline binary content or large base64 blobs
```
Do not commit secrets, API keys, tokens, passwords, or any credential values to the product tree. Store the location (vault path, environment variable name, secret manager key) instead.
Items to store as refs rather than raw content:
| Type | What to store instead |
| ----------------------- | --------------------------------------- |
| Secrets and credentials | Vault path or environment variable name |
| Source code excerpts | Snippet artifact ref + path |
| Diffs and patches | Branch name or commit hash |
| Large binary files | Artifact ref with path and hash |
| Raw logs | Evidence summary artifact ref |
**Small sanitized samples are allowed** when they are intentionally product fixtures — for example, a 10-row JSON file that represents realistic input data for an acceptance test. These should be explicitly marked `privacy: sanitized_fixture` in the artifact manifest.
## PR review as product review
Treat primitive edits in a pull request the same way you treat code changes. The diff is the product record.
```text theme={null}
# Example: a meaningful primitive diff in a PR
- scope: Steps 1–3 of the web and iOS onboarding funnel.
+ scope: Steps 1–2 of the web and iOS onboarding funnel.
+ Step 3 (avatar upload) is deferred to post-signup.
- non_scope: Avatar upload during onboarding.
+ non_scope: Avatar upload during onboarding is now in scope for M2.
```
A reviewer who understands the product can evaluate this diff the same way an engineer reviews an interface change. The history of who merged what, and when, is the auditable record of accepted product decisions.
Because primitive ids are stable and paths are refactorable, a rename or reorganization commit produces a near-zero-content diff. This makes structural housekeeping easy to review and keeps meaningful product changes distinct in the log.