Specification: Product Engineering Workflow¶

TLDR (Solution Summary)¶

Define a lean BetterFleet workflow with three phases: Discovery creates a canonical Challenge, Definition creates a canonical Specification and Story Set, and Delivery ships one story at a time while maintaining code-native release-note artifacts in product repos: each product UI repo owns docs/release-notes/ at its repo root, with bf-manage-web/docs/release-notes/unreleased.md as the first concrete implementation; that unreleased note is updated continuously, sectioned into Public, Beta, and Internal content, and each visibility section is further broken into changelog-style subsections such as Added, Changed, and Fixed, with Internal retaining feature-flag grouping inside those subsections; weekly release promotion copies only Public and Beta into bf-manage-web/docs/release-notes/releases/<version>.md, historical notes move from ClickUp into versioned files, and product UIs can render those notes through a help-style markdown/nav surface; putting that workflow into place also means landing the persistent process docs and related docs surfaces in code, while Linear mirrors the canonical artifacts and Codex checks the artifact chain by default before coding.

• Discovery workflow + use challenge-writer with a human in the loop to produce one canonical Challenge + governed work starts from a clear problem statement.
• Definition workflow + use specification-writer and then story-shaper to produce one canonical Specification and a Story Set of unit user stories + delivery starts from narrow, explicit stories.
• Delivery workflow + work from one story at a time, update the product repo's docs/release-notes/unreleased.md (first concrete path: bf-manage-web/docs/release-notes/unreleased.md), and keep relevant user-facing docs current + shipped scope is documented at the point it lands.
• Release-note artifact model + define each product repo's docs/release-notes/unreleased.md and docs/release-notes/releases/<version>.md (first concrete paths in bf-manage-web) as the code-native source for current and published notes + release communication lives in product repos rather than ClickUp.
• Release-note visibility model + keep Public, Beta, and Internal sections in unreleased notes, require changelog-style subsections inside each visibility section, and keep feature-flag grouping inside Internal subsections + rollout state and note visibility stay explicit and reviewable.
• Release-note history and surface + migrate historical notes from ClickUp and define an in-app release-notes surface parallel to help docs using the same markdown/nav pattern + users can browse current and past release notes in the app.
• Persistent workflow docs and mirror rules + land the workflow in docs/process/product-engineering-workflow.md, align the supporting BFDev docs surfaces that expose it, and keep the Linear mirror concise + the workflow stays usable beyond the project artifact set.

1. Summary¶

• Problem statement:
  • BetterFleet's workflow currently treats release notes mostly as a delivery reminder rather than a defined artifact model.
  • Historical release notes still live outside the product repos in ClickUp-derived processes, which makes the source of truth for released scope harder to follow.
  • Weekly release communication risks drift when the publishable note is reconstructed late instead of promoted from content that delivery has already kept current.
  • Product UI repos already have a markdown-and-nav pattern for in-app help, but release notes are not yet defined as a parallel code-native surface.
• Goal and success criteria:
  • Define one clear workflow for governed work using Discovery, Definition, and Delivery.
  • Define release notes as code-native product artifacts owned in product repos.
  • Make release-note visibility, feature-flag linkage, and weekly promotion rules explicit enough for product, engineering, and release stakeholders to review directly.
  • Keep Codex default behavior explicit for normal governed project work while allowing this initiative to shape the release-note model more broadly.
  • Success means a reviewer can read the challenge, specification, stories, persistent process docs, and Linear mapping doc once and explain where current release-note content lives, what gets published, what stays unreleased, how feature flags affect notes, and how governed delivery keeps those artifacts current.
  • Success also means a relevant MR and a relevant completed story can be checked against explicit release-note follow-through rather than relying on unwritten team practice.
  • Success also means historical release notes are defined to live in code and the in-app release-note surface is defined as a parallel to the help-doc experience instead of an unrelated content path.
• What will be built in this phase:
  • docs/artifacts/archived/code-canonical-orchestration/spec.md + define the release-note operating model, artifact paths, visibility rules, promotion rules, and migration expectations + release notes become a code-native workflow asset rather than only a delivery reminder.
  • docs/artifacts/archived/code-canonical-orchestration/stories.md + reshape the release-note work around IPT-106 and explicit downstream split signals + the repo and Linear mirror use the same broader framing.
  • bf-manage-web/docs/release-notes/unreleased.md + define the first concrete working note with Public, Beta, and Internal sections plus changelog-style subsections, while keeping internal rollout notes grouped by feature flag + the current shippable state stays explicit during delivery.
  • bf-manage-web/docs/release-notes/releases/<version>.md + define the first concrete published-note path with release metadata + weekly releases are promoted from unreleased content instead of rewritten from scratch.
  • historical ClickUp release notes + define migration into versioned code-native files + release-note history moves into the repo.
  • release-note app surface + define a view parallel to help docs using the same markdown/nav pattern + users can browse release notes in-app through a familiar content model.
  • MR and story delivery rules + require relevant MRs to check release-note impact and relevant stories to add or revise unreleased entries + release communication stays current as scope lands.
• Scope (in/out) for this phase:
  • In:
  • The core governed workflow for BetterFleet project work.
  • The canonical artifact chain and the BetterFleet-specific Linear mirror rules.
  • The release-note artifact model for product UI repos, including exact path conventions.
  • Release-note visibility rules for Public, Beta, and Internal content, including changelog-style subsections and internal feature-flag grouping.
  • Historical release-note migration expectations from ClickUp into code-native files.
  • The in-app release-note surface expectation that reuses the existing help markdown/nav pattern.
  • Delivery obligations requiring relevant MRs and completed stories to keep release-note content current.
  • Out:
  • Runtime validation or sync tooling.
  • Detailed automation implementation for release-note promotion.
  • A full Linear user guide.
  • A redesign of every documentation surface beyond what is needed to expose the canonical workflow and define the release-note surface.
  • Detailed database, API, or CI design for release-note handling.
• Current baseline (as of March 18, 2026):
  • The canonical workflow artifacts already say delivery should update unreleased release notes, but they do not yet define the artifact model behind that rule.
  • Historical release notes are still associated with ClickUp-driven preparation rather than versioned product-repo files.
  • bf-manage-web already renders markdown help content from docs/help/ using nav.json, which makes bf-manage-web/docs/release-notes/ the first concrete target for a release-note tree that sits parallel to help.
  • Linear issue descriptions do not yet consistently capture the broadened release-note operating model that this initiative now requires.
• Future evolution guardrails:
  • Repo artifacts must remain canonical.
  • The release-note model must support Public, Beta, and Internal separation without manual archaeology.
  • Later automation must fit the written release-note model rather than redefine it.
  • The default governed rule remains one narrow story at a time; broader shaping work must stay explicit when it is an exception.
• Not in scope:
  • Database, API, CI, or service-level enforcement design.
  • Detailed release tooling or rollout automation beyond defining the target artifact model and promotion behavior.

2. Users and Use Cases¶

• Primary personas:
  • Product lead framing governed work.
  • Engineering Lead (DRI) handling Definition.
  • Developer using Codex to work from a narrow story.
  • Delivery stakeholder managing the Linear mirror.
  • Release stakeholder preparing customer-visible communication.
  • Documentation or support stakeholder maintaining help and release-note surfaces in the app.
  • Workflow or docs maintainer keeping the persistent process docs and supporting surfaces aligned.
• High-level user stories:
  • As a product lead, I want Discovery to end in a canonical challenge so the problem is explicit before solution design starts.
  • As an Engineering Lead (DRI) handling Definition, I want Definition to end in a canonical specification and story set so delivery starts from narrow, buildable slices.
  • 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.
  • As a developer working a relevant change, I want every relevant MR and completed story to explicitly check and update docs/release-notes/unreleased.md so the current shippable state is already described.
  • As a documentation or support stakeholder, I want release notes viewable in-app through a surface parallel to help docs so users and internal teams can browse current and historical release changes from the product.
  • As a delivery stakeholder, I want Linear to mirror the canonical artifacts so operational planning stays aligned.
  • As a workflow or docs maintainer, I want the persistent process docs and their supporting BFDev docs surfaces aligned so the workflow is easy to find, publish, and maintain in practice.
• Edge cases and failure modes:
  • Coding starts without a narrow story.
  • Linear is treated as the source of truth instead of a mirror.
  • Relevant MRs ship without checking release-note impact.
  • A completed story lands but unreleased.md still reflects an earlier product state.
  • Internal-only content leaks into a published release note.
  • Beta-visible content is either omitted from the published note or presented as general-availability scope.
  • Feature-flagged changes exist in release notes without a clear feature-flag grouping.
  • Historical release notes stay trapped in ClickUp after the code-native model is defined.
  • The workflow remains trapped in project artifacts and never lands as a persistent process doc.
  • A temporary feature flag remains in place for scope that is supposed to be generally released to users.
  • One-off work is treated as governed project work, or governed project work is bypassed without an explicit opt-out.

3. Conceptual Model Terms and Decisions¶

Key Terms¶

Decision Ledger¶

4. Domain Model and Eventstorming (Conceptual)¶

• Bounded context and ubiquitous language:
  • Canonical Workflow uses Challenge, Specification, Story Set, and Delivery.
  • Workflow Documentation uses the Persistent Workflow Artifact and the supporting BFDev docs surfaces that expose it.
  • Operational Planning uses Linear Initiative, Linear Project, Linear Issue, Linear Milestone, and Linear Cycle.
  • Release Communication uses Release Notes Root, Unreleased Release Note, Published Release Note, Release Note Visibility Section, Release Note Change Type Subsection, Feature Flag Bucket, Release Notes Surface, and shipped milestone scope.
• Aggregates and entities (abstract):
  • Challenge Record: problem statement, scope, constraints.
  • Specification Record: workflow definition, Linear mirror summary, Codex rule set, and release-note model.
  • Story Set Record: unit user stories and dependencies.
  • Unit User Story Record: one narrow buildable slice with a story statement, acceptance criteria, material dependencies, and canonical links.
  • Persistent Workflow Artifact: long-term process doc for humans in docs/process/.
  • Workflow Docs Surface: BFDev documentation paths or publication surfaces that expose the workflow and supporting guidance.
  • Release Notes Root: product-repo tree containing unreleased.md, versioned published notes, nav data, and any release-note assets.
  • Unreleased Release Note: single working note that accumulates current Public, Beta, and Internal entries.
  • Published Release Note: versioned weekly note with metadata such as release date.
  • Release Note Visibility Section: Public, Beta, or Internal bucket inside unreleased.md.
  • Release Note Change Type Subsection: Added, Changed, Fixed, or another approved changelog category inside a visibility section.
  • Feature Flag Bucket: subsection keyed by feature flag inside an internal change-type subsection.
  • Release Notes Surface: in-app release-note browser that reads markdown and nav data using the help-doc pattern.
  • User-Facing Doc Update: help or guide content updated during delivery when shipped behavior changes what users see, expect, or need to do.
• Value objects (if relevant):
  • Workflow Phase, Mirror Link, Milestone Scope, ReleaseVersion, ReleaseNoteVisibility, FeatureFlagRef.
• Domain events and their triggers:
  • ChallengeWritten when discovery produces a canonical challenge.
  • SpecificationWritten when definition produces a canonical specification.
  • StorySetWritten when definition produces the canonical stories.
  • LinearIssuePrepared when a mirrored Linear issue is ready for direct developer pickup.
  • StoryDelivered when one story is implemented and completed.
  • ReleaseNoteUpdated when delivery adds or revises the unreleased note for shipped scope.
  • ReleaseNotesPromoted when weekly release creation copies Public and Beta content into a versioned published note.
  • HistoricalReleaseNotesMigrated when ClickUp history is moved into versioned code-native files.
  • ReleaseNotesSurfacePublished when the in-app release-note surface is wired to the repo-owned release-note artifacts.
  • UserFacingDocUpdated when delivery updates relevant user-facing docs for shipped scope.
  • WorkflowDocPublished when the persistent process doc or its supporting BFDev docs surfaces are updated to expose the current workflow.
  • MilestoneReleased when a released-together scope is live to users.
• Commands, actors, and policies:
  • WriteChallenge by product lead or workflow owner using challenge-writer.
  • WriteSpecification by workflow owner using specification-writer with human review.
  • ShapeStories by workflow owner or engineering lead using story-shaper with human review.
  • PrepareLinearIssue by workflow owner or delivery stakeholder.
  • CheckReleaseNoteImpact by MR author or reviewer on each relevant MR.
  • UpdateUnreleasedReleaseNote by a developer or docs owner when a relevant story lands.
  • PromoteWeeklyReleaseNotes by a release stakeholder when a weekly release is cut.
  • MigrateHistoricalReleaseNotes by a docs or release owner moving history out of ClickUp.
  • PublishReleaseNotesSurface by a UI or docs maintainer wiring the in-app release-note experience.
  • PublishWorkflowDocs by workflow owner or docs maintainer.
  • MirrorWorkInLinear by delivery stakeholders or Codex-supported workflow steps.
• Invariants and business rules enforced:
  • Governed work follows Discovery -> Definition -> Delivery.
  • Discovery produces Challenge; Definition produces Specification then Story Set.
  • Story Set entries are unit user stories by default; broader shaping exceptions must be explicit.
  • Repo artifacts remain canonical.
  • The workflow must land as a persistent process doc, not only as project artifacts.
  • Linear mirrors the canonical artifacts.
  • Each mirrored Linear issue must be directly usable as the starting point for implementation unless it is an explicitly broader shaping exception.
  • Product UI repos own docs/release-notes/, with bf-manage-web/docs/release-notes/ as the first concrete implementation.
  • docs/release-notes/unreleased.md contains Public, Beta, and Internal sections, with bf-manage-web/docs/release-notes/unreleased.md as the first concrete file.
  • Each visibility section uses changelog-style subsections such as Added, Changed, and Fixed.
  • Internal entries inside those change-type subsections are grouped by feature flag or an explicit no-flag bucket.
  • Each relevant MR checks release-note impact.
  • Each completed relevant story adds or revises unreleased.md.
  • Published release notes contain only Public and Beta content, with Beta called out separately.
  • Internal content remains in unreleased.md until its visibility changes.
  • Historical release notes live in versioned code-native files after migration.
  • For normal product work, milestones represent released-together customer scope.
  • Cycles are weekly planning only.
  • Bugs outside projects go through IPT triage.
  • Codex checks for upstream challenge, spec, and story context before coding unless the user explicitly opts out.
• External systems and integrations:
  • Linear mirrors challenges, specs, unit user stories, milestones, and cycles for operational use.
  • ClickUp is the migration source for historical release-note content.
  • BFDev docs surfaces expose the persistent workflow docs and supporting guidance for humans.
  • Product UI apps can reuse the help markdown/nav pattern to render release-note content in-app.

Interaction Flow¶

flowchart LR
  D["Discovery: Challenge"] --> F["Definition: Specification"]
  F --> S["Definition: Story Set"]
  S --> LI["Linear Issues Ready for Pickup"]
  S --> C["Delivery: One Story at a Time"]
  C --> M["MR checks release-note impact"]
  M --> U["Update bf-manage-web/docs/release-notes/unreleased.md"]
  U --> P["Public by change type"]
  U --> B["Beta by change type"]
  U --> I["Internal by change type and feature flag"]
  P --> R["Promote weekly release note"]
  B --> R
  I --> U
  R --> V["bf-manage-web/docs/release-notes/releases/<version>.md"]
  V --> A["In-app release-note surface"]
  V --> G["Milestone Ready for Release"]
  F --> W["Persistent Workflow Docs"]
  W --> X["BFDev Docs Surfaces"]

Event Timeline¶

timeline
  title Product Engineering Workflow
  Discovery: Challenge written
  Definition: Specification written
  Definition: Story set written
  Definition: Linear issues prepared for direct pickup
  Definition: Persistent workflow doc landed
  Delivery: Story delivered
  Delivery: Release note updated
  Release: Weekly public and beta notes promoted
  Release: Milestone released
  Migration: Historical release notes moved from ClickUp
  Experience: In-app release-note surface published

Event Dictionary¶

• ChallengeWritten: discovery artifact is created | starts governed work | challengeRef, scope | enables definition.
• SpecificationWritten: definition artifact is created | defines the workflow for the work scope | specRef, phaseSummary | enables story shaping.
• StorySetWritten: canonical delivery stories exist | makes delivery narrow and explicit by default | storyRefs, dependencies | enables coding.
• LinearIssuePrepared: mirrored issue is ready for direct developer pickup | keeps the operational mirror usable on its own | issueRef, storyRef, contextLinks | supports coding from Linear.
• WorkflowDocPublished: persistent workflow docs or their BFDev docs surfaces are updated | keeps the workflow prominent and maintainable | docRef, surfaceRef | supports human adoption.
• StoryDelivered: one story is implemented | marks a unit of scope as complete | storyRef, status | may update milestone readiness.
• ReleaseNoteUpdated: unreleased note is added to or revised during delivery | keeps current shippable scope traceable | noteRef, storyRef, visibility, changeType, featureFlagRef | supports release communication.
• ReleaseNotesPromoted: weekly release creation copies Public and Beta content into a versioned note | makes the published release note a direct output of delivery-maintained content | unreleasedRef, releaseRef, releaseVersion | supports customer-facing release communication.
• HistoricalReleaseNotesMigrated: ClickUp history is moved into versioned code-native files | makes historical release notes durable in the repo | sourceRef, releaseRefs | supports continuity and in-app browsing.
• ReleaseNotesSurfacePublished: release-note markdown and nav data are rendered in the app | exposes current and historical notes to users | surfaceRef, contentRootRef | supports product experience and support.
• UserFacingDocUpdated: relevant user-facing docs are updated during delivery | keeps shipped guidance accurate | docRef, storyRef | supports user adoption and support.
• MilestoneReleased: released-together scope is live to users | closes a customer-facing scope group | milestoneRef, scopeSummary | completes that delivery boundary.

5. Requirements and Constraints¶

• Functional requirements:
  • FR-001: The workflow shall define exactly three phases: Discovery, Definition, and Delivery.
  • FR-002: Discovery shall produce one canonical Challenge using challenge-writer with a human in the loop.
  • FR-003: Definition shall produce one canonical Specification using specification-writer with a human in the loop.
  • FR-004: Definition shall then produce one canonical Story Set of unit user stories using story-shaper with a human in the loop.
  • FR-005: Delivery shall start from one narrow story at a time and keep code-native release notes and any relevant user-facing docs current as work lands when shipped behavior changes what users see, expect, or need to do.
  • FR-006: Repo artifacts shall remain the canonical source of truth for governed work.
  • FR-007: The workflow shall define Initiative -> Challenge, Project -> Specification, Issue -> Unit User Story, and issue-dependency mirroring in Linear.
  • FR-008: The workflow shall define Milestone as released-together customer scope and Cycle as weekly planning only.
  • FR-009: The workflow shall define bugs outside projects as IPT triage work rather than forcing them into a project.
  • FR-010: For governed project work, Codex shall check Challenge -> Spec -> Story context before coding.
  • FR-011: The workflow shall allow explicit sidestepping when the user clearly opts out of the governed workflow.
  • FR-012: The workflow initiative shall land docs/process/product-engineering-workflow.md as the persistent human-readable workflow artifact, make the default developer operating path for governed work explicit enough for a new team member or Codex to follow without unwritten team context, and keep relevant workflow doc links aligned to it.
  • FR-013: The workflow initiative shall include the BFDev docs surfaces and supporting repo artifacts needed to publish, find, and maintain the canonical workflow docs in practice.
  • FR-014: The canonical story set shall be made of unit user stories that are the narrowest buildable delivery slices for the governed work by default.
  • FR-015: Each mirrored Linear issue shall include the user story statement, acceptance criteria, material dependencies, and links back to the canonical specification and challenge so a developer can start from the issue directly.
  • FR-016: For product UI repos, the workflow shall define docs/release-notes/ at the product repo root as the code-native home for release-note artifacts, with bf-manage-web/docs/release-notes/ as the first concrete implementation.
  • FR-017: The workflow shall define docs/release-notes/unreleased.md at the product repo root as the single working release-note file for current changes, with bf-manage-web/docs/release-notes/unreleased.md as the first concrete file.
  • FR-018: The workflow shall define docs/release-notes/releases/<version>.md at the product repo root as the published release-note file for each released version and shall require release metadata such as release date, with bf-manage-web/docs/release-notes/releases/<version>.md as the first concrete path.
  • FR-019: The workflow shall define unreleased.md with top-level Public, Beta, and Internal sections.
  • FR-020: The workflow shall require each visibility section to use changelog-style subsections such as Added, Changed, and Fixed, with optional categories such as Removed, Deprecated, or Security when needed.
  • FR-021: The workflow shall require internal entries inside those change-type subsections to be grouped by feature flag so rollout linkage remains explicit and checkable.
  • FR-022: Each relevant MR shall explicitly check whether release notes need to be added or revised.
  • FR-023: Each completed relevant story shall add or revise the unreleased note so the current shippable state is accurately described at that point in delivery.
  • FR-024: Weekly release creation shall promote only Public and Beta content from unreleased.md into the published release note, leaving Internal content in unreleased.md.
  • FR-025: Published release notes shall present beta-visible scope in a distinct Beta section and shall exclude internal-only scope.
  • FR-026: Historical release notes shall be migrated from ClickUp into versioned code-native release-note files.
  • FR-027: Release-note files shall be intended for in-app viewing through a surface parallel to the help/user-guide experience, reusing the same markdown/nav pattern.
  • FR-028: Milestone delivery shall treat unreleased Public and Beta content as the final release-note source for the release rather than requiring a fresh rewrite step.
• Non-functional requirements:
  • NFR-001: The workflow must be readable in one pass by product, engineering, and delivery stakeholders.
  • NFR-002: The workflow must be manually executable without runtime enforcement tooling.
  • NFR-003: The workflow must clearly separate canonical artifacts from operational mirrors and exploratory reference docs.
  • NFR-004: The workflow must be direct enough for Codex to use as governance guidance without hidden team context.
  • NFR-005: The Linear guidance must stay BetterFleet-specific and concise, not a generic user guide.
• Constraints and assumptions:
  • Product UI repos own docs/release-notes/unreleased.md and docs/release-notes/releases/ as the target release-note paths, with bf-manage-web/docs/release-notes/ as the first concrete implementation.
  • Internal-only feature-flagged scope may remain in unreleased.md across multiple weekly releases until its visibility changes.
  • Historical release-note migration uses ClickUp as the starting source.
  • User-facing docs are updated during delivery when shipped behavior changes what users see, expect, or need to do.
  • Milestone modeling is defined for normal product work, but this internal workflow simplification does not need its own milestone plan in this pass.
  • Labels are out of scope for core governance until BetterFleet standardizes them for validation.
• Build item coverage mapping:
  • Challenge rewrite build item -> FR-001, FR-002, FR-006, NFR-001.
  • Specification rewrite build item -> FR-001, FR-003, FR-005, FR-006, FR-010, FR-011, FR-012, FR-013, FR-016 through FR-028, NFR-001, NFR-002, NFR-004.
  • Story set rewrite build item -> FR-004, FR-005, FR-014, FR-015, FR-022, FR-023, NFR-001.
  • Persistent workflow doc build item -> FR-012, FR-013, NFR-001, NFR-003.
  • Linear mapping doc build item -> FR-007, FR-008, FR-009, NFR-003, NFR-005.
  • Release-note operating model build item -> FR-016 through FR-028, NFR-001, NFR-003.
  • Codex guardrails and support docs surfaces build item -> FR-010, FR-011, FR-013, FR-015, NFR-004.
• Verification notes:
  • FR-001 through FR-005: validate by reading the canonical challenge, specification, and story set together.
  • FR-006 through FR-009: validate by reading the specification and the companion Linear mapping doc.
  • FR-010 and FR-011: validate through the AGENTS and skill guidance.
  • FR-016 through FR-028: validate by reading the specification and story set and confirming they define the artifact paths, visibility sections, change-type subsections, internal feature-flag grouping, promotion rule, migration expectation, app-surface intent, and MR/story obligations.
  • NFR-001 through NFR-005: validate through a concise-document review with product, engineering, and delivery stakeholders.

6. Interaction and Flow¶

• User journey or process steps:
  • Write the canonical challenge in Discovery.
  • Write the canonical specification, then the canonical story set of unit user stories, in Definition.
  • Prepare one mirrored Linear issue per unit user story with the story statement, acceptance criteria, material dependencies, and canonical links.
  • Land the persistent workflow docs in docs/process/ and align the supporting BFDev docs surfaces that expose them.
  • Mirror the governed work into Linear for operational planning.
  • Deliver one story at a time in Delivery.
  • For each relevant MR, check whether release-note content must be added or revised.
  • Update the product repo's docs/release-notes/unreleased.md as each relevant story lands, placing entries in the correct visibility and change-type subsection, and grouping internal entries by feature flag; for BetterFleet Manage, that file is bf-manage-web/docs/release-notes/unreleased.md.
  • Update relevant user-facing docs or in-app help when shipped behavior changes what users see, expect, or need to do.
  • Promote unreleased Public and Beta content into the product repo's docs/release-notes/releases/<version>.md when the weekly release is cut, leaving Internal content behind; for BetterFleet Manage, that path is bf-manage-web/docs/release-notes/releases/<version>.md.
  • Release milestones when the grouped stories are done, the public and beta notes are ready for direct promotion, the scope is live to users, and temporary feature flags for generally released scope are removed.

Flowchart: Governed Work¶

flowchart TD
  A["Challenge"] --> B["Specification"]
  B --> C["Story Set"]
  C --> K["Linear Issue Ready for Pickup"]
  B --> H["Persistent Workflow Docs"]
  C --> D["Linear Project + Issues"]
  K --> E["Deliver One Story"]
  E --> M["Check MR release-note impact"]
  M --> F["Update bf-manage-web/docs/release-notes/unreleased.md"]
  F --> P["Public by change type"]
  F --> Q["Beta by change type"]
  F --> R["Internal by change type and feature flag"]
  P --> S["Promote weekly published note"]
  Q --> S
  R --> F
  H --> I["BFDev Docs Surfaces"]
  S --> G["bf-manage-web/docs/release-notes/releases/<version>.md"]
  G --> J["Release-note app surface"]
  G --> L["Milestone Ready"]
  I --> L

Sequence Diagram: Codex Guardrail¶

sequenceDiagram
  participant User
  participant Codex
  participant Repo
  User->>Codex: Start governed project work
  Codex->>Repo: Check challenge, spec, and story context
  alt Context complete
    Codex-->>User: Proceed from the narrow story
  else Missing upstream artifact
    Codex-->>User: Prompt toward the missing artifact
  end
  User->>Codex: Explicitly opt out
  Codex-->>User: Bypass governed workflow for that request

7. Non-Technical Implementation Approach¶

• Approach overview:
  • Rewrite the canonical challenge, specification, and story set around the simplified three-phase model.
  • Expand the specification so it defines docs/release-notes/ in the product repo, starting with bf-manage-web/docs/release-notes/, as a code-native artifact model rather than only a delivery reminder.
  • Reshape the story set and the mirrored Linear issues so the release-note work is framed explicitly, with any broader shaping exception called out rather than implied.
  • Land the persistent process docs and the BFDev docs surfaces that make the workflow easy to find in practice.
  • Add one short BetterFleet-specific Linear mapping doc.
  • Reuse the help markdown/nav pattern as the intended release-note surface model instead of inventing a second content approach.
  • Keep automation and implementation-heavy follow-through, including INF-4, as downstream work once the artifact model is explicit.
• Design considerations:
  • Favor direct wording over exhaustive workflow theory.
  • Keep repo artifacts canonical and Linear mirrored.
  • Keep release traceability inside delivery, not after it.
  • Keep visibility rules explicit enough to distinguish Public, Beta, and Internal scope at review time.
  • Allow explicit exceptions without weakening the default governed path.
• Dependencies and prerequisites:
  • Agreement that the simplified three-phase model is the default governed workflow.
  • Agreement that Linear remains a mirror.
  • Agreement on the BFDev docs surfaces that should expose the persistent workflow docs.
  • Agreement that changelog-style subsections are required inside unreleased visibility sections, and that internal entries still keep feature-flag grouping within those subsections.
  • Agreement that Codex should prompt toward missing upstream artifacts rather than infer them silently.

8. Open Questions¶

• None for this pass.

9. Appendices¶

• Persistent workflow artefact target: docs/process/product-engineering-workflow.md
• Companion Linear mapping doc: docs/process/workflows/product-engineering-linear.md
• Exploratory workflow package retained as reference only: docs/process/workflows/code-canonical-orchestration/