Challenge

Challenge: Product Engineering Workflow

How might we define a simple BetterFleet product engineering workflow that humans can follow directly and Codex can govern reliably, so work moves from challenge to specification to story-based delivery without losing release traceability?

Motivation

• BetterFleet already has challenge, specification, story, and release-note practices, but the default workflow joining them is still too implicit and the Linear mapping is still being defined.
• Teams need one readable path for normal governed work.
• Teams also need the canonical workflow artefacts to live in code in the places they will actually find and maintain them.
• Codex needs the same path to be explicit so it can guide governance and then assist delivery.
• Delivery should start from one narrow story and keep release-note work current as code lands.

Context

• Repo artifacts should remain the canonical source of truth for governed work.
• Linear should mirror the canonical artifacts for operational planning.
• The core workflow should be only three phases: Discovery, Definition, and Delivery.
• The workflow must be simple enough to run manually before any automation exists.
• Supporting BFDev docs needed to publish, find, or maintain the workflow may also need to live alongside the canonical artifacts in code.
• A developer, driving through Codex, should be able to start from one Linear issue, then confirm the broader challenge/spec context through links back to the canonical repo artifacts.

Domain Modelling

• Domain: BetterFleet product engineering workflow.
• Primary entities: Challenge, Specification, Story Set, Linear Initiative, Linear Project, Linear Issue, Linear Milestone, and unreleased release-note entry.

High-Level Use Cases / JTBD (Required)

• As a product lead, I want discovery to end in a canonical challenge so the real 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 developer using Codex, I want governed work to check challenge, spec, and story context before coding so I do not start from partial intent.
• As a developer using Codex, I want each mirrored Linear issue to contain one narrow user story with enough context to start work directly, so I do not need to reconstruct the intended slice from surrounding project notes.
• As a delivery stakeholder, I want Linear to mirror the canonical artifacts so day-to-day planning stays aligned.
• As a release stakeholder, I want unreleased release notes updated during delivery so a milestone is ready for end consumption when its stories are done.

Current State -> Desired State

Current State (Pain/Gain)	Desired Outcome	Success Measure
Pain: the default workflow is spread across habits and draft docs	One clear workflow explains the standard path for governed work	A reviewer can explain the workflow from the canonical artifacts alone
Pain: developers can start coding without clear upstream context	Governed delivery starts from a narrow canonical story	Less ambiguity about what "ready to code" means
Pain: the workflow does not yet define how Linear should mirror the canonical artifacts	BetterFleet-specific Linear mapping is written down concisely	A reviewer can map challenge/spec/story to Initiative/Project/Issue without guessing
Pain: the workflow is not yet prominent or easy to find in the BFDev docs surfaces people actually use	The canonical workflow lives as a persistent process artifact with aligned supporting docs surfaces	A reviewer can find the workflow and related guidance without relying on project-only context
Gain to unlock: Codex can assist governance and coding	Codex can check the same artifact chain humans use	Governed work can be validated against explicit rules instead of tacit context

Assumptions & Open Questions

• Key assumptions:
  • Repo artifacts remain canonical.
  • Linear is an operational mirror.
  • Delivery works story by story.
  • Milestones matter for normal product releases, but this internal workflow simplification does not need its own milestone plan in this pass.
• Open questions:
  • None for this pass.
• Validation plans (who/what/when):
  • Product and engineering review the challenge, specification, story set, and Linear mapping doc together.
  • The workflow is validated when a reviewer can explain the three phases, the Linear mapping, and the default Codex guardrails from the written artifacts alone.

Constraints & Out of Scope

• Constraints:
  • The workflow must stay readable and manual-first.
  • Normal governed work should follow Challenge -> Spec -> Story -> Delivery.
  • Bypassing the workflow must be an explicit user choice.
• Out of scope:
  • Runtime validators, sync jobs, or enforcement services.
  • A full Linear user guide.
  • Detailed rollout or release tooling design.

Evaluation

• User value:
  • Less ambiguity about how work should start and move forward.
  • Clearer handoff from discovery to definition to delivery.
  • Better release traceability because delivery updates release notes as it goes.
• Business value & strategic alignment:
  • Better consistency across human and Codex-driven work.
  • Faster onboarding into the BetterFleet way of working.
  • Cleaner foundation for later automation, if it is still justified after manual use.

Risks & Opportunities

• Risks:
  • The workflow remains too broad and keeps carrying exploratory detail that people will not follow.
  • Linear or draft docs are treated as canonical when the repo artifacts should win.
• Opportunities:
  • Establish one default BetterFleet workflow for governed project work.
  • Make Codex governance practical without adding tooling first.

Relationships

• Related projects: BFDev process docs, Codex-assisted delivery, Linear operating practice, and release-note preparation.
• Upstream/downstream dependencies:
  • The challenge feeds the specification, story set, Linear mirror rules, and Codex guardrails.

Solution Ideas & Tradeoffs

• Idea A (Preferred): keep a lean canonical artifact chain and document only the Linear mapping and Codex rules needed to run it.
  • Best for readability and day-to-day use.
• Idea B: keep the broader exploratory workflow model with more stages, gates, and tool concepts.
  • Covers more possibilities, but stays harder to read and harder to follow.
• Idea C: define tooling and enforcement first, then document the workflow around those rules.
  • Faster to mechanize, but higher risk of enforcing the wrong workflow.
• Preferred direction: Idea A, because BetterFleet first needs a direct workflow that humans and Codex can both follow.

Release Sequencing

• Natural or value-based order:
  • Rewrite the canonical challenge, specification, and story set.
  • Add the concise Linear mapping doc and Codex guardrails.
  • Apply the workflow to governed project work and refine it from use.
• Smaller parts to solve first:
  • Make the three phases explicit.
  • Make the repo-vs-Linear split explicit.
  • Make Codex default behavior explicit.
• Potential slices/releases:
  • v1: simplified canonical artifacts and guardrails.
  • v1.1: practical use on governed project work.