Skip to content

MBO: move objective state tracking to GitHub Project #4 + skills to maintain it #131

Description

@sfc-gh-eraigosa

Problem

docs/mbo/index.md is the MBO objective tracker. Today it does two jobs in one
hand-maintained markdown table:

  1. Catalog — for each objective: links to its design / spec / plan and the associated
    issue(s) and PR(s). This is genuinely useful and worth keeping.
  2. State — a State lifecycle column
    (idea → designing → specifying → planning → building → in-review → merged → done, plus
    parked / superseded) and an Active vs Merged/historical split.

The state half is hard to maintain by hand:

  • Every lifecycle transition is a manual markdown edit that must be kept in lockstep with what
    is actually happening on the issue/PR. It drifts immediately — e.g. a PR merges but the row
    still says in-review; an objective starts building but nobody moves the row.
  • The Active vs historical partition requires manually moving rows between two tables as
    objectives complete.
  • It does not scale: the more objectives we track, the more bookkeeping, and the markdown is
    never a reliable source of truth for "what is in flight right now."

GitHub already models exactly this (status fields, board / table / roadmap views, and automatic
reflection of issue/PR state) in Projects.

Proposed direction

Adopt GitHub Project #4 as the live,
source-of-truth state tracker for MBO objectives, and build skills to maintain it:

  • Field schema: map the MBO lifecycle to a Project Status (single-select) field
    (idea / designing / specifying / planning / building / in-review / merged / done, plus
    parked / superseded).
  • Auto-state: lean on Project built-in workflows (auto-add items, set status on PR
    merge/close) so state mostly maintains itself from issue/PR activity.
  • Skill(s) to maintain it (new, or an extension of mbo-plan):
    • register an objective on the Project when design work starts (create/link the design issue,
      set the initial Status);
    • sync the Status field from issue/PR state where the built-in automations do not cover it;
    • optionally regenerate the catalog portion of index.md (artifacts + links) from the
      Project/issues, so the markdown becomes a generated projection (like the teams routing
      artifacts) rather than a hand-edited source.

What index.md keeps vs. what moves

  • Keeps (catalog): the table of objectives → design/spec/plan links + issue/PR links. This
    is the accomplishment record and is worth preserving.
  • Moves to the Project (state): the State column and the Active-vs-historical split —
    these become Project Status + views, not hand-edited markdown.

Open design question: keep index.md as a hand-edited catalog (just drop the State column),
or generate it from the Project so it can never go stale.

Scope / deliverables

This is itself an MBO objective (design → spec → plan):

  • a design doc for the Project-managed MBO workflow (what the Project owns vs. what index.md
    owns);
  • the Project save project settings to a file we can manage #4 Status field schema + any automations;
  • the skill(s) to register objectives and keep state in sync;
  • updates to docs/mbo/GEMINI.md / index.md so the docs point at the Project as the state
    source-of-truth.

Why now

Surfaced while reviewing docs/mbo/index.md: the catalog is valuable, but the hand-maintained
State column + Active/historical split are already painful and will only get worse as the
objective count grows.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions