docs/development-process.md

Development process

How we go from idea → spec → PR → review → ship at studyflash. Inspired by PH's process but adapted to a 5-person team.

draftrajivprocessengineering

Status: draft scaffold. Inspired by PH's development process handbook but we have a very different shape — small team, no PMs, founder-engineering. Rewrite from first principles, don't copy.

What we keep from PH

TODO. Candidates:

  • Small PRs, frequent merges, feature flags for risky changes.
  • Default-to-shipping bias.
  • Public-by-default knowledge (this handbook surface).
  • "Sprints" are just calendar weeks, not Jira ceremony.

What we explicitly reject from PH

TODO. Probably:

  • Multi-team coordination overhead.
  • RFC process for every change — too heavy for 5 people.
  • Quarterly OKR ritual.

Our actual flow (to be defined)

TODO. Sketch the shape we want:

Idea capture

  • Where: Linear backlog, "Brain dump" doc, Slack #engineering, this handbook (research write-ups at internal/docs/content/).
  • Promotion: idea → Linear ticket when scoped.

Spec / planning

  • Default: ticket description + one comment for design notes.
  • Threshold for a write-up: TODO (e.g. anything touching >2 apps, anything user-facing with UX implications).
  • Where write-ups live: internal/docs/content/ (research surface).

Build

  • Branch naming: TODO.
  • PR size guidance: TODO (PH says <500 LoC — what's ours?).
  • Feature flags: when required.
  • Preview environments: PR-triggered Hetzner preview VM (see infra/learning-api/preview-vm.ts).

Review

  • Reviewer assignment: TODO.
  • Turnaround SLA: TODO.
  • When to request a second reviewer.
  • /ultrareview as a tool (multi-agent review on the branch).

Ship

  • Merge gate: green CI, one approval, no open conversations.
  • Auto-deploy or manual.
  • Customer comms — when does a feature warrant changelog / in-app notice.

Post-ship

  • Watching telemetry for X hours.
  • Rollback procedure.
  • When a regression becomes a postmortem.

Cadences

TODO.

  • Standup? (Probably no.)
  • Weekly demo / show-and-tell?
  • Retro?
  • Planning session?

Open questions

  • Do we want a lightweight RFC convention for cross-cutting changes? What's the threshold?
  • How do we keep this doc current as the team grows from 5 → 10?