handbook: GitHub workflow and ABCD

drafts/github-workflow-v1.md

@@ -0,0 +1,55 @@
+---
+title: 'GitHub workflow'
+sidebar:
+  label: GitHub workflow
+  order: 7
+updatedDate: May 7, 2026
+authors: drew
+meta:
+  title: 'GitHub Workflow - Datum Handbook'
+  description: 'How we use GitHub as a team — issues, PRs, code review, and keeping up. With a good agent, the hygiene takes care of itself.'
+  og:
+    title: 'GitHub workflow'
+---
+
+GitHub is where the work happens and where it gets recorded. A good issue makes the work legible before a line of code is written. A good PR description makes the reviewer's job easier and the git log useful months later. A good code review makes the software better and the author stronger.
+
+The overhead of doing all that well is real, and it compounds. An AI agent is a genuinely useful partner here — not for the thinking, but for the mechanics: finding what needs attention, drafting the boilerplate, surfacing the right context. Keep one close.
+
+## Issues
+
+Every piece of work starts with a GitHub issue. This is where intent lives. Even a quick configuration change or a one-line fix should have a trail — that trail is what lets someone else pick it up, or lets you reconstruct why it happened three months later.
+
+A good issue states the problem before it proposes the solution. It links to related issues, prior discussions, or relevant context. It doesn't have to be long, but it should be complete enough that someone who didn't write it can act on it.
+
+When the queue is long and ambiguous, ask your agent: _"Look at the open issues in datum-cloud that have no assignee and no recent activity — which 3 are clearest to pick up right now given [your current context]?"_ A few minutes of triage with an agent every week keeps the backlog from becoming opaque.
+
+## Pull requests
+
+A pull request is a proposal. The description is your chance to explain not just what changed, but why, and what the reviewer should pay attention to. A description that just says "fixes the bug" is a tax on the reviewer.
+
+Keep PRs small and focused. A PR that does one thing is easier to review, easier to revert, and easier to understand in the future. If you find yourself writing "also" in a PR description more than once, consider splitting it.
+
+Agents are good at drafting descriptions. Paste in your diff and the linked issue and ask: _"Write a PR description that explains what changed, why, and what a reviewer should look for."_ Edit it — don't just post the output — but the draft handles the blank-page problem and usually surfaces context you would have left out.
+
+## Code review
+
+Code review is where quality is made, not just checked. It's also where culture is expressed. A review that asks questions instead of just demanding changes, that explains reasoning instead of just asserting it, builds trust. A review that comes back quickly respects the author's momentum.
+
+As an author: give your reviewer what they need. Link the issue. Explain the approach. Call out the parts you're uncertain about. The PR description is the brief; the review is the conversation.
+
+As a reviewer: say what you mean. A comment that isn't blocking should say so. A comment that is blocking should say why. Approval means you've actually looked — it's not a social courtesy.
+
+The review queue is easy to lose track of. Take a couple hours in your week, hand it to your agent, and ask: _"Find all the open PRs across datum-cloud and milo-os that need a reviewer — tell me the 3 highest value ones I can review right now."_ Your agent can weigh factors like staleness, author, blast radius, and how much is already in your head from related work. You'll often find you can make a real dent in an hour.
+
+## Milestones and releases
+
+We ship on a [monthly release cadence](/handbook/operate/rhythms/). Milestones are how we organize that. If work is scoped for the current release, it should be on the milestone. If it slips, move it or close it — a milestone that's 60% done at release time tells the team nothing.
+
+After a release, a quick agent pass is useful: _"What merged PRs in datum-cloud since [last release date] don't have a linked issue or milestone? Give me a list."_ That usually catches the loose threads worth cleaning up before the next cycle.
+
+## Keeping up
+
+GitHub hygiene erodes silently. Issues go stale, PRs pile up, reviews get delayed by distraction rather than judgment. The fix isn't discipline — it's reducing the activation energy.
+
+Build a habit of starting a few sessions per week by asking your agent to give you the lay of the land: what's open, what's blocked, what's been quiet too long. Let it do the scanning so you can do the deciding. The work doesn't pile up; it just needs a few minutes of triage to stay manageable.

src/content/handbook/build/github-workflow.md

@@ -0,0 +1,101 @@
+---
+title: "GitHub workflow"
+sidebar:
+  label: GitHub workflow
+  order: 7
+updatedDate: May 7, 2026
+authors: drew
+meta:
+  title: "GitHub Workflow - Datum Handbook"
+  description: "How we use GitHub at Datum — standards and procedures for issues, branches, pull requests, and code review so engineers spend their energy on the work, not the process."
+  og:
+    title: "GitHub workflow"
+---
+
+This page covers how we use GitHub day-to-day — not what GitHub is, but how we work in it. Having shared standards means engineers spend less time deciding how to do something and more time doing it. It also means our work is legible to teammates who pick it up mid-stream, and to our future selves.
+
+One principle that runs through all of it: [ABCD — Always Be Connecting Dots](https://www.threestacksfull.com/thinking/abcd-always-be-connecting-dots). GitHub is where work gets recorded, but the people doing the recording are in a position to make connections that no agent can — between this PR and that customer conversation, between this architecture decision and something the platform team is quietly changing. The practices below are designed to make space for that.
+
+## Issues
+
+Every piece of work starts with a GitHub issue — including small changes. The issue is the trail: the reasoning, the constraints, the decisions made and discarded. Without it, someone (probably you, six months from now) has to reconstruct context from git blame and Slack history.
+
+**Writing a good issue:**
+- State the problem before proposing the solution
+- Note the constraints and assumptions you're working with
+- Link to related issues, prior discussions, or relevant context
+- Explicitly note non-goals if scope is likely to creep
+
+Before you start implementing, ask: *who else would have an opinion if they knew about this?* If the answer is anyone outside your immediate work, loop them into the issue before the PR. That's the cheapest time to surface a conflict.
+
+Agents are useful here for drafting, researching prior art, and finding related work across the org. Use them freely for that. The judgment call — whether the framing is right, whether the right people know about it — is yours.
+
+## Branches
+
+Branch from `main`. Name branches in the format `type/short-description`, using the same types as [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat/` — new functionality
+- `fix/` — bug fixes
+- `docs/` — documentation only
+- `chore/` — maintenance, dependency bumps, config changes
+- `refactor/` — code changes with no behavior change
+
+Keep branch names lowercase and hyphenated. Short is better than complete: `feat/oauth-pkce` not `feat/add-pkce-support-to-oauth-login-flow`.
+
+## Commits
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) standard for commit messages: `type(scope): description`. The same types apply as above. Scope is optional but helpful when the repo covers multiple areas.
+
+```
+feat(auth): add PKCE support to OAuth login flow
+fix(billing): correct proration calculation on mid-cycle upgrades
+docs(api): add rate limiting section to reference
+```
+
+A good commit message completes the sentence "if applied, this commit will…" Keep the description under 72 characters. Use the commit body for the *why* if it isn't obvious from the diff.
+
+## Pull requests
+
+A PR is a proposal, not just a delivery. The description is how you make your reasoning legible to reviewers — what changed, why, and what you assumed when you made those choices. A description that only restates the diff is a tax on everyone who reads it.
+
+**What a PR description should include:**
+- What problem this solves (link the issue — don't restate it)
+- Why you approached it this way, especially if alternatives exist
+- What a reviewer should pay close attention to
+- Any assumptions that haven't been validated yet
+
+Keep PRs small and focused. If you find yourself writing "also" more than once in a description, consider whether it's two PRs. Smaller PRs get faster, better reviews and are easier to revert if something goes wrong.
+
+Use [draft PRs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) when you want early feedback or are working something out in the open. Mark ready for review only when you'd be comfortable merging it.
+
+Agents are effective at drafting PR descriptions from a diff and a linked issue. Use them to get past the blank page, then edit for anything the description doesn't capture about your actual reasoning.
+
+## Code review
+
+Require at least one approval before merging. For changes with a large blast radius — anything touching auth, billing, public APIs, or shared infrastructure — get two.
+
+**As an author:**
+- Don't assign reviewers until the PR is genuinely ready
+- Respond to all comments before merging, even if just to acknowledge and defer
+- If a review conversation is going in circles, move it to a call and summarize the outcome in the PR
+
+**As a reviewer:**
+- Mark comments clearly: blocking (must be addressed before merge) or non-blocking (suggestion, take it or leave it)
+- Approval means you've actually read it — not a social courtesy
+- If you need more than a day to review, say so; don't leave a PR waiting silently
+
+The code will likely be fine — agents can check correctness and catch edge cases faster than a human skimming a diff. What you're looking for as a human reviewer is what the author couldn't have seen alone: a connection to work happening elsewhere, an assumption that conflicts with a recent decision, a scope question that should involve someone outside engineering. Those are the comments worth writing. Ask your agent to surface the queue: *"Find all open PRs across datum-cloud and milo-os that need a reviewer — what are the 3 highest value ones for me right now?"* Then spend your time on the conversation.
+
+## Merging
+
+The PR author merges, once approved. Don't merge someone else's PR unless they've asked you to.
+
+Squash merge by default for feature branches to keep `main` history readable. Merge commits are fine for long-running branches where the individual commit history is meaningful.
+
+Delete the branch after merging. If the work is incomplete and the branch needs to live, leave a comment explaining why.
+
+## Milestones
+
+We ship on a [monthly release cadence](/handbook/operate/rhythms/) — everything bundles to the last Friday of the month. If work is scoped for the current release, it should be on the milestone. If it slips, move it explicitly; don't let milestones quietly go incomplete.
+
+When closing out a milestone, check whether anything that merged needs a changelog entry, a demo, or a heads-up to someone outside engineering. That last step is the one most likely to get skipped — and it's the one that makes shipped work actually land.

src/content/handbook/build/sdlc.md

@@ -0,0 +1,71 @@
+---
+title: "How we ship"
+sidebar:
+  label: How we ship
+  order: 1
+updatedDate: May 7, 2026
+authors: drew
+meta:
+  title: "How We Ship - Datum Handbook"
+  description: "The arc from idea to production — how work moves through our SDLC and what questions humans need to answer at each stage."
+  og:
+    title: "How we ship"
+---
+
+We ship software continuously, but deliberately. Agents handle a lot of the throughput — writing, reviewing, scanning. What the process below is designed for is the human judgment at each stage: is this the right problem? Are the assumptions sound? Does everyone who needs to know, know? Those questions don't answer themselves, and no amount of velocity compensates for skipping them.
+
+## From idea to issue
+
+Work starts as a hypothesis. Before an issue becomes a task, it should be able to answer: what problem are we solving, for whom, and why now? The discussion that happens in an issue before a line of code is written is often the most valuable part of the project. It's where assumptions get challenged, connections get made, and the scope gets honest.
+
+An agent can draft the issue, research prior art, and find related work. The human job is to pressure-test the framing. See [GitHub workflow](/handbook/build/github-workflow/).
+
+## From issue to pull request
+
+Once scope is clear, implementation begins on a branch. A pull request is the proposal that implementation makes to the team — not just the code, but the reasoning behind it. A good PR description makes the author's assumptions legible so a reviewer has something real to engage with, not just a diff to skim.
+
+Review is where humans add what agents can't: the cross-functional connection, the surfaced assumption, the decision hiding inside an implementation detail. See [GitHub workflow](/handbook/build/github-workflow/).
+
+## The definition of done
+
+Before work is considered finished, the team should be able to say yes to a specific set of questions: Is the problem statement clear? Is it deployed with no manual steps remaining? Has someone tested it from the user's perspective? Is it documented well enough that a user could discover and use it without asking anyone?
+
+These aren't gates — they're a shared picture of what "finished" means. Not every item applies to every project, but every item should be explicitly considered, not skipped by accident. See [Definition of done](/handbook/operate/project-management/).
+
+## The monthly release
+
+We ship to production continuously, but we bundle work into monthly releases that culminate on the last Friday of each month. That rhythm creates the forcing functions that pure continuous delivery skips: milestone grooming, documentation, demos, communications, and changelog entries. It's when the work gets announced — not just deployed.
+
+Milestones are how we organize the bundle. If work slips out of a milestone, move it explicitly rather than letting the milestone quietly drift. See [Rhythms](/handbook/operate/rhythms/).
+
+## Into production
+
+Substantial changes — anything with real blast radius — are [calendar events](/handbook/build/change/), not chat messages. The team knows a change is coming before it arrives. That shared awareness is itself a diagnostic tool: when something breaks, the first question is always "what changed?" and a calendar entry shortens that conversation to zero.
+
+For new services or significant capability expansions, a [production readiness review](/handbook/build/production-readiness/) is the checkpoint that validates the operational foundations are in place before customers depend on them.
+
+## Engineering cadence
+
+The sections above describe how individual pieces of work move from idea to production. This section is about the recurring habits that keep things moving — what to do every day, week, and month regardless of what you're building.
+
+These aren't all-or-nothing. When you're [on call](/handbook/build/oncall/), the daily and weekly habits shift toward triage and responsiveness. When you're heads-down on a complex piece of work, they shrink to the minimum needed to stay connected. The goal is sustainable rhythm, not a checklist to feel guilty about.
+
+### Daily
+
+- **Process notifications.** GitHub mentions, PR review requests, and discussion replies are your primary async input. Clear them once a day so nothing waits more than 24 hours.
+- **Move your current work forward.** At least one meaningful commit or decision on your active milestone issue. It keeps momentum and makes the weekly status update honest.
+- **Check your open PRs.** If a PR is waiting on you — or waiting on someone else and going stale — take an action: respond, ping, merge, or close.
+
+### Weekly
+
+- **Write a status update** on any in-flight issues. Two things: when it's expected to ship, and what's in the way. See [Status updates](/handbook/operate/status/).
+- **Review your issue assignments.** Are they still accurate? Still the right priority? Close what's resolved, update what's changed, flag what's blocked.
+- **Scan the PR review queue.** Ask your agent: _"Find all open PRs across datum-cloud and milo-os that need a reviewer — what are the 3 highest value ones for me right now?"_ A couple of focused hours on reviews is one of the highest-leverage things you can do for the team.
+- **Connect one dot.** What did you learn this week — in a PR, a customer issue, a Slack thread — that someone else should know about? Put it where they'll find it: a comment on the relevant issue, a note in a PR description, a mention in the Monday all-hands.
+
+### Monthly
+
+- **Close out the milestone.** Before the last-Friday release, confirm that everything that shipped has a changelog entry, is documented, and has been socialized in some form. Work that shipped but isn't discoverable isn't done. See [Definition of done](/handbook/operate/project-management/).
+- **Read the on-call summary.** Review the end-of-shift notes from the cycle. What issues came in? What got deferred? Anything that bounced around the queue without resolution usually points at a gap worth fixing.
+- **Tend the backlog.** A monthly pass through your open issues: close what's stale, reprioritize what's shifted, and break down anything that's been sitting in a vague state for more than a cycle.
+- **Attend the community huddle.** It's where engineering work meets the public. If you shipped something worth showing, bring it.