Product Engineering Workflow in Linear

This page describes BetterFleet's use of Linear for the product engineering workflow.

Repo artifacts are canonical. Linear mirrors them for planning and delivery, and may also hold execution-only issues that are not backported into code.

Use it with:

• Product Engineering Workflow for the governed workflow overview
• Product Engineering Delivery for the delivery execution loop and done rules
• Active Artifacts for the canonical work artifacts that Linear mirrors
• System Design for long-lived design references that may shape delivery

Core Mapping

• Initiative -> Challenge
  • One governed challenge maps to one Linear initiative.
• Project -> Specification
  • One governed specification maps to one Linear project.
• Story issue -> Unit User Story
  • Each canonical unit user story is mirrored as one flat Linear story issue under the project.
  • Story dependencies are mirrored as issue dependencies.
• Execution Issue -> hours-scale delivery step
  • Use these for technical, spike, validation, or docs work inside one canonical story.
  • They stay in Linear only.
  • They should usually be the active In Progress item when a story still needs multiple focused delivery steps.
• Milestone -> released-together customer scope
  • A milestone groups scope that releases together.
  • If it is being used for planned delivery, it should carry a target date.
• Cycle -> weekly planning
  • A cycle is for weekly planning only.

Operating Principles

• If Linear and the repo disagree, follow the repo and fix Linear.
• Backport only initiative, project, and story mirror references into code.
• Placeholders in Linear are allowed, but they are not ready for governed delivery.
• Do not code from a broad placeholder or wrongly shaped item. Shape it first.
• During delivery, the hard control point is simple: the current In Progress issue must match the work actually happening.

When To Mirror

• Initiative after the challenge exists.
• Project after the specification exists.
• Story issue after the story exists.
• Execution issue only when a story still needs separate hours-scale steps.
• If the canonical artifact changes materially, update the Linear mirror.

Traceability Back Into Code

• Do not rely on title matching alone.
• Backport mirror references into code once they exist.
• Use linear_ref in frontmatter for challenge, specification, and release-plan artifacts.
• Record the mirrored story issue close to the story in the story file.
• If a mirror is planned but not created yet, leave TBD.
• Execution-only issues stay in Linear only.

Linear-First Intake

Linear can be used for placeholder intake before the governed artifacts exist, but that state must be explicit.

• Say that it is a placeholder.
• Say what is missing next: challenge, specification, story, or triage decision.
• Include the best-known owner for shaping the next step.
• Do not treat it as ready for delivery or move it to In Progress.

Use these conversion rules:

• If the item describes a problem, opportunity, or customer outcome space, shape it as a Challenge and mirror it as an initiative.
• If the item describes a solution-sized body of work or multiple stories, shape it as a Specification and mirror it as a project.
• If the item describes one narrow buildable slice with acceptance criteria, shape it as a Unit User Story and mirror it as a story issue.
• If the item is a bug without governed project context yet, route it through IPT triage instead of forcing it into a governed project.

If a placeholder is ahead of the canonical artifacts, create or prompt for the missing artifact instead of improvising delivery scope from the placeholder.

Required Fields By Artifact

Initiatives

• Governed initiatives should link to the canonical challenge.
• Initiative ownership should reflect the owning team for the governed work.
• If an initiative is still placeholder-only, it should say that explicitly and identify the missing challenge work.

Projects

• Governed projects should link to the canonical specification.
• Team ownership lives on the project for governed work.
• A governed project should have a lead assigned.
• A project in In Progress must have both a start date and a target date.
• A project that is active should have a status update added at least every two days, or sooner if state, risk, timing, or scope changes.
• A project that is not yet started may omit dates, but adding expected dates early is preferred for planning.
• If a project exists only as a rough thought, park it as a placeholder and make the missing specification work explicit.

Milestones

• A milestone should be used only when a released-together customer scope is being tracked.
• Where a milestone is being used for planned delivery, it should have the relevant target date set.
• If a milestone is only a rough placeholder and no meaningful target timing exists yet, avoid inventing precision; either leave it out until the timing is real or keep the placeholder status explicit.

Issues

Story issues

• Each governed story issue should include the user story statement, acceptance criteria, material dependencies when delivery order matters, and links back to the canonical specification and challenge.
• For governed mirrored work, copy the canonical User Story and Acceptance Criteria into the Linear story issue unless there is a documented reason not to.
• Each governed story issue should carry the Story label under the Kind label group.
• Story issues should record any active execution-only issues in Linear through issue relations or a short execution-issue list in the story issue body.
• A story issue may still need multiple delivery steps, but it must still map to one canonical unit user story.

Execution-only issues

• Execution-only issues exist only in Linear. They are not recorded in canonical repo artifacts.
• Each execution-only issue should carry exactly one issue-type label from:
  • technical under Kind
  • spike under Kind
  • validation under Kind
  • docs under Kind
• Each execution-only issue should include a short Story Ref note pointing to the canonical story path or ID and the mirrored story issue ID.
• Use blockedBy when the execution-only issue must finish before the story can be completed.
• Use relatedTo for supporting work that should stay visible but is not a completion blocker.
• Execution-only issues should be narrow enough to represent one hours-scale delivery step rather than a long-running umbrella.
• Individual execution-only issues should normally be assigned to the person doing the current step.
• Estimates remain advisory for execution-only issues. Use them as a split signal, not as the main gate.
• If an execution-only issue grows beyond one focused delivery step, split it or push the broader scope back into shaping.

Estimate Calibration

BetterFleet uses Linear's T-shirt estimates with these values:

• XS = 1
• S = 2
• M = 3
• L = 5
• XL = 8

Use estimates as a planning aid, not as a claim about elapsed calendar time and not as the main shape gate.

Calibrate by delivery shape and expected focused effort:

• XS: a very narrow, tightly bounded change
• S: a clean small slice, often one self-contained change with light cross-checking
• M: a straightforward multi-file or multi-surface change, often about a day of focused work
• L: a broader story or shaping slice with meaningful cross-artifact coordination
• XL: use sparingly; prefer splitting before assigning XL

Calibration rules:

• Estimate the intended shape of the issue, not elapsed calendar time.
• If a body of work contains multiple independently shippable slices, split it instead of inflating the estimate. Use story-shaper for story reshaping and execution-only issues for smaller operational steps preceding a story.
• If a broad shaping umbrella is kept intentionally broad, document that exception explicitly.
• Reuse recently completed issues as anchors when estimating similar work.

Readiness Rules

Treat a Linear story issue as ready for governed pickup only when:

• it maps to one unit user story
• it links back to the canonical story context through the repo artifacts
• it includes acceptance criteria or equivalent story-level completion rules
• material dependencies or blockers are visible
• it has an estimate if it is in the current cycle or In Progress

If that minimum is missing, the work is not ready for governed delivery yet.

Treat a Linear execution-only issue as ready to become the active work item only when:

• it points back to one canonical story and one mirrored story issue
• it is clearly one hours-scale delivery step rather than a broad umbrella
• it has enough scope detail that the assignee can tell what is being done and when it is finished
• any relevant blockers or dependencies are visible
• it has the correct issue-type label

Treat a Linear project as ready for active delivery tracking only when:

• it maps to one canonical specification
• it has the owning team set
• it has a lead assigned
• it has a start date and target date once it is In Progress
• if it is already active, its status updates are being kept current at least every two days, or sooner when state, risk, timing, or scope changes
• the issues under it are being shaped as unit user stories rather than broad buckets

Treat a milestone as ready for operational release tracking only when:

• it represents one real released-together customer scope
• it has a relevant target date when timing is being planned or communicated

Cycles

• A cycle is a weekly planning container, not a release boundary.
• The current cycle must be populated by the start of each week.
• Only work that is intended for that week should be in the cycle.
• Issues in the current cycle should already be shaped enough to be actionable.
• Story issues may sit in the cycle for planning visibility even when the actual day-to-day work will happen through execution-only issues.
• The active In Progress issue should still be one clearly bounded execution step unless the story issue itself is already that small.
• If a placeholder or obviously wrong-shaped item is sitting in the current cycle at the start of the week, shape it immediately or remove it.
• Do not use the cycle as a backlog bucket or parking lot.

Agent And Developer Expectations

• When working from Linear, confirm the canonical chain in order: Challenge -> Specification -> Story.
• If a Linear item is missing the governed artifacts, prompt toward the missing upstream artifact instead of broad implementation.
• If a placeholder issue is really a project, say so and push it upward into specification shaping.
• If a governed story issue is missing an estimate, add one using this calibration rather than leaving it blank for later.
• If a governed Linear mirror exists but the repo artifact is missing the backported Linear reference, treat that as a traceability gap and fix it.
• If a project is In Progress without dates, treat that as a planning gap and fix it.
• If a project is missing a lead, treat that as a planning gap and fix it.
• If an active project has gone more than two days without a status update, treat that as a visibility gap and fix it unless the project is effectively paused.
• If a milestone is being used for planned delivery without a relevant target date, treat that as a planning gap and fix it.
• If an issue is In Progress without an assignee, treat that as a planning gap and fix it.
• If the current In Progress issue does not match the work actually happening, correct it immediately.
• If a canonical repo artifact changes, update the Linear mirror so the operational view stays trustworthy.
• Cross-team delivery should still keep one clear owning team and use issue dependencies instead of ambiguous shared ownership.

Governed Delivery Status Handling

• These rules apply when a governed unit user story is being delivered from its mirrored story issue or from a smaller execution-only issue inside that story.
• Do not move a placeholder, not-ready, or wrongly shaped item into In Progress.
• Once governed delivery is actually starting from a ready item, move the active issue to In Progress and assign it to the person doing that implementation step.
• When delivery is underway, aim to keep at least one clear In Progress issue that matches the work actually happening. More than one can be valid in special circumstances, but having none should usually be treated as a signal to correct the operational view or clarify whether delivery is actually paused.
• If a story still needs multiple delivery steps, prefer moving the execution-only issue to In Progress rather than the broader story issue.
• If the current assignee is someone else but the work is being handed over cleanly, reassign the issue to the person doing the current step rather than leaving ambiguous ownership.
• If the issue cannot yet be assigned confidently, stop and clarify ownership instead of starting delivery with no assignee.
• Keep the Linear mirror accurate during delivery if scope, dependencies, blockers, linked canonical references, or the identity of the current active issue change.

Before proposing that implementation work is complete, check all of the following:

• the changed behaviour has been run in the relevant executable environment
• the observed behaviour matches the unit user story and its acceptance criteria
• concise review evidence is available for what was tested, which acceptance criteria were covered, and any notable gaps or risks
• the Linear mirror still reflects the current story scope, dependencies, and any blocking execution-only issues accurately
• any required release-note and user-facing documentation follow-through has been handled

Status proposal after that completion check:

• If the completion check fails, do not propose Done or In Review; keep the issue in its active state and call out the remaining gaps explicitly.
• If the completion check passes and the work is being handed over through a merge request, propose moving the issue to In Review.
• If the completion check passes and no merge request or review handoff is pending, propose moving the issue to Done.
• Prefer proposing the terminal state change in the final handoff unless the user explicitly asked Codex to apply the Linear update directly.

Useful BetterFleet workflow helpers when shaping missing artifacts:

• challenge-writer for problem framing
• specification-writer for solution definition
• story-shaper for converting scoped work into unit user stories

Standardized Labels

• Use the existing Kind label group for governed issue type.
• Standardized values in that group are:
  • Story
  • technical
  • spike
  • validation
  • docs

Out Of Scope

• This page does not replace a full Linear user guide. It defines BetterFleet's operating rules for using Linear as the mirror of the canonical repo workflow.