Product Engineering Workflow Deliverables (Unit User Stories)

Context Summary

• Product area: BFDev product engineering workflow.
• Scope basis: docs/work/archived/code-canonical-orchestration/spec.md.
• Story rule: each story in this artifact is a Unit User Story (UUS), meaning the narrowest buildable slice for this initiative.
• Linear mirror rule: each UUS should map to one Linear issue that contains the user story statement, acceptance criteria, material dependencies, and links back to the canonical challenge and specification.
• Milestone note: this internal workflow simplification does not define its own milestone plan; milestone rules in the specification apply to normal product projects.

Core Artifact Chain

Rewrite the canonical challenge around the three-phase workflow

User Story

As a workflow owner, I want the canonical challenge rewritten around Discovery, Definition, and Delivery so that the problem framing matches the workflow we intend to govern.

Acceptance Criteria

• The challenge describes the workflow as Discovery, Definition, and Delivery.
• The challenge states that repo artifacts are canonical and Linear is a mirror.
• The challenge states that delivery starts from a narrow story and keeps release-note work current.

Dependencies

• None.

Rewrite the canonical specification around the three-phase workflow

User Story

As an Engineering Lead (DRI) handling Definition, I want the canonical specification rewritten around Discovery, Definition, and Delivery so that the workflow, mirror model, and governance rules are explicit.

Acceptance Criteria

• The specification defines the canonical output of each workflow phase.
• The specification defines the Linear mirror at the summary level only.
• The specification makes release notes and relevant user-facing docs part of delivery.
• The specification defines the persistent process doc as part of putting the workflow in place.

Dependencies

• Rewrite the canonical challenge around the three-phase workflow

Replace the broad story artifact with unit user stories

User Story

As a workflow owner, I want the canonical story artifact rewritten as unit user stories so that delivery starts from the narrowest buildable slices instead of broad work buckets.

Acceptance Criteria

• The canonical story set is made of unit user stories, not broad categories.
• Each story has a concrete user story statement, acceptance criteria, and material dependencies when needed.
• The stories are narrow enough to mirror one-for-one into Linear issues for direct developer pickup.

Dependencies

• Rewrite the canonical specification around the three-phase workflow

Delivery Docs in Code

Define the release-notes operating model in the workflow spec

Linear issue: IPT-106 Exception note: This story is intentionally broader as a shaping umbrella for the release-note operating model. It is an explicit exception to the default unit-story rule for this initiative and does not change the normal governed delivery shape.

User Story

As a release stakeholder, I want BetterFleet release notes kept current as product artifacts throughout delivery so release communication is accurate when a milestone ships and release history is available in the app.

Acceptance Criteria

• The canonical workflow spec defines release notes as product-repo artifacts in code, not only as a delivery reminder.
• The model defines one published release-note file per release and one working unreleased file for current changes.
• The unreleased file is sectioned into Public, Beta, and Internal content, and each visibility section uses changelog-style subsections such as Added, Changed, and Fixed so current scope is easy to scan.
• Internal unreleased entries are also grouped by feature flag within those change-type subsections so rollout status remains explicit and checkable.
• Every relevant MR must explicitly check whether release notes need updating.
• Every completed relevant story must add or revise the unreleased note so that, if the product shipped at that point, the current releasable scope is already accurately described.
• Weekly release creation promotes the unreleased Public and Beta content into that release's published note and leaves Internal-only content behind in unreleased.
• Published release notes show beta-visible scope in a distinct Beta section and exclude internal-only scope.
• Historical release notes are migrated from ClickUp into the code-native release-note files.
• The release-note files are intended to be viewable in the app through a surface parallel to the existing help/user-guide experience.

Dependencies

• Rewrite the canonical specification around the three-phase workflow
• INF-4 follows this shaping work to adapt release-note automation to the new artifacts.

Split Signals

• Split the in-app release-note surface into its own delivery story once the artifact model is locked.
• Split historical release-note migration out into a dedicated delivery story once the target file structure is agreed.
• Split release-note promotion or automation tooling into a dedicated downstream story rather than coupling it to the shaping work.

Persistent Workflow Docs

Publish the persistent product engineering workflow doc

User Story

As a workflow or docs maintainer, I want docs/process/product-engineering-workflow.md to carry the persistent workflow and define the default developer operating path for governed work so the process lives in its intended long-term home and developers can tell what to do without reconstructing the workflow from scattered context.

Acceptance Criteria

• docs/process/product-engineering-workflow.md states the three workflow phases.
• The doc states that stories are unit user stories.
• The doc states that mirrored Linear issues must be self-contained enough for direct developer pickup.
• The doc makes the default developer starting point explicit: pick up one unit user story or its mirrored Linear issue, confirm the upstream Challenge -> Specification -> Story context, then begin delivery from that narrow slice.
• The doc makes the developer-facing delivery obligations explicit enough that a developer can see, in one place, that delivery also keeps unreleased release notes and relevant user-facing docs current when shipped behavior changes what users see, expect, or need to do.
• The doc is explicit enough that a new team member, or Codex working without unwritten team context, can follow the default governed path and understand what to pick up, what upstream context to confirm, what delivery boundary applies, and what still counts as part of done.

Dependencies

• Rewrite the canonical specification around the three-phase workflow
• Replace the broad story artifact with unit user stories

Expose the workflow from BFDev docs surfaces

User Story

As a workflow or docs maintainer, I want the persistent workflow doc linked from the BFDev docs surfaces that matter so people can find it without relying on project-only context.

Acceptance Criteria

• The relevant BFDev workflow/process docs link to the persistent product engineering workflow doc.
• The relevant BFDev workflow/process docs link to the Linear mapping note where appropriate.
• The linked docs do not contradict the canonical challenge, specification, or story set.

Dependencies

• Publish the persistent product engineering workflow doc

Add workflow discovery and search entry points

User Story

As a developer or workflow maintainer, I want the BFDev docs surfaces to expose useful discovery and search entry points for the workflow so the canonical guidance is easy to find during day-to-day work.

Acceptance Criteria

• A relevant BFDev docs surface exposes a discoverable entry point to the workflow guidance.
• The entry point helps a user find the persistent workflow doc rather than bypassing it with stale summary text.
• The change does not create a second source of truth for the workflow.

Dependencies

• Expose the workflow from BFDev docs surfaces

Publish BFDev docs to the support microsite private section

Linear issue: IPT-104

User Story

As a BFDev docs maintainer, I want the docs/ tree published to the support microsite private section so internal users can view the canonical docs.

Acceptance Criteria

• The support microsite private section serves content from the BFDev docs/ tree.
• An internal user can navigate to the published Product Engineering Workflow page from the support microsite private section.
• The published content reflects the repo docs/ tree as the canonical source rather than a copied second source of truth.
• The publishing path, sync mechanism, or operational ownership is documented clearly enough that maintainers can keep the microsite publication working.
• docs/process/publishing/index.md describes the actual publication behaviour and ownership, not only the intended rule.

Dependencies

• Publish the persistent product engineering workflow doc
• Expose the workflow from BFDev docs surfaces

Align BFDev support records with the canonical workflow docs

User Story

As a workflow maintainer, I want supporting BFDev records that materially help explain or maintain the workflow aligned to the canonical docs so adjacent guidance does not drift.

Acceptance Criteria

• Supporting BFDev records that materially help maintain or explain the workflow point back to the canonical docs.
• Supporting BFDev records do not restate stale workflow guidance that conflicts with the canonical docs.
• The alignment work stays scoped to records that actually help humans find or maintain the workflow.

Dependencies

• Expose the workflow from BFDev docs surfaces

Linear Mirror and Governance

Document BetterFleet's Linear mapping rules

User Story

As a delivery stakeholder, I want BetterFleet's Linear mapping rules documented so operational planning mirrors the canonical artifacts without replacing them.

Acceptance Criteria

• The Linear mapping doc defines Initiative -> Challenge, Project -> Specification, and Issue -> Unit User Story.
• The Linear mapping doc states that each mirrored Linear issue includes the user story statement, acceptance criteria, material dependencies when needed, and links back to the canonical challenge and specification.
• The Linear mapping doc defines milestone and cycle usage and the project-less bug flow through IPT triage.

Dependencies

• Rewrite the canonical specification around the three-phase workflow
• Publish the persistent product engineering workflow doc

Add Codex governance guardrails to repo instructions

User Story

As a developer using Codex, I want the repo instructions to check the canonical artifact chain before coding so governed project work starts from the right context.

Acceptance Criteria

• AGENTS.md states the default order Challenge -> Spec -> Story -> Delivery.
• The guidance tells Codex to prompt toward missing upstream artifacts instead of broad implementation from partial context.
• The guidance allows bypass only when the user explicitly opts out.

Dependencies

• Document BetterFleet's Linear mapping rules
• Replace the broad story artifact with unit user stories

Skill Alignment

Tighten specification-writer for the workflow definition

User Story

As a workflow owner, I want specification-writer to pause on unresolved workflow and mirror decisions so the specification is decision-complete before story shaping starts.

Acceptance Criteria

• The skill explicitly pauses and asks when phase boundaries, Linear mapping, milestone or release expectations, release-note handling, or governance opt-out rules are unclear.
• The skill guidance stays concise and avoids speculative expansion.
• The skill guidance remains general enough to apply beyond this one workflow initiative.

Dependencies

• Rewrite the canonical specification around the three-phase workflow

Tighten story-shaper for unit user stories and Linear-ready mirrors

User Story

As a workflow owner, I want story-shaper to output unit user stories that can be mirrored directly into Linear so developers can start from one issue without reconstructing context.

Acceptance Criteria

• The skill guidance says the target output is a unit user story: the narrowest buildable slice.
• The skill guidance says each unit user story should be self-contained enough for direct backlog or Linear pickup.
• The skill guidance keeps dependencies explicit when they materially affect delivery order.
• The skill guidance does not encourage broad taxonomy or milestone grouping unless the specification explicitly requires it.

Dependencies

• Replace the broad story artifact with unit user stories