Table of Contents

Operating Model

Last updated: 7/14/25

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 the planning prompt or software-architecture skill, 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 the diagrams prompt 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 the unit-test prompt 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. Keep planning docs and feature docs in the workspace repo (docs/plan/, docs/features/) so they stay available as LLM context during development. Human-oriented engineering process and capability docs (like this one) live in the docs repo (qwestly-docs).
Optional quality passes (use when relevant): deslop prompt, error-handling prompt, security-review prompt, accessibility-audit prompt, optimize-performance prompt.
Author review (mandatory):
- Run tests and any required manual checks from the test plan.
- Run the code-review prompt against staging (or main if staging does not exist) for a structured pass.
PR — use the PR-description prompt then the create-PR prompt (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.
PR-review routing — Dominick is not the default reviewer for every PR.
- Peer-review small fixes, incremental PRs, and routine changes.
- Bring Dominick in for architecture/design plans and complex features that originated from those plans (EM signoff category — see §5).
Standard PR review loop — before approving any PR:
1. Understand the feature — read the PR description, linked planning doc, and Asana ticket so you know what the change is supposed to do.
2. Review the automated review output — check the bot's findings first; the author should have resolved red/yellow items before requesting human review.
3. Run an independent review — do your own diff pass. Do not rely solely on the automated review.
4. Resolve all findings — every red (blocking) and yellow (advisory) finding must be addressed or explicitly waived with a rationale.
5. Confirm resolution — re-review the updated diff and confirm all items are closed before approving.

Agent skills & prompts

Planning & design

Skill / prompt	What it does
Planning prompt	Write a planning/design doc before complex implementation — surfaces scope, architecture, risks, tests, and open decisions before coding.
`software-architecture`	Review a change or design doc for architectural quality; intended for bigger decisions and design plans.

Implementation & bug fixes

Skill / prompt	What it does
`qwestly-bugfix`	Take an Asana ticket ID or description, implement the fix, create a branch and bot-authored PR, and trigger automated code review. Works best with detailed tickets.
`dependabot-review`	Pull flagged dependency PRs, evaluate them, and approve or reject them.

Quality & validation

Skill / prompt	What it does
`validate-implementation`	Post-implementation quality gate — code review, architecture review when applicable, fix red/yellow issues, run tests and TypeScript checks, update docs, then report before committing.
Code-review prompt	Structured self-review pass before requesting human reviewers.
PR review workflow	Understand the feature, inspect the automated review, run an independent review prompt, resolve red/yellow issues, then re-check before approval.

Git & docs

Skill / prompt	What it does
`git-squash`	Compress a branch into one meaningful commit, generate a clean message, force-push, wait for CI, then merge.
`plan-to-feature-doc`	Convert an implemented planning doc into a durable feature doc covering architecture, data model, key files, API changes, gotchas, and deferred work.

Workspace & debugging

Skill / prompt	What it does
Workspace harness	Multi-repo workspace with background-process scripts, consolidated logs, and agent-readable architecture docs — work across repos without terminal or context-switching overhead.
Browser debugging POC	Give an agent page context such as URL, console logs, network activity, selected elements, and tokens, avoiding manual copy/paste when debugging UI.

Quality prompts (as-needed hardening)

deslop, security-review, accessibility-audit, optimize-performance, error-handling, diagrams, unit-tests, PR-description, create-PR

AI-assisted development

Model-use operating pattern

Use a stronger model for design and review, a cheaper model for implementation:

Phase	Model tier	Rationale
Upfront planning & design	Stronger (e.g. Pro, Opus)	Architecture decisions, data modeling, and tradeoff analysis benefit from deeper reasoning.
Implementation	Cheaper (e.g. Flash, Sonnet)	Code generation, tests, and boilerplate are volume work where speed and cost matter more than deep reasoning.
Final review (author + PR)	Stronger (e.g. Pro, Opus)	Catching subtle bugs, security issues, and design inconsistencies before merge justifies the higher cost.

This is a guideline, not a rule — switch tiers when the task demands it (e.g. a complex refactor during implementation may warrant the stronger model for a session).

Deployment

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

Team rhythms

Daily standup

Rotating driver — engineers take turns driving standup, sharing updates, and surfacing blockers. The driver changes each day so everyone builds the habit of running the room and keeping things moving.
Engineers-only by default — keep standup focused on technical coordination. Managers and stakeholders join only when there is a specific reason (e.g. cross-team sync, escalated blocker).
Blockers surfaced immediately — the driver is responsible for noting blockers and making sure they land in the right channel (Asana, Slack, or an ad hoc sync) before standup ends.

End-to-end area ownership

Each engineer owns a defined product area. Ownership means:

Proactive ticket creation — when you see a bug, improvement opportunity, or missing piece in your area, create and self-assign the ticket. Do not wait for someone else to assign it.
Escalate blockers — if something outside your control is blocking progress in your area, raise it immediately (standup, Slack, or direct ping).
Know your area's health — you should be able to speak to what shipped recently, what is in flight, and what needs attention next.

1:1s

Engineer's agenda — 1:1s are for the engineer's topics: unblocking, architectural decisions, growth and career development, and design review. They are not for routine status reporting.
Status lives in standup — use the daily standup for status updates.
Ad hoc syncs for urgent blockers — when a blocker cannot wait for the next 1:1, book an ad hoc sync immediately.

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