You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs/mbo/index.md is the MBO objective tracker. Today it does two jobs in one
hand-maintained markdown table:
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.
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 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.
Problem
docs/mbo/index.mdis the MBO objective tracker. Today it does two jobs in onehand-maintained markdown table:
issue(s) and PR(s). This is genuinely useful and worth keeping.
Statelifecycle column(
idea → designing → specifying → planning → building → in-review → merged → done, plusparked/superseded) and an Active vs Merged/historical split.The state half is hard to maintain by hand:
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.objectives complete.
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:
Status(single-select) field(
idea / designing / specifying / planning / building / in-review / merged / done, plusparked/superseded).merge/close) so state mostly maintains itself from issue/PR activity.
mbo-plan):set the initial
Status);Statusfield from issue/PR state where the built-in automations do not cover it;index.md(artifacts + links) from theProject/issues, so the markdown becomes a generated projection (like the teams routing
artifacts) rather than a hand-edited source.
What
index.mdkeeps vs. what movesis the accomplishment record and is worth preserving.
Statecolumn and the Active-vs-historical split —these become Project
Status+ views, not hand-edited markdown.Open design question: keep
index.mdas a hand-edited catalog (just drop theStatecolumn),or generate it from the Project so it can never go stale.
Scope / deliverables
This is itself an MBO objective (design → spec → plan):
index.mdowns);
Statusfield schema + any automations;docs/mbo/GEMINI.md/index.mdso the docs point at the Project as the statesource-of-truth.
Why now
Surfaced while reviewing
docs/mbo/index.md: the catalog is valuable, but the hand-maintainedStatecolumn + Active/historical split are already painful and will only get worse as theobjective count grows.