Product Engineering Delivery

This companion explains how to execute governed delivery once a unit user story is ready for pickup.

Use it with:

• Product Engineering Workflow for the overall governed workflow
• Product Engineering Workflow in Linear for the operational mirror rules

Navigation

• Start from the governed workflow: Product Engineering Workflow
• Find the canonical work artifacts for the story you are delivering: Active Artifacts
• Use long-lived domain design when a story depends on it: System Design
• Use the Linear operational rules here: Product Engineering Workflow in Linear
• Use the release-note operating guide when delivery changes release communication: Release Notes
• Use the feature-flag rollout guide when delivery uses a Manage feature flag: GitLab Feature Flags
• Move completed or superseded artifact sets to the archive path defined here: Archived Artifacts

Ready To Pick Up

Treat a story as ready for governed delivery only when:

• the work is one unit user story rather than a broad bucket of scope
• the story has explicit acceptance criteria
• the upstream canonical context can be followed in order: Challenge -> Specification -> Story
• any material dependencies or unresolved questions are visible before implementation starts

If that minimum context is missing, do not start. Push back toward the missing artifact or story detail first.

If the story still needs multiple hours-scale steps in Linear, that is fine, but the current active Linear issue must still clearly work toward that story.

Delivery Loop

Work one story at a time:

1. Start from the unit user story, its mirrored Linear story issue, or a smaller Linear execution issue that explicitly references that story.
2. Confirm the upstream Challenge -> Specification -> Story context.
3. Check whether any relevant long-lived design already exists in System Design.
4. Define the implementation approach inside the boundary of that unit user story.
5. Confirm that the current In Progress issue in Linear matches the work actually happening. If it does not, update it or switch issues before continuing.
6. Keep the Linear operational view accurate during delivery by following the rules in Product Engineering Workflow in Linear.
7. Implement the change without silently widening scope into adjacent stories.
8. Validate the changed behaviour in the relevant executable environment before calling the work complete.
9. Check the observed behaviour against the acceptance criteria for that story.
10. Capture concise review evidence: what was tested, which acceptance criteria were covered, and any notable risks or remaining gaps.
11. Prefer finishing with a slice that can move into next.public.md; if work must sit in next.internal.md or holdback.md, make the reason explicit and keep that state temporary.
12. If rollout uses a Manage feature flag, confirm the intended stage on the sysadmin page and record the retirement expectation.

Done Means

Treat a governed story as done only when:

• the implemented behaviour matches the intended scope of that unit user story
• the acceptance criteria for that story have been met
• the changed behaviour has been run and checked in the relevant executable environment
• the Linear mirror still reflects the story and its dependencies accurately enough for operational tracking, including any blocking execution-only issues that were used during delivery
• working release notes are updated in the product repo when the shipped scope should appear in release communication; for BetterFleet Manage, update the appropriate file under bf-manage-web/docs/release-notes/working/, including next.public.md, next.internal.md, and holdback.md as needed, and describe the change in human-relevant terms rather than implementation detail
• relevant user-facing docs or in-app help are updated when shipped behaviour changes what users see, expect, or need to do
• when a Manage feature flag was used, its rollout state, release-note handling, and retirement expectation still match the GitLab feature-flag guide

If the work has not been run, checked against the acceptance criteria, or clearly explained, it is not done yet.

Staging Validation

• After the MR deploys to staging, rerun the story's acceptance criteria in staging and check for regressions before treating the story as done.
• Staging validation is mandatory between the Thursday cut-off and the following Tuesday production release; production deployment must not proceed until this validation passes.
• When staging validation passes, add the GitLab label Validated in Staging to the MR. If staging validation fails or is incomplete, do not add the label; fix and recheck first.
• Use the prefilled GitLab view to find merged staging MRs missing the label: Staging validation MR view.
• Tip: in that view you can filter by Author for your name and bulk-edit labels when it saves time.

Add label	Filter by author	Bulk label edit

Artifact Locations

• Active governed artifact sets live under docs/artifacts/active/
• Completed or superseded artifact sets move to docs/artifacts/archived/
• Long-lived cross-project design belongs under docs/system-design/
• Workflow rules live under docs/process/
• Product release-note artifacts live in the product repo under docs/release-notes/; the first concrete implementation is bf-manage-web/docs/release-notes/

When an artifact set moves from active to archived, move the slug folder and update the relevant active and archived index pages so the navigation path stays intact.