Product Engineering Workflow¶

This page defines the persistent BetterFleet workflow for governed product work.

Repo artifacts are the source of truth. Linear mirrors them for planning and delivery, and may also hold execution-only issues that stay in Linear.

Start Here¶

• Governed workflow overview: this page
• Governed delivery execution: Product Engineering Delivery
• Linear mirror rules: Product Engineering Workflow in Linear
• Manage feature-flag rollout process: GitLab Feature Flags
• Active artifact sets: Active Artifacts
• Long-lived design references: System Design
• Completed or superseded artifact sets: Archived Artifacts

Workflow Summary¶

flowchart LR
  subgraph COL1[" "]
    direction TB
    D["Discovery"]
    C["Challenge"]
    D -. produces .-> C
  end

  subgraph COL2[" "]
    direction TB
    F["Definition"]
    S["Specification"]
    T["Story Set"]
    F -. produces .-> S
    S -. shapes .-> T
  end

  subgraph COL3[" "]
    direction TB
    V["Delivery"]
    U["One Unit User Story at a Time"]
    R["Release Notes + User-Facing Docs"]
    V -. works through .-> U
    V -. updates .-> R
  end

  D --> F --> V

The workflow has three phases:

• Discovery
• Definition
• Delivery

Core Rules¶

• Governed work follows Discovery -> Definition -> Delivery.
• Discovery produces a canonical Challenge.
• Definition produces a canonical Specification and then a canonical Story Set.
• Stories in the canonical story set are unit user stories: the smallest buildable delivery slices.
• Delivery works one story at a time.
• Governed delivery should prefer small, releasable increments that can flow to users steadily rather than accumulating hidden scope behind long-lived holdbacks.
• Backport initiative, project, and story mirror references into code once they exist. Do not backport execution-only Linear issues.
• For governed work, Codex should check Challenge -> Spec -> Story before coding unless the user explicitly opts out.

Default Developer Operating Path¶

Start from one unit user story, its mirrored Linear story issue, or a smaller Linear execution issue that clearly sits inside that story.

Use these interpretation rules:

• If Linear and the repo disagree, follow the repo and fix Linear.
• The delivery boundary is one unit user story. Do not silently widen scope.
• A story mirror is only a valid pickup point if it contains the minimum context defined in the Linear guide.
• A smaller execution issue is only a valid pickup point if it clearly points back to the story mirror and canonical story.
• If that context is missing, stop and push back toward shaping.

Work in this order:

1. Pick the story or execution issue you are actually working on.
2. Confirm Challenge -> Specification -> Story.
3. Stay inside that story boundary.
4. Keep Linear and the required docs/release-note follow-through current.
5. Follow GitLab Feature Flags for stage language, rollout handling, and retirement expectations when the story uses a Manage feature flag.

Use Product Engineering Workflow in Linear for the mirror rules, execution-issue rules, and estimate guidance. Use Product Engineering Delivery for the delivery loop and done rules.

If the upstream challenge, specification, or story is missing, stop and shape first unless the user explicitly opts out of the governed path.

A governed story is only done when:

• the delivered behaviour stays inside the intended story scope
• the acceptance criteria have been checked and met
• the Linear mirror still reflects the story and its dependencies accurately enough for operational tracking
• required release notes and user-facing docs/help are updated

1. Discovery¶

Discovery frames the problem before solution design starts.

• Output: one canonical Challenge.
• Goal: make the problem, scope, and constraints explicit enough to anchor downstream work.
• Default skill: challenge-writer, with a human in the loop.

Discovery is complete when the challenge clearly defines the problem to solve and gives Definition a stable starting point.

2. Definition¶

Definition turns the challenge into buildable delivery intent.

• Output: one canonical Specification.
• Output: one canonical Story Set.
• Default skill: specification-writer, with a human in the loop.
• Default skill: story-shaper, with a human in the loop.

The specification defines the intended solution. The story set slices that solution into unit user stories.

Each story should be as small as practical. In Linear, each story maps to one flat story issue. If a story still needs multiple hours-scale delivery steps, track those as separate Linear execution issues rather than backporting them into code.

3. Delivery¶

Delivery ships one story at a time.

• Input: one story with linked canonical context.
• Confirm Challenge -> Specification -> Story before coding unless the user explicitly opts out.
• Make sure the current In Progress issue in Linear matches the work actually happening.
• Keep the Linear operational view current during delivery by following the rules in Product Engineering Workflow in Linear.
• Keep release notes and user-facing docs/help current as part of delivery, not as follow-up admin; capture the human-relevant impact of the shipped change rather than its implementation detail.
• Update the correct working release-note artifact as scope becomes ready in the product repo; for BetterFleet Manage, use bf-manage-web/docs/release-notes/working/next.public.md, bf-manage-web/docs/release-notes/working/next.internal.md, and bf-manage-web/docs/release-notes/working/holdback.md as described in the release-note guide.
• Prefer shaping and shipping slices that can move through next.public.md; use next.internal.md and holdback.md as exceptions, not the default path.
• Update relevant user-facing docs or in-app help when shipped behavior changes what users see, expect, or need to do.
• When a delivered behaviour uses a Manage feature flag, follow the GitLab feature-flag guide for stage naming, audience communication, and bounded flag retirement.

See Product Engineering Delivery for the concrete delivery loop, validation expectations, and artifact-location links used during execution.

Canonical and Mirror Model¶

• Challenge is mirrored by a Linear Initiative.
• Specification is mirrored by a Linear Project.
• Unit User Story is mirrored by one flat Linear Story issue.
• Additional hours-scale delivery steps may be tracked as separate flat Linear execution issues such as technical, spike, validation, or docs work. Those issues stay in Linear only.
• Story dependencies are mirrored as issue dependencies.
• Milestones remain about released-together customer scope.
• Cycles remain weekly planning only.

See Product Engineering Workflow in Linear for the BetterFleet-specific Linear mapping rules.