MotirBuilding in public
MOTIR · moooon
onMotir
You’re viewing a public project. Anyone can view it — no account needed. Sign in to submit, upvote, or comment on requests.View-only — you can’t edit work items
MOTIR-3175

Planning bug: (motir-meta) a deferral written in a DESIGN ASSET or a source COMMENT is invisible to the deferral-is-a-card rule — the AI orb shipped a mock "M" for 18 days with no card

Done
Description

THE REPLAN ACTION step 5 for motir re-plan MOTIR-1343 (2026-08-19). The plan correction is already applied — plan cmt0ou3li00hxi2ph0iowzhp9, in the review queue. This work item is the RULE change that would have prevented it.

What happened

Motir's most-visible control — the floating orb on every authed screen, the door to every AI capability — has rendered a literal M placeholder since it shipped on 2026-08-01, and no card in the tree owned replacing it. It was found only because Yue looked at it and said so.

It was not an oversight in the usual sense. The deferral was written down twice, in plain language, by the people who knew:

  • motir-core/design/ai-chat/design-notes.md § "B — the floating 'M' button": "Built now with a mock M logo — the real brand logo replaces it later (the orb is the logo's home)."
  • motir-core/components/planning/PlanWithAIFab.tsx, both in the docstring and inline above the span: "Built with a MOCK 'M' logo (the real brand mark lands later, per the design)" · "Mock 'M' brand mark — replaced by the real logo later (design note)."

Neither produced a card, and the same is true of the two chat avatars that render the same letter (PlanChangeRail.tsx, and DiscoveryChatRail.tsx via onboarding.chat.assistantInitial in both locale catalogs).

Why no gate fired — two independent misses

1 — the deferral-is-a-card rule does not read a design asset or a source comment. plan-rules/core.md's A DEFERRAL IS A CARD names its surfaces exactly: "In an ADR §, a decision record, a card body, a Boundary / 'what this does NOT change' / 'out of scope' section." Its trigger list is "a later decision" · "not this one" · "its own card" · "left for later" · "stays for now" · "the route stays" · "unchanged" · "deferred" · "we'll revisit" · "whoever picks this up". A design/<area>/design-notes.md is none of those surfaces, and "built now with a mock X — the real Y replaces it later" is none of those phrases — so the check could not fire, and the sentence read as a note rather than as an orphan.

The rule's own §-level limb is the near miss that makes this worth writing down: it already knows that "when the DEFERRING ARTIFACT IS A DOCUMENT, mirroring the deferral onto a card is the ONLY thing that puts it in the plan" — stated of a type: decision card's ADR. A design asset is exactly the same shape (a document, a deliverable of a type: design card, outside the graph), and it was not named.

2 — an "apply X across the app" card enumerates surfaces, and a placeholder lives where the surface list is not looking. MOTIR-1150 (8.3.5, apply the brand mark across the app, done) built its list from the §0 renders in design/brand/design-notes.md: shell, auth, email, public chrome, favicon/manifest, OG. That list answers "where SHOULD the brand appear?". The defect lived at "where is a brand placeholder ALREADY rendering?" — a different question with a different, mechanical answer (git grep for the placeholder). The orb and both avatars are absent from 1150's list, its acceptance criteria and its context refs.

The rule this owes — motir-meta, and its mirror is a sibling card

(a) Widen the deferral rule's SURFACES. A DEFERRAL IS A CARD fires on the same sentence wherever it is written: a card body, an ADR §, a design/<area>/design-notes.md or any design asset, and a source-code comment shipped alongside the placeholder it describes. The discharge is unchanged — create_work_item before the artifact is sealed, and cite the key in the sentence that defers.

(b) Add the PLACEHOLDER phrasings to the trigger list. They are lexical and greppable like the rest: "mock X" · "placeholder" · "stand-in" · "the real Y lands later" · "replaced by … later" · "for now" · "until the real …" — and the tell that separates this family from the others is that the sentence describes the CURRENT artifact rather than a future decision, which is why it reads as documentation instead of as a debt.

(c) Add the inverse-enumeration limb to gate 8's sweep. A card whose verb is apply / roll out / adopt X across the app owes a grep for what X REPLACES, not only an enumeration of where X belongs. The two lists differ exactly where a placeholder is, which is the only place the card can silently under-deliver.

Fix applied (the plan correction, already submitted)

Plan cmt0ou3li00hxi2ph0iowzhp9 proposes, under MOTIR-1343: the mark's re-draw, its approval, the glyph design for the orb + avatars, the geometry landing in components/brand/waveBand.ts, and the swap itself — plus amendments to MOTIR-1343, MOTIR-1815, MOTIR-1822, MOTIR-1823, MOTIR-1344 and MOTIR-2267. Nothing was archived. The cards hang off 1343 rather than MOTIR-1342 or MOTIR-1150 because both are done and we only plan forward.

Acceptance criteria

  • motir-meta/prompts/plan-rules/core.md's A DEFERRAL IS A CARD carries (a) the widened surface list — design assets and source comments named explicitly beside the ADR § and the card body — and (b) the placeholder trigger phrasings, with the "describes the current artifact" tell.
  • motir-meta/prompts/plan-rules/core.md's gate 8 carries (c), the apply-across-the-app inverse-enumeration limb, phrased GENERICALLY — the shipped planner plans other people's products, so no wording may name Motir, its repos or its brand.
  • Each amendment carries its warrant line in the corpus's existing form (incident, date, one-line summary), pointing at this work item.
  • motir-meta/notes.html gains the mistake entry, count bumped, matching the existing .mistake markup: what was assumed, the rung-2 evidence (both quoted sentences, with their file:path), and the lesson.
  • Before writing (a): grep the target on origin/main and quote the result — this card asserts a GAP in core.md, and an asserted absence is a code fact. The same for gate 8 and (c).
  • Landed on a branch + PR against motir-meta — never a direct commit to main.
  • The motir-ai mirror is NOT in this card's scope — it is MOTIR-3176, blocked_by this one, because SHARED_PLANNING_RULES lives in another repo and one subtask is one repo is one PR. Write the wording here so that card can LIFT it without re-deriving intent.

Context refs

  • motir-meta/prompts/plan-rules/core.mdA DEFERRAL IS A CARD (its surfaces and trigger list) and gate 8 (Referrers swept).
  • motir-meta/notes.html — the lesson tier.
  • motir-core/design/ai-chat/design-notes.md § "B — the floating 'M' button" — the deferral, verbatim.
  • motir-core/components/planning/PlanWithAIFab.tsx — the same deferral as a source comment, twice.
  • MOTIR-1150 — the surface enumeration that could not see a placeholder.
  • MOTIR-1343 — the story the correction was planned onto (relates_to).
  • MOTIR-3176 — the SHARED_PLANNING_RULES mirror this rule's second home lands in (blocks).
  • Plan cmt0ou3li00hxi2ph0iowzhp9 — the correction itself.