Motir

Two ways a lesson enters a project's store, and the controls over both: the planner records one automatically when it corrects itself, and a person or their agent adds one deliberately.

The setting

A fourth setting group on the existing AI-planning settings surface: whether this project's planner records what it got wrong. On by default, because the loop is worth having; switchable, because something is writing down conclusions about a customer's work and they should be able to say no.

The copy is the deliverable. A bare toggle labelled "Record planning mistakes" tells a reader nothing about what is stored, who sees it, or what changes if they turn it off — and this is the one setting on the page where the answer is not obvious from the name. It has to say, in the product's voice and without jargon:

• What is captured — when the planner gets something wrong and corrects itself, it writes down the takeaway. Not the work items, not the code: the lesson.
• Where it goes — this project's own store. It is not shared with other projects.
• What it does — later plans for this project are given the relevant ones, so the same mistake is less likely twice.
• What turning it off costs — no new lessons are recorded; the ones already there keep applying until retired.
• Where to look — the list, so the setting and the thing it produces are one step apart.

Write it plainly. "Planning mistakes" is already the clearest available name for the thing; the explanation underneath is where the work is, and it should read like a sentence a person would say.

What the toggle actually gates: the automatic tenant capture path. When it is off, a planning run records no lesson for this project. It does not stop planning bugs being filed, and it does not remove existing lessons.

Both catalogs, en and zh — a setting whose value is its explanation is worse than useless half-translated.

Adding one deliberately

The other half: an add_lesson MCP tool, so a project can teach its planner something without waiting for the planner to get it wrong first. A team that already knows a trap — one they hit last quarter, one that lives in a runbook — has no reason to wait for a planning run to rediscover it.

Tenant scope only, and gated. It writes a lesson bound to this project; there is no argument through which a caller could produce a global one, because the corpus every tenant reads is curated through migrations. It takes the same permission as retiring — both change the standing instructions the planner is given.

The tool description is the deliverable here, for the same reason the copy is above. It is the only briefing the calling agent gets, and it decides whether the store fills with lessons or with notes.

The setting does not gate this tool. Turning off automatic capture says stop drawing your own conclusions about our work; it does not say we may no longer write anything down ourselves. Conflating them would take a control away from the person who asked for a different one.

Acceptance criteria

• A fourth setting group on the AI-planning settings surface, matching the shape of the three already there.
• The setting defaults to ON for existing and new projects, with no migration needed to opt anyone in.
• Turning it off stops automatic tenant lesson capture for that project, asserted at the capture path — not by hiding a control.
• Turning it off does not stop planning bugs being filed and does not disable existing lessons; both asserted.
• The explanation covers all five points above and is reviewed as copy, not as a label.
• Copy lands in en and zh; the catalog-parity gate passes.
• Reading and changing the setting are permission-guarded consistently with the rest of the surface.
• An E2E walks: open settings → read the explanation → turn it off → confirm no lesson is captured → turn it back on.
• An add_lesson MCP tool creates one tenant lesson for the acting project, and the created lesson is retrievable by the planner — asserted against injection, not against the table.
• No caller can create a global lesson through it; refused, not ignored.
• It is gated by the lesson-library-change permission, checked before any upstream call.
• A near-duplicate is refused and names the existing lesson, rather than silently reinforcing it as automatic capture does.
• Turning the setting off does not disable the tool, asserted.

Context refs

• motir-core app/(authed)/settings/project/ai-planning/_components/AiPlanningSettingsEditor.tsx — the three existing groups (aiPlanning.autoPlan, .sprint, .planner) whose shape this follows, including the explanationsLabel boolean as precedent.
• motir-core app/api/projects/[key]/ai-settings/route.ts — the settings API.
• motir-core design/ai-settings/ — the asset the new group is drawn into.
• motir-core lib/mcp/registry.ts, lib/mcp/tools/addComment.ts — the tool surface and the adapter shape.
• motir-ai src/services/lessonService.ts — captureMistake (what the setting gates) and createFromCorrection (what the tool reaches).
• MOTIR-3327 — tenant-only capture; this is the switch on it.
• MOTIR-3329 — the list this setting's copy points at, and the permission keys both halves take.