Operating Model

Last updated: 4/24/26

Purpose

This document defines how we ship software: one coherent change at a time, clear documentation, predictable review, and branches that match reality. It exists because inconsistent practices create brittle workflow, noisy PRs, and preventable defects.

Problems we are correcting

Issue	Expectation
Multiple unrelated features in one PR	One PR = one logical deliverable (one feature, one fix, or one tightly scoped refactor). Split follow-ups into separate PRs.
Feature branch not rebased / base branch stale	Before opening or materially updating a PR: sync default integration branch locally, rebase (or merge per team convention), resolve conflicts, push, verify CI.
Authors not reviewing their own diff	No reviewers added until the author has completed the author review (below).
Over-engineered solutions	Match complexity to the actual use case: prefer the smallest design that meets agreed requirements and leaves a credible extension path. Document why a heavier approach was rejected when alternatives were considered.
Under-engineered solutions	Call out scale, shape, and evolution in planning: volumes, latency, concurrent use, and how data is modeled (e.g. when a concept deserves a typed object or nested structure vs flat primitives). Reviewers reject “convenient now, expensive later” shortcuts when the plan already implied scale.
Low test coverage	New or changed behavior includes automated tests appropriate to risk (see Testing expectations). Gaps need a short, explicit rationale in the PR—not silence.
Critical decisions reviewed too late	Decide before deep implementation: API and persistence shape, ownership boundaries, and other hard-to-reverse choices must be captured in the planning doc (or ADR) and go through EM signoff when applicable—see §5—so we avoid downstream rework and churn.
Weak paper trail in Asana	The work ticket links the plan-review PR, the implementation PR, and other artifacts (deploy URLs, Loom, Google planning docs, etc.)—see Asana: paper trail in the feature lifecycle.

Feature lifecycle (end-to-end)

1. Start the feature

Create a focused branch from the current integration branch (e.g. staging).
Name it so intent is obvious (e.g. feat/…, fix/…).

2. Planning document (`/docs/plan`)

Add a planning doc at docs/plan/<short-slug>.md in the repo root (create docs/plan if needed). Alternatively, use Cursor plan mode, make sure to address the contents below, and have it write the output to docs/plan.
Minimum contents:
- Problem / outcome — what user or system behavior changes.
- Scope — in scope / explicitly out of scope.
- Requirements — product expectations and engineering constraints (APIs, performance, security, rollout).
- Scale & constraints — expected volume, growth, latency or throughput needs, and concurrent-use assumptions so design is not under-scaled.
- Data modeling — how concepts are represented (structured types vs loose fields), validation boundaries, and when something is intentionally deferred.
- Approach — high-level design; link or embed diagrams if useful.
- Proportionality — simplest viable approach and explicit tradeoffs (what we are not building now and why); avoids both gold-plating and one-off hacks that contradict stated scale.
- Decisions (pre-implementation) — API/persistence boundaries, cross-service contracts, and other hard-to-reverse choices stated clearly; unresolved items listed as blockers before large implementation spend.
- Risks & open questions — unknowns and decisions pending.
- Test plan — what will be automated vs manually verified.
When the draft is ready for feedback, review it in a draft PR with reviewers added—see §3.

3. Reviewing the plan (and other markdown)

Use the same PR workflow for planning docs and any other markdown you want reviewed before implementation (RFCs, ADRs, long-form specs in-repo).

Open a draft PR that contains only the document(s) under review (or the smallest diff that isolates them). Base branch follows team convention (e.g. staging).
Add the reviewer(s) immediately—draft PRs still support comments, suggestions, threads, and notifications, which beats ad hoc doc links or chat for tracking resolution.
Work feedback to completion in the PR: reply in threads, accept or push edits, and resolve conversations so the record is clear.
Close the PR without merging once review is done and open items are addressed. The branch can be discarded; the value is the review history and the updated content on the branch that you carry into the implementation branch (cherry-pick, re-apply, or recreate commits as you prefer). Do not treat closing the plan-review PR as “merged design”—merge happens with the implementation PR when code ships.

If the planning doc lives on the same branch as later implementation work, you may instead keep one PR and transition it from “plan review” to “code review” after rebasing or force-pushing implementation commits—only when that stays one logical deliverable and reviewers understand the phase change.

4. Requirements

Product: acceptance criteria, UX copy, edge cases, analytics or flags if relevant.
Engineering: dependencies, API contracts, data model touchpoints, observability, rollback.

Document agreements in the planning doc or linked ticket so reviewers can trace decisions. If a decision is expensive to undo (schema, public API, event shape, security model), it belongs here and must be settled—or explicitly scoped down—before implementation proceeds at scale.

5. Engineering manager signoff (before implementation)

Do not start substantial implementation until signoff when the change involves any of the following. If unsure, ask—default to signoff.

Always require signoff

Architecture — new services, major module boundaries, significant refactors that change how the system is structured.
Control flow across systems — sequence or flow that spans multiple services, jobs, or user-visible steps (diagram recommended); use .cursor/commands/diagrams.md to produce Mermaid as needed.
Database — new collections/tables, non-trivial schema changes, indexes strategy, migrations, backfills, or data integrity rules.
Security & access — authentication, authorization, handling of secrets, PII, or permission models.
External integrations — new third-party APIs, webhooks, or material changes to existing integrations.
Breaking or versioned contracts — public APIs, events, or client assumptions that other teams or repos rely on.
Cost or quota impact — LLM usage, new paid services, or large fan-out work.
Cross-repo or multi-app coordination — changes that must land in a specific order across repositories.
Irreversible or wide-impact contracts — anything that will force broad refactors if wrong: primary identifiers, core domain types exposed to clients, event payloads, or “primitive soup” that should be a stable structured model before data accumulates.

Usually require signoff (unless explicitly small / local)

Feature flags / experiments — when rollout strategy affects production behavior or data.
Performance-sensitive paths — hot paths, N+1 queries, large payloads, caching changes.
Observability — new critical metrics/alerts or removal of existing ones.

Optional check-in (brief async OK)

Small UI tweaks with no new data paths.
Bug fixes that restore documented behavior without new contracts.

6. Implementation

Follow repository standards (e.g. CLAUDE.md, .cursor/rules/*, API and coding standards).
Keep the planning doc updated if scope or design shifts materially.
Right-size the solution: if implementation diverges into a much larger or much flimsier design than the plan, stop and re-align (async or signoff)—do not ship surprise complexity or surprise shortcuts.

7. After implementation (before PR is “ready for review”)

Tests — add or update unit/API/integration coverage per change; use .cursor/commands/write-unit-tests.md when helpful.
Promote documentation — move or summarize the planning content into docs/features/<feature-slug>.md (or the team’s agreed feature-doc layout): final behavior, configuration, rollout notes, and links to code or APIs.
Optional quality passes (use when relevant): .cursor/commands/deslop.md, .cursor/commands/add-error-handling.md, .cursor/commands/security-review.md, .cursor/commands/accessibility-audit.md, .cursor/commands/optimize-performance.md.
Author review (mandatory):
- Run tests and any required manual checks from the test plan.
- Use .cursor/commands/code-review.md against staging (or main if staging does not exist) for a structured pass.
PR — use .cursor/commands/generate-pr-description.md then .cursor/commands/create-pr.md (default base staging). Review your own PR as if you were a reviewer; fix typos, dead code, missing tests, and obvious issues. Keep the PR in draft until the checklist below is satisfied.
Request reviewers only after the PR is green, description is complete, and author review is done.

8. Asana: paper trail

The Asana task should stay the async source of truth for where work lives: major decisions, PRs, deploys, and other references anyone might need later.

Plan review — If you produced an implementation plan for EM review (draft PR, external doc, or other artifact), add an Asana comment with a link to the plan review PR when that PR exists. Links to closed PRs still work; prefer the canonical GitHub link so the history remains reachable.
Implementation — When you submit (open) the implementation PR, add an Asana comment with a link to that PR so the plan and the shipping change stay connected.
Other artifacts — In the same ticket (comments, description, or attachments as fits your process), include anything else that matters for review or handoff: deployment or preview links, Loom or other walkthroughs, planning documents in Google Drive, and any other relevant links (metrics, runbooks, follow-up tickets).

Testing expectations

Default: new logic and bug fixes include tests that would fail without the change (unit, API, or integration—whatever fits the layer).
Coverage: aim to cover happy path plus meaningful edge cases and error paths for new surface area; don’t merge large untested branches without EM agreement.
If tests are skipped or minimal, the PR description states why (e.g. time-boxed spike behind a flag, follow-up ticket linked).
Reviewers treat unexplained low coverage as Request changes material when risk is non-trivial.

Git and PR discipline

Branch hygiene

Integration branch (e.g. staging) should be current when you open or materially update a PR.
Prefer rebase onto the latest integration branch before review (or merge, if that is the team standard—pick one and be consistent).

Pull request rules

Never merge without review: Do not merge a PR until it has been reviewed and approved by the required reviewers (no self-merge without approval, no bypassing review).
Draft until ready for human review (description complete, CI passing, author review done).
One logical change per PR; stack dependent PRs if needed instead of bundling.
Reviewers: add them only after you would be comfortable approving the diff yourself.
Reviewers: use Request changes when the bar is not met; be specific.
Author: after addressing feedback, summarize what changed and re-request review from the people who blocked.

Cursor commands (reference)

Stage	Command
Planning / design diagrams	`.cursor/commands/diagrams.md`
Self-review before reviewers	`.cursor/commands/code-review.md`
Tests	`.cursor/commands/write-unit-tests.md`
PR description	`.cursor/commands/generate-pr-description.md`
Open PR	`.cursor/commands/create-pr.md`
Docs in-repo	`.cursor/commands/add-documentation.md`, `.cursor/commands/generate-api-docs.md`
Hardening (as needed)	`deslop`, `security-review`, `accessibility-audit`, `optimize-performance`, `add-error-handling`
Commits	`.cursor/commands/git-commit.md`

Deployment

(To be filled in: environments, promotion path, rollback, who approves production.)

Weekly rotating on-call

Each week, one engineer rotates into the on-call role for production operations and dependency maintenance.

Responsibilities

Production bugs — Any production bug that surfaces during the on-call week is the on-call person's responsibility to triage, fix, and follow through to deploy.
Dependabot issues — All open dependabot PRs are the on-call person's responsibility to review, approve, and merge (or triage if blocked).

Dependabot review guidelines

Bump type	Action
Patch bumps (e.g. `1.2.3` → `1.2.4`)	Usually safe to merge as long as there is no build failure. If CI passes without errors, approve and merge.
Minor and major bumps (e.g. `1.2.3` → `1.3.0` or `2.0.0`)	Have the LLM review the PR to check for breaking API changes, removed dependencies, or behavioural differences that could affect the codebase.
Code changes needed	Sometimes the version bump alone won't work — you may need to update imports, types, or config to match the new API. Make the necessary code changes and commit them as part of the PR.
Smoke tests	If the change touches a meaningful runtime path (e.g. a core library, an SDK used in API routes, or a build tool), run a manual smoke test before approving/merging to confirm things still work as expected. It's the on-call person's job to do this.

Code development guidelines

Always bring the feature branch up to date with the integration branch before opening or updating a PR (rebase or merge per team convention).
Prefer small, reviewable commits with clear messages (git-commit command as needed).
Prefer clear domain shapes (types, schemas, validated objects) over ad hoc primitives when the plan or scale implies structure or reuse.

Author review checklist (before adding reviewers)

Diff read end-to-end; no debug noise, dead code, or accidental files.
Planning / feature doc reflects what shipped (or ticket updated); Asana has plan PR, implementation PR, and key artifacts linked where applicable.
Tests added or updated per Testing expectations; CI green.
Manual test plan executed where applicable.
PR description: summary, testing notes, breaking changes, screenshots if UI.
Base branch is current; PR scope matches title and description.

_private/qwestly-docs/Engineering/operating-model.md