Product Development System¶

This is the core operating model for BetterFleet work. Start here for the 50,000-foot view, then zoom into the detailed process docs only when the next question needs more detail.

The whole system has one simple shape:

flowchart TB
  Signal["Signal<br/>Slack / support / customer / product / repo"]
  Triage["Linear triage<br/>one issue with enough context to decide"]
  Backlog["Backlog / not now<br/>visible state and missing decision"]

  subgraph Routes["Responsible routes"]
    direction TB
    Support["Support/bug"]
    Incident["Incident"]
    Fix["Small fix"]
    Docs["Process/docs"]
    Product["Governed product"]
  end

  subgraph Governed["Governed product route"]
    direction TB
    Index["Index challenge"]
    Project["Linear Project specification"]
    Issues["Linear issues"]
    Index --> Project --> Issues
  end

  Active["Active work<br/>one current Linear item"]
  Evidence["Repo evidence<br/>code / tests / ADRs / docs / notes"]
  Handoff["Handoff<br/>verification / Linear state / remaining gaps"]

  Signal --> Triage
  Triage --> Support
  Triage --> Incident
  Triage --> Fix
  Triage --> Docs
  Triage --> Product
  Product --> Index
  Issues --> Active
  Support --> Active
  Incident --> Active
  Fix --> Active
  Docs --> Active
  Triage -.-> Backlog
  Active --> Evidence --> Handoff
  Handoff -.-> Active

Use the companion Workflow Map when a visual orientation is enough. Use this page when you need the model behind the map.

Design Principles¶

The system is built on five principles for operating as an AI-native product organisation.

Target machine legibility.

Every planning artifact has a defined owning system, status, and set of required fields. For governed product work, the Index Challenge -> Linear Project Specification -> Linear Issue traceability chain means any agent can navigate from a line of code back to the business problem that motivated it.

Create visible tools.

Index, Linear, GitLab, and the repos are the operational tools. Linear is the main operating surface for work. Index holds governed challenge framing. Linear Projects hold governed specifications. Linear issues hold active state and execution plans. Repos hold implementation and shipped-output artifacts such as code, tests, ADRs, release notes, and help docs.

Assign work to expert loops.

AI skills are expert loops that embed best practices in a process context. challenge-writer runs Socratic problem framing. specification-writer runs eventstorming. story-shaper applies established slicing heuristics. Reviews are structured expert panels: LLM reviewers produce findings, and human experts confirm or challenge them. The process defines when and how these loops run, what they produce, and how their outputs are used.

Organise around outcomes.

Each route is defined by the outcome it needs to produce. Triage produces a clear next path. Governed product work produces an Index challenge, a Linear Project specification, and Linear issues. Delivery produces shipped behaviour, release notes, help docs, operational docs, and verification evidence. Done is a state with explicit conditions, not a feeling that the activity is over.

Evaluate with human review.

Expert review, QA checkpoints, and human gates are the repeating pattern throughout the system. LLMs produce findings; humans confirm or challenge them. QA keeps humans in the loop at the points where correctness, customer impact, or operational risk matter.

Operating Contract¶

Linear should tell anyone what is going on without needing a spoken status update:

• what work is being considered
• what work is active
• who owns the current step
• what is blocked
• what changed
• what state the work is in

Slack, meetings, customer messages, and informal conversations can create signals. They are not durable workflow memory. If they create work, capture the durable part in the right artifact.

The durable sources are:

How Work Enters¶

If new work appears and it is not already in a clear process, create or update one Linear triage issue. The triage issue should contain just enough context for the Head of Engineering and Lead Product Manager to decide the next path:

• need or problem
• why it matters
• source or context
• affected customer, product area, support path, or repo
• urgency or known deadline
• suspected owner, if known
• decision needed next

Do not turn a raw Slack thread, meeting note, customer message, or idea into a full challenge, project, or implementation plan before triage.

If the work is valid but not selected now, keep it visible in backlog or a placeholder state with the missing next decision recorded. Backlog work is not delivery-ready just because it exists.

Work Routes¶

Triage decides the route. Governed product work is one route, not the default shape for every bug, investigation, incident, or narrow repo fix.

Day-To-Day Loop¶

For active work:

1. Pick the Linear item you are actually working on.
2. Confirm it is in the right route.
3. Move or keep the active item in In Progress and assign it to the person doing the current step.
4. Stay inside the issue boundary.
5. Investigate, implement, test, or document in the relevant repo or executable environment.
6. Update release notes, help docs, ADRs, or operational docs when the change affects what users, operators, or future implementers need to know.
7. Keep Linear current when scope, blockers, dependencies, owner, status, or estimate changes.
8. Hand off with concise verification evidence, current Linear state, and any remaining gaps.

If the active Linear item does not match the work actually happening, fix the Linear state or switch work before continuing.

Governed Product Route¶

Use this route only after triage decides the work needs governed product shaping.

The detailed governed route is:

flowchart TB
  Goals["Product goals<br/>industry / competition / customer feedback"]
  Commitments["Customer commitments<br/>scope / deadlines / constraints"]
  TriageSeed["Linear triage issue<br/>governed route selected"]
  Selection["Selection / prioritisation<br/>challenge queue"]

  subgraph Discovery["Discovery"]
    direction TB
    ChallengeWriter["challenge-writer"]
    Challenge["Index challenge<br/>review gate"]
    ChallengeWriter --> Challenge
  end

  subgraph Definition["Definition"]
    direction TB
    UX["UI/UX design<br/>wireframes / flows / interaction model"]
    SpecificationWriter["specification-writer<br/>business logic / user solution / technical what"]
    Specification["Linear Project specification<br/>review gate"]
    Scenarios["bdd-scenario-writer<br/>Given / When / Then"]
    StoryShaper["story-shaper<br/>Linear issues / acceptance criteria"]
    ExecutionPlan["Execution plan<br/>review gate"]
    UX --> SpecificationWriter
    SpecificationWriter --> Specification
    Specification --> Scenarios
    Specification --> StoryShaper
    Scenarios --> StoryShaper
    StoryShaper --> ExecutionPlan
  end

  subgraph Delivery["Delivery"]
    direction TB
    Implementation["software-workflow<br/>canon-tdd / python / react"]
    MergeRequest["GitLab MR<br/>description / peer review"]
    Staging["Staging validation<br/>Validated in Staging label"]
    Implementation --> MergeRequest
    MergeRequest --> Staging
  end

  subgraph Release["Release follow-through"]
    direction TB
    WorkingNotes["Working release notes<br/>next.public / next.internal / holdback"]
    HelpDocs["In-app help docs"]
    PublishedNotes["Published release notes<br/>weekly cut"]
    WorkingNotes --> PublishedNotes
  end

  IndexStore[("Index<br/>challenge")]
  LinearStore[("Linear<br/>Project / issues")]

  Goals --> Challenge
  Commitments --> Challenge
  Commitments --> Selection
  TriageSeed --> ChallengeWriter
  Challenge --> Selection
  Selection --> UX
  Selection --> SpecificationWriter
  ExecutionPlan --> Implementation
  Staging --> WorkingNotes
  Staging --> HelpDocs

  Challenge -.-> IndexStore
  Specification -.-> LinearStore
  ExecutionPlan -.-> LinearStore
  Staging -.-> LinearStore

Do not skip forward silently. If the Index challenge, Linear Project specification, or active Linear issue is missing, shape that stage before broad implementation unless the requester explicitly opts out.

Output Follow-Through¶

Delivery is not just code. The repo must carry the shipped evidence people will need later:

Working release notes and product help docs live in the product repo. BFDev process docs live here under docs/process/.

Review And Expert Loops¶

Use expert loops where they reduce risk or improve quality; do not turn them into ceremony for every small change.

Human reviewers confirm or challenge important findings. The target is clearer decisions and safer delivery, not more process text.

Weekly Planning¶

Use Linear for the weekly operating view:

• Triage items needing a route.
• Top backlog items surfaced for planning.
• Rolled-over work that needs re-selection or closure.
• Ready small work.
• Active governed projects and their next gate.
• Blocked work needing a decision.

Cycles are weekly planning containers, not release boundaries. Automatic rollover is a review prompt, not a commitment to keep doing the same work.

Zoom In¶

Use these companion docs when the core model is not enough: