From 9834dfb7cab3e5c6707acdcbd7ee6d2117e2aeba Mon Sep 17 00:00:00 2001 From: Michael Ganchas Date: Thu, 5 Nov 2026 15:36:38 +0000 Subject: [PATCH 01/12] fix(planning): install planning skills on MetaMask Extension and narrow triggers - Install planning, planning-spec and jira-brief for MetaMask Extension with per-repo overlays. Core stays out of scope. - planning is experimental with no base; it triggers only for ambiguous, large, security-sensitive, performance-sensitive or explicitly requested work. - Security and performance stop for agreement before the edit, with a spec only when also large. - Cheap uncertainty proceeds with a closing note; risk uncertainty stops for a short brief. - Catalog reads every installed mms-* description and follows the matching skill; drop the fixed mms-performance read. - Remove the Jira nudge line; jira-brief reads a ticket when one is identified and planning continues otherwise. --- CHANGELOG.md | 9 +- .../jira-brief/repos/metamask-extension.md | 8 ++ .../jira-brief/repos/metamask-mobile.md | 2 +- domains/planning/skills/jira-brief/skill.md | 2 +- .../planning-spec/repos/metamask-extension.md | 8 ++ .../planning-spec/repos/metamask-mobile.md | 2 +- .../planning/skills/planning-spec/skill.md | 4 +- .../planning/repos/metamask-extension.md | 8 ++ .../skills/planning/repos/metamask-mobile.md | 2 +- domains/planning/skills/planning/skill.md | 113 +++++++++--------- 10 files changed, 96 insertions(+), 62 deletions(-) create mode 100644 domains/planning/skills/jira-brief/repos/metamask-extension.md create mode 100644 domains/planning/skills/planning-spec/repos/metamask-extension.md create mode 100644 domains/planning/skills/planning/repos/metamask-extension.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 6915cacb..1d983cb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,10 +20,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Update the `testing/visual-testing` skill for `@metamask/client-mcp-core` 0.13.1: remove the knowledge store commands and the mandatory knowledge-reuse step, and document the global `--observe` and `--pretty` flags, one-line JSON output, observations without app state, `run-steps` `observe` (replaces `includeObservations`), timed-out calls being cancelled, and one element per ref. Replace the removed `yarn build:test:webpack` script with `yarn build:test`. +- Drop the `A Jira ticket would improve this context.` line from `planning`. When a ticket is identified, `jira-brief` still reads it. When none is identified, planning continues and does not ask for one. +- Stop `planning` before the edit for security-sensitive and performance-sensitive work, even when the ask is fully specified, covered by a ticket, or not large. The pause is one line that names the risk, then agreement. A spec is still only for a large change. +- Tighten `large` for `planning`: only a new product area, or a cross-system design whose scope is not decided. Security, a contract or API change, keyring, vault, auth, migrations, persisted state, a long diff, or several screens is not large by itself and does not get a spec. Cheap uncertainty (whether the result will be kept, or whether an existing spec, plan, or ticket covers the change) proceeds and ends with one confirmation line. Risk uncertainty (security, contract or API, or large, including CI) stops for a one-line short brief and does not recommend a spec. +- Install `planning`, `planning-spec`, and `jira-brief` for MetaMask Extension as well as MetaMask Mobile, with the same rules in both. Core stays out of scope. `planning` stays `maturity: experimental`. When `planning` or `planning-spec` applies, assess every installed `mms-*` skill by its description, read the body on any fit, and follow an `mms-*` skill over a non-`mms-*` skill when both fit. Drop the fixed `mms-performance` read, which does not install for MetaMask Extension; the catalog rule covers each repo's installed performance skills. +- Call `planning` (`mms-planning`) only when scope is ambiguous, the change is large, the work is security-sensitive, or the engineer asks. Keep the name `mms-planning`. Mark it `maturity: experimental` and remove `base: true`, so a default stable sync no longer installs it. An already installed copy keeps the old always-on trigger until a sync that includes `planning` with `--maturity experimental`, or until a prune. A change covered by an existing spec, plan, or ticket with acceptance criteria, and a fully specified security or privacy change that is not large, proceed without a brief; the latter names the risk in one line in the final summary. Once the skill applies, Catalog runs on every path, including mechanical, revert, CI-only, spike, and fully specified, before the edit, brief, or yes/no. Remove the named minimum-routing skill list from `planning` and its reference from `planning-spec`; the catalog rule already reads every installed `mms-*` skill whose area the task touches. Recommend a planning spec only for a large change, now defined as a new product area or a cross-system design with undecided scope; a new design or a contract or API change that is not large gets a brief instead. - Update the MetaMask Mobile performance overlay and animation references for React Native 0.86.x, Expo SDK 57, and Reanimated 4.x with `react-native-worklets`. From a worklet, call `scheduleOnRN` (`runOnJS` is a deprecated alias). Static-ESM tree-shaking stays off. ([#203](https://github.com/MetaMask/skills/pull/203)) - Require every revert yes/no to be one line that names the pull request or commit, the files, and exactly one yes/no question, whether or not security or privacy is involved. A shorter message is not that step. -- Keep a new public method or other contract change on the brief and spec path when the objection is that another package should own the edit. Put that objection in the brief. -- Skip a planning brief for an unkept spike or POC and for routine CI-only work, including a workflow edit that changes how jobs or E2E launch. A CI change that is a new design, a contract or API change, or multi-surface work still stops for a brief and a spec. For a revert of a merged pull request or commit, name the target and files, then ask one yes/no, and name the risk when security or privacy is involved. Recommend a spec for a new design, a contract or API change, or multi-surface work even when the ask is fully specified or single-file; any other fully specified ask gets one line of scope and one yes/no instead of a brief, unless it touches auth, secrets, logs or exports of state, permissions, keyring or vault, migrations, or persisted state, which still gets a brief. Always read the installed skill catalog, including for reverts and fully specified asks. +- Keep a new public method or other contract change on the brief path, not the yes/no, when the objection is that another package should own the edit. Put that objection in the brief. +- Skip a brief for an unkept spike or POC and for routine CI-only work, including a workflow edit that changes how jobs or E2E launch. A CI change that is large or a contract or API change still stops for a brief, and gets a spec recommendation only when it is large. For a revert of a merged pull request or commit, name the target and files, then ask one yes/no, and name the risk when security or privacy is involved. A fully specified ask that is not large, is not a contract or API change, and does not touch auth, secrets, logs or exports of state, permissions, keyring or vault, migrations, or persisted state gets one line of scope and one yes/no instead of a brief. Always read the installed skill catalog, including for reverts and fully specified asks. - Add component-view rules to `testing/mobile-testing` from the Predict flake investigation: clear call history before call-count assertions, re-query after a remount instead of holding a `findBy*` result, keep time-dependent behaviour in unit tests or target-state fixtures, require a named async boundary for any explicit `{ timeout }`, and a Fixing a Flake section (name the cause, reproduce it, prove the fix; a longer timeout alone is not a fix). - Document confirmed Appium interaction-stability patterns in `testing/mobile-testing` (`references/appium-e2e.md`): child readiness, fresh interactive queries, shared open retries, virtualized-list proof, native control state, action postconditions, and single assertions for short-lived alerts. diff --git a/domains/planning/skills/jira-brief/repos/metamask-extension.md b/domains/planning/skills/jira-brief/repos/metamask-extension.md new file mode 100644 index 00000000..c5a9b487 --- /dev/null +++ b/domains/planning/skills/jira-brief/repos/metamask-extension.md @@ -0,0 +1,8 @@ +--- +repo: metamask-extension +parent: jira-brief +--- + +# Jira brief — MetaMask Extension + +This skill installs for MetaMask Mobile and MetaMask Extension. diff --git a/domains/planning/skills/jira-brief/repos/metamask-mobile.md b/domains/planning/skills/jira-brief/repos/metamask-mobile.md index 6973cb8b..9140be17 100644 --- a/domains/planning/skills/jira-brief/repos/metamask-mobile.md +++ b/domains/planning/skills/jira-brief/repos/metamask-mobile.md @@ -5,4 +5,4 @@ parent: jira-brief # Jira brief — MetaMask Mobile -This skill installs only for MetaMask Mobile. +This skill installs for MetaMask Mobile and MetaMask Extension. diff --git a/domains/planning/skills/jira-brief/skill.md b/domains/planning/skills/jira-brief/skill.md index 9263806c..1dc6eafe 100644 --- a/domains/planning/skills/jira-brief/skill.md +++ b/domains/planning/skills/jira-brief/skill.md @@ -33,4 +33,4 @@ Installed name: `mms-jira-brief`. `mms-planning` calls it for ticket identificat 10. Do not copy secrets, tokens, credentials, or customer data into the file. 11. In chat, name the path. Do not paste the file. Do not write to Jira. Do not say that code will not change. -`A Jira ticket would improve this context.` belongs to `mms-planning`. That skill adds the line only when no brief was actually read and the change stops for a brief. A revert does not get that line. This skill does not add that line. +When `mms-planning` delegates and no ticket is identified, return no ticket identified and stop. Do not ask for a ticket. Do not suggest creating one. `mms-planning` then continues. A revert does not call this skill. diff --git a/domains/planning/skills/planning-spec/repos/metamask-extension.md b/domains/planning/skills/planning-spec/repos/metamask-extension.md new file mode 100644 index 00000000..e9f398d4 --- /dev/null +++ b/domains/planning/skills/planning-spec/repos/metamask-extension.md @@ -0,0 +1,8 @@ +--- +repo: metamask-extension +parent: planning-spec +--- + +# Planning spec — MetaMask Extension + +This skill installs for MetaMask Mobile and MetaMask Extension. diff --git a/domains/planning/skills/planning-spec/repos/metamask-mobile.md b/domains/planning/skills/planning-spec/repos/metamask-mobile.md index be21cd0e..df46c80c 100644 --- a/domains/planning/skills/planning-spec/repos/metamask-mobile.md +++ b/domains/planning/skills/planning-spec/repos/metamask-mobile.md @@ -5,4 +5,4 @@ parent: planning-spec # Planning spec — MetaMask Mobile -This skill installs only for MetaMask Mobile. +This skill installs for MetaMask Mobile and MetaMask Extension. diff --git a/domains/planning/skills/planning-spec/skill.md b/domains/planning/skills/planning-spec/skill.md index b8155a95..2fa85272 100644 --- a/domains/planning/skills/planning-spec/skill.md +++ b/domains/planning/skills/planning-spec/skill.md @@ -5,7 +5,7 @@ description: >- when the user asks for a planning spec. Ask one unblocked product or engineering question at a time, the one that most reduces uncertainty, then write one English file at - .specs/spec-XXX-short-description.md in the MetaMask Mobile checkout. Do + .specs/spec-XXX-short-description.md in the MetaMask Mobile or MetaMask Extension checkout. Do not edit product code, and do not say that in chat. Do not write a -pt.md sibling. base: true @@ -27,7 +27,7 @@ Installed name: `mms-planning-spec`. Use it only after `mms-planning` recommends 2. Ask when the question can be stated precisely now, even if the answer is unknown. When an in-scope area cannot be stated precisely because it depends on an open answer, keep it as not yet specified. Do not split that area into questions. When the blocking answer arrives, state any question that is now precise, then ask the unblocked one that most reduces uncertainty. 3. Stop asking when every precise unknown is decided, explicitly deferred, or recorded as an open question, and every remaining in-scope area is not yet specified. State the direction. 4. When the direction is ready, state it and wait. Write the file only after the engineer approves. If they do not approve, ask the next unblocked question. -5. After approval, and before writing, use the same catalog rule as `mms-planning`. Read the installed `mms-*` catalog. Read every skill whose area the spec touches, including a partial fit. Skip a skill only when the spec has no surface for it. Run an explicit performance check. Read `mms-performance` when the change has a performance surface. The named routing list in `mms-planning` is a floor, not an allowlist. Name a matching skill that is unavailable. Do not pretend it was applied. +5. After approval, and before writing, use the same catalog rule as `mms-planning`. Read the installed `mms-*` catalog. Assess every installed `mms-*` skill by its description. Read the body of every skill whose area the spec touches, including a partial fit. Skip a skill only when the spec has no surface for it. Follow an installed `mms-*` skill over a skill outside that catalog when both fit. Name a matching skill that is unavailable. Do not pretend it was applied. 6. Write one English file at `.specs/spec-XXX-short-description.md` in the checkout. `.specs/` is local and not team-shared storage. Do not stage it. Sharing the file is a manual step outside this skill. Numbering is the highest existing `.specs/spec-*.md` plus one. If none exist, start at `001`. The slug is two to five kebab-case words. The H1 is `# spec-XXX: `. diff --git a/domains/planning/skills/planning/repos/metamask-extension.md b/domains/planning/skills/planning/repos/metamask-extension.md new file mode 100644 index 00000000..0c13147a --- /dev/null +++ b/domains/planning/skills/planning/repos/metamask-extension.md @@ -0,0 +1,8 @@ +--- +repo: metamask-extension +parent: planning +--- + +# Planning — MetaMask Extension + +This skill installs for MetaMask Mobile and MetaMask Extension. diff --git a/domains/planning/skills/planning/repos/metamask-mobile.md b/domains/planning/skills/planning/repos/metamask-mobile.md index 441a9569..414e0744 100644 --- a/domains/planning/skills/planning/repos/metamask-mobile.md +++ b/domains/planning/skills/planning/repos/metamask-mobile.md @@ -5,4 +5,4 @@ parent: planning # Planning — MetaMask Mobile -This skill installs only for MetaMask Mobile. +This skill installs for MetaMask Mobile and MetaMask Extension. diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index 15ff6761..0fa7b9db 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -1,37 +1,56 @@ --- name: planning description: >- - Use before the first edit in MetaMask Mobile, including when the user did - not ask for a plan. Decide whether to proceed, write a scope brief, read - Jira through mms-jira-brief, open installed mms-* domain skills, or - recommend mms-planning-spec. A mechanical edit, an unkept spike or POC, - and routine CI-only work proceed. A CI change that is a new design, a - contract or API change, or multi-surface work stops for a brief and a spec. - A revert of a merged pull request or commit states the target and files, - then one yes or no. A spec is only for a new design, a contract or API - change, or multi-surface work. Any other change stops until the engineer - agrees. -base: true -maturity: stable + Use in MetaMask Mobile or MetaMask Extension when scope is ambiguous, the + change is large, the work is security-sensitive or performance-sensitive, + or the engineer asks for mms-planning or a plan. Ambiguous means the ask + does not name the target, the action, and the expected result, or it leaves + an open product or contract decision. Large means only a new product area, + or a cross-system design whose scope is not decided. Security, performance, + a contract or API change, a long diff, or several screens is not large by + itself. Security and performance stop for agreement before the edit, even + when fully specified, and get a spec only when also large. Do not use it + before every edit. When it applies, read the installed mms-* catalog and + every matching skill before the edit, brief, or yes/no. +maturity: experimental --- # Planning -This skill installs as `mms-planning`. Related skills are `mms-planning-spec` and `mms-jira-brief`. Domain skills use their installed `mms-*` names. This skill applies to MetaMask Mobile engineers. Other repositories are out of scope. +This skill installs as `mms-planning`. Related skills are `mms-planning-spec` and `mms-jira-brief`. Domain skills use their installed `mms-*` names. ## Decision order -This is the first procedure. Follow it before the first edit. Do not embed a diagram of this procedure. +When this skill applies, follow this procedure before the first edit of that task. Do not embed a diagram of this procedure. + +### Catalog + +Run this before any edit, brief, revert yes/no, or fully specified yes/no. Mechanical, revert, unkept spike or POC, routine CI-only, and fully specified asks do not skip it. Do not start a later step until this step has run. If a later step is reached before it has run, run it first. + +Read the installed `mms-*` catalog. Assess every installed `mms-*` skill by its description. Read the body of every skill whose area the task touches. A partial or uncertain fit is read. Skip a skill only when the task has no surface for it. When an installed `mms-*` skill and a skill outside that catalog both fit, follow the `mms-*` skill. Prefer an installed skill over restating its guidance. The engineer does not have to name a skill. + +Name a matching skill that is unavailable in this path's output. On a brief, that is the brief. Do not pretend it was applied. Do not block only because it is missing. + +`mms-planning-spec` uses this same catalog rule for the spec it writes. ### 1. Classify A change proceeds without a brief when any of these is true: - It is mechanical. A change is mechanical when it cannot change behavior, a contract, or a risk surface. Formatting, comments, behavior-preserving renames, and copy typos that do not change what the product does are mechanical. -- The engineer will not keep the result. That is a throwaway, exploratory, or disposable spike or POC. A spike or POC the engineer will merge does not proceed without a brief. A spike or POC that touches security or privacy does not proceed without a brief. -- It is routine CI-only: coverage, Jest flags, Sonar, or another workflow edit. Changing how jobs or E2E launch stays on this path. A CI change that is a new design, a contract or API change, or multi-surface work does not use this path. That change stops for a brief and recommends a spec. The brief path reads the catalog and every matching skill before the brief. +- The engineer will not keep the result. That is a throwaway, exploratory, or disposable spike or POC. A spike or POC the engineer will merge does not proceed without a brief. A spike or POC that touches security, privacy, or performance does not proceed without a pause. +- It is routine CI-only: coverage, Jest flags, Sonar, or another workflow edit. Changing how jobs or E2E launch stays on this path. A CI change that is large, a contract or API change, security-sensitive, or performance-sensitive does not use this path. That change stops for a brief and recommends a spec only when it is large. +- The ask points to an existing spec, plan, or ticket whose acceptance criteria cover this change, and the change is not security-sensitive or performance-sensitive. Follow it. Do not recommend another spec, even when the change is large. + +Security-sensitive and performance-sensitive work never use step 3. Stop before the first product edit. Do not recommend a spec unless the change is also large. When the ask is fully specified and not large, the pause is a short brief: one line that names the risk, then `Do you agree, or do you want to discuss something in more detail?` Wait. No scope essay. When the ask is not fully specified, use the brief in step 4. An existing spec, plan, or ticket does not skip this pause. + +Uncertainty splits by whether a wrong edit is cheap to undo. + +Cheap uncertainty is only whether the engineer will keep the result, or whether an existing spec, plan, or ticket covers the change, and only when the change is not security-sensitive or performance-sensitive. Do not stop for a brief. Proceed as in step 3. End the final summary with one line that names that uncertainty and asks the engineer to confirm it. That line does not wait before the edit. + +Risk uncertainty is whether the work is security-sensitive, a contract or API change, or large, including whether CI work is large or a contract or API change. Stop before the first product edit. Write a short brief, not the brief in step 4. The short brief is one line that names the uncertainty. It has no scope essay, no performance, UX, or test sections, and no spec. Then ask `Do you agree, or do you want to discuss something in more detail?` and wait. On agreement, the edit may start. More detail stays stopped. -Uncertainty about whether the result will be kept, or whether CI work is a new design, a contract or API change, or multi-surface work, means the change does not proceed without a brief. Uncertainty about behavior, a contract, or a risk surface means the change is not mechanical. +Uncertainty about behavior, a contract, or a risk surface means the change is not mechanical. A revert of a merged pull request or commit does not use steps 2, 3, or 4. Scope is that original change. The message is one line, whether or not it touches security or privacy. That line names the target pull request or commit, names the files, and asks exactly one yes/no question. When it touches security or privacy, that question names the risk. A shorter message is not this step. Do not offer a menu. Do not write a brief and do not recommend a spec. On yes, edit. Security or privacy means auth, secrets, logs or exports of state, permissions, keyring or vault, migrations, or persisted state. @@ -41,17 +60,13 @@ Apply this step on every path except a revert. Follow `mms-jira-brief` for ticket identification and the brief. That skill owns URL, bare-key, and non-Jira-token identification. -When no brief was actually read, say what was missing. A failure file is not a brief that was read. +When a ticket is identified, read the brief and use it as context. When no ticket is identified, say nothing about Jira and continue. Do not ask for a ticket. Do not suggest creating one. -Add this line only when no brief was actually read and the change stops for a brief. It is not a question and does not wait: - -`A Jira ticket would improve this context.` - -Omit that line when a brief was actually read, when the change proceeds without a brief, when the change is a revert, or when a fully specified ask has no spec trigger and does not touch security or privacy. +When a ticket was identified but the brief was not read, say what was missing. A failure file is not a brief that was read. Do not block on that failure. ### 3. Proceed without a brief -A revert does not use this step. Proceed. Do not show a brief. Do not ask for approval. Do not recommend a spec. Apply the Jira step. Run Checks, then edit. +A revert does not use this step. Security-sensitive and performance-sensitive work do not use this step. Proceed. Do not show a brief. Do not ask for approval. Do not recommend a spec. Apply the Jira step. Run Checks, then edit. ### 4. Stop for a brief @@ -59,30 +74,13 @@ A revert does not use this step. Stop before the first product edit. Do not bloc A fully specified ask names the target, the action, and the expected result, and it leaves no open product or contract decision. -Decide whether a spec trigger applies. Recommend a spec when the work is a new design, a contract or API change, or multi-surface work. Those triggers win over a fully specified ask and over a single-file change. Say why in one line. Do not name `mms-planning-spec` in chat. - -A new public method is a contract or API change. That trigger still stops for a brief and a spec recommendation when the objection is that this repo should not hold the edit (wrong owner, a core package, or an existing API elsewhere). Put that objection in the brief. Do not answer with the objection alone. This does not use the yes/no path. - -A fully specified ask that touches security or privacy, as defined above, stops for a brief instead of this yes/no. A new public method or other contract or API change does not use that yes/no. When no spec trigger applies and the ask is fully specified, and it does not touch security or privacy, this does not stop for a brief. Apply the Jira step and omit the Jira line. Do not write a brief. State scope in one line. Run Checks, then end with one yes/no and wait. Do not offer a menu. Do not use either question below. On yes, the edit may start. - -When a spec trigger applies, the ask is not fully specified, or a fully specified ask touches security or privacy, the change stops for a brief. Apply the Jira step. +Decide whether a spec trigger applies. The only spec trigger is a large change, as defined in When to use. That trigger wins over a fully specified ask. A new design or a contract or API change that is not large gets a brief, not a spec. Security-sensitive work, performance-sensitive work, keyring, vault, auth, migrations, and persisted state are not large by themselves. Do not recommend a spec for them unless the change is also large. Say why in one line. Do not name `mms-planning-spec` in chat. -Read the installed `mms-*` catalog on every change, before the brief or the yes/no. Read every skill whose area the task touches. A partial or uncertain fit is read. Skip a skill only when the task has no surface for it. Prefer an installed skill over restating its guidance. The engineer does not have to name a skill. +A new public method is a contract or API change. A contract or API change stops for a brief and does not use the yes/no path, including when the objection is that this repo should not hold the edit (wrong owner, a core package, or an existing API elsewhere). Put that objection in the brief. Do not answer with the objection alone. Recommend a spec only when that change is also large. -Performance is an explicit check on every change. Read `mms-performance` before the brief or the yes/no when the task has any of these surfaces: screen, list, animation, polling, prefetch, realtime data, heavy image, blur, frequent update, large collection, startup path, account or network switch, selector, context provider, bundle, memory, battery, latency, or profiling. This list is a floor for that skill, not an allowlist of skills. +A fully specified ask that is security-sensitive or performance-sensitive does not use this yes/no. It uses the pause in step 1. A new public method or other contract or API change does not use that yes/no. When no spec trigger applies and the ask is fully specified, and it is not security-sensitive or performance-sensitive, this does not stop for a brief. Apply the Jira step. Do not mention a missing ticket. Do not write a brief. State scope in one line. Run Checks, then end with one yes/no and wait. Do not offer a menu. Do not use either question below. On yes, the edit may start. -Minimum routing, also a floor and not an allowlist: - -- Product-code test strategy reads `mms-mobile-testing`. -- Flag work reads `mms-feature-flags`. -- UI work reads `mms-ui-development`. -- Analytics work reads `mms-analytics`. -- Navigation work reads `mms-navigation`. -- User-facing copy reads `mms-content-guidelines`. - -`mms-planning-spec` uses this same catalog rule for the spec it writes. - -A matching skill that is unavailable is named in the brief. Do not pretend it was applied. Do not block only because it is missing. +When a spec trigger applies, the ask is not fully specified, or the change is a contract or API change, the change stops for a brief. Apply the Jira step. Then brief scope and non-goals. Include performance, security, UX, and tests only when that area can change the work. Omit empty areas. @@ -104,18 +102,25 @@ More detail returns to the brief. Agreement is the point where the edit may star Run these before an edit that proceeds without a brief, before the revert yes/no, before the fully specified yes/no, and before the spec question or the agreement question. Every item that applies is required. A miss goes back to that step. Do not continue with it open. -- Classification says whether the change proceeds without a brief, is a revert, takes the fully specified fast path, or stops for a brief. -- Before the revert yes/no: the message is one line, whether or not there is a security or privacy risk. That line names the target pull request or commit, names the files, and asks exactly one yes/no. A security or privacy revert names the risk in that question. A message that omits the target, the files, or the question is not done. There is no brief, spec, menu, or Jira line. -- The Jira step is done except on a revert. The Jira line is present only when that step requires it. -- A spec trigger is a new design, a contract or API change, or multi-surface work. A new public method is a contract or API change. A spec trigger wins over a fully specified ask, over a single-file change, and over routine CI-only. An objection that another package should own the edit does not remove the trigger. Put that objection in the brief. Routine CI-only proceeds without a brief, including a workflow edit that changes how jobs or E2E launch. CI with a spec trigger stops for a brief, reads the catalog and matching skills, and recommends a spec. -- Before the fully specified yes/no: a fully specified ask with no spec trigger and no security or privacy surface states scope in one line and ends with one yes/no. There is no brief and no spec. A fully specified ask that touches security or privacy does not use this path. A new public method or other contract or API change does not use this path. -- On every path, the catalog was read and each matching skill was read or named missing. On every path, the performance check ran. -- When the change stops for a brief, the brief states scope and non-goals. Performance, security, UX, and tests are present only when that area can change the work. +- [ ] Classification matches step 1: the change proceeds without a brief, is cheap uncertainty, is a revert, takes the fully specified fast path, stops for a short brief, or stops for a brief. +- [ ] Before the revert yes/no: the message is one line, whether or not there is a security or privacy risk. That line names the target pull request or commit, names the files, and asks exactly one yes/no. A security or privacy revert names the risk in that question. A message that omits the target, the files, or the question is not done. There is no brief, spec, or menu. +- [ ] The Jira step is done except on a revert. A ticket that was identified was read. No ticket means no Jira mention and no request to create one. +- [ ] A spec is recommended only as step 4 states: for a large change, and never over an existing spec, plan, or ticket whose acceptance criteria cover the change. Security, a contract or API change, keyring, vault, auth, migrations, or persisted state does not get a spec unless that change is also large. A risk-uncertainty stop is a one-line short brief and does not recommend a spec. +- [ ] Before the fully specified yes/no: a fully specified ask with no spec trigger and no security, privacy, or performance surface states scope in one line and ends with one yes/no. There is no brief and no spec. A fully specified ask that is security-sensitive or performance-sensitive does not use this path. It stops for the one-line pause in step 1 and waits. A new public method or other contract or API change does not use this path. +- [ ] On every path, including mechanical, revert, unkept spike or POC, routine CI-only, and fully specified yes/no, the installed `mms-*` catalog was read and each matching skill was read or named missing. A path that edits, asks yes/no, or writes a brief without that read is not done. +- [ ] Cheap uncertainty proceeds only when the change is not security-sensitive or performance-sensitive. The final summary ends with one line that names the uncertainty and asks the engineer to confirm it. There is no brief and no wait before the edit. +- [ ] Security-sensitive or performance-sensitive work stops before the edit, even when fully specified, covered by a ticket, or not large. The fully specified pause is one line that names the risk, then the agreement question. No spec unless the change is also large. +- [ ] When the change stops for a brief, the brief states scope and non-goals. Performance, security, UX, and tests are present only when that area can change the work. A short brief is one line and does not use those sections. ## When to use -- Before the first edit on any MetaMask Mobile change, including when the user did not ask for a plan. -- When the work might be mechanical, a revert, or might need a brief, Jira context, a domain skill, or a spec. +- Scope is ambiguous. The ask does not name the target, the action, and the expected result, or it leaves an open product or contract decision. +- The change is large. Large means only a new product area, or a cross-system design whose scope is not decided. A long diff, several screens, security, a contract or API change, keyring, vault, auth, migrations, or persisted state is not large by itself. +- The work is security-sensitive. That means auth, secrets, logs or exports of state, permissions, keyring or vault, migrations, or persisted state. Stop for agreement before the edit. This is not large by itself. +- The work is performance-sensitive. That means a screen, list, animation, polling, prefetch, realtime data, startup, account or network switch, selector, context provider, bundle, memory, battery, latency, or profiling. Stop for agreement before the edit. This is not large by itself. A copy typo, comment, or behavior-preserving rename is not performance-sensitive. +- The engineer asks for `mms-planning`, a plan, or a planning spec. + +Do not use this skill before every edit. ## Workflow From 4159e02a0006ee53ffc525e597f1f7448fd684bc Mon Sep 17 00:00:00 2001 From: Michael Ganchas Date: Thu, 5 Nov 2026 15:38:23 +0000 Subject: [PATCH 02/12] fix(planning): drop -pt.md reference from planning-spec --- domains/planning/skills/planning-spec/skill.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/domains/planning/skills/planning-spec/skill.md b/domains/planning/skills/planning-spec/skill.md index 2fa85272..b371176b 100644 --- a/domains/planning/skills/planning-spec/skill.md +++ b/domains/planning/skills/planning-spec/skill.md @@ -6,8 +6,7 @@ description: >- engineering question at a time, the one that most reduces uncertainty, then write one English file at .specs/spec-XXX-short-description.md in the MetaMask Mobile or MetaMask Extension checkout. Do - not edit product code, and do not say that in chat. Do not write a -pt.md - sibling. + not edit product code, and do not say that in chat. base: true maturity: stable --- From 9d2bc38fbf3b0dfe407444392750c69502aa215e Mon Sep 17 00:00:00 2001 From: Michael Ganchas Date: Thu, 5 Nov 2026 15:47:14 +0000 Subject: [PATCH 03/12] fix(planning): drop related-skills line from planning skill --- domains/planning/skills/planning/skill.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index 0fa7b9db..52ad97e5 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -17,8 +17,6 @@ maturity: experimental # Planning -This skill installs as `mms-planning`. Related skills are `mms-planning-spec` and `mms-jira-brief`. Domain skills use their installed `mms-*` names. - ## Decision order When this skill applies, follow this procedure before the first edit of that task. Do not embed a diagram of this procedure. From 7613162c0786f02f1d03fb9fe25f6504913b2ad5 Mon Sep 17 00:00:00 2001 From: Michael Ganchas Date: Thu, 5 Nov 2026 15:59:18 +0000 Subject: [PATCH 04/12] fix(planning): mark planning-spec and jira-brief experimental, narrow performance trigger Narrow the performance-sensitive trigger from any screen to a screen's render or data path. Mark planning-spec and jira-brief experimental so they no longer install without planning. Fold the planning changelog entries and log the dropped -pt.md instruction. --- CHANGELOG.md | 7 ++----- domains/planning/skills/jira-brief/skill.md | 3 +-- domains/planning/skills/planning-spec/skill.md | 7 +++---- domains/planning/skills/planning/skill.md | 2 +- 4 files changed, 7 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d983cb8..77c7c10c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,11 +20,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Update the `testing/visual-testing` skill for `@metamask/client-mcp-core` 0.13.1: remove the knowledge store commands and the mandatory knowledge-reuse step, and document the global `--observe` and `--pretty` flags, one-line JSON output, observations without app state, `run-steps` `observe` (replaces `includeObservations`), timed-out calls being cancelled, and one element per ref. Replace the removed `yarn build:test:webpack` script with `yarn build:test`. -- Drop the `A Jira ticket would improve this context.` line from `planning`. When a ticket is identified, `jira-brief` still reads it. When none is identified, planning continues and does not ask for one. -- Stop `planning` before the edit for security-sensitive and performance-sensitive work, even when the ask is fully specified, covered by a ticket, or not large. The pause is one line that names the risk, then agreement. A spec is still only for a large change. -- Tighten `large` for `planning`: only a new product area, or a cross-system design whose scope is not decided. Security, a contract or API change, keyring, vault, auth, migrations, persisted state, a long diff, or several screens is not large by itself and does not get a spec. Cheap uncertainty (whether the result will be kept, or whether an existing spec, plan, or ticket covers the change) proceeds and ends with one confirmation line. Risk uncertainty (security, contract or API, or large, including CI) stops for a one-line short brief and does not recommend a spec. -- Install `planning`, `planning-spec`, and `jira-brief` for MetaMask Extension as well as MetaMask Mobile, with the same rules in both. Core stays out of scope. `planning` stays `maturity: experimental`. When `planning` or `planning-spec` applies, assess every installed `mms-*` skill by its description, read the body on any fit, and follow an `mms-*` skill over a non-`mms-*` skill when both fit. Drop the fixed `mms-performance` read, which does not install for MetaMask Extension; the catalog rule covers each repo's installed performance skills. -- Call `planning` (`mms-planning`) only when scope is ambiguous, the change is large, the work is security-sensitive, or the engineer asks. Keep the name `mms-planning`. Mark it `maturity: experimental` and remove `base: true`, so a default stable sync no longer installs it. An already installed copy keeps the old always-on trigger until a sync that includes `planning` with `--maturity experimental`, or until a prune. A change covered by an existing spec, plan, or ticket with acceptance criteria, and a fully specified security or privacy change that is not large, proceed without a brief; the latter names the risk in one line in the final summary. Once the skill applies, Catalog runs on every path, including mechanical, revert, CI-only, spike, and fully specified, before the edit, brief, or yes/no. Remove the named minimum-routing skill list from `planning` and its reference from `planning-spec`; the catalog rule already reads every installed `mms-*` skill whose area the task touches. Recommend a planning spec only for a large change, now defined as a new product area or a cross-system design with undecided scope; a new design or a contract or API change that is not large gets a brief instead. +- Narrow `planning` (`mms-planning`) to run only when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, or the engineer asks. Security and performance stop for agreement before the edit, even when fully specified, and get a spec only when also large. `large` means only a new product area or a cross-system design whose scope is not decided. Cheap uncertainty proceeds with one confirmation line; risk uncertainty stops for a one-line short brief. Once the skill applies, the catalog is read on every path before the edit, brief, or yes/no. Drop the `A Jira ticket would improve this context.` line; `jira-brief` still reads a ticket when one is identified. Mark `planning`, `planning-spec`, and `jira-brief` `maturity: experimental` and remove `base: true`, so a default stable sync installs none of them. An installed copy keeps the old always-on trigger until a sync with `--maturity experimental` or a prune. Drop the `-pt.md` sibling instruction from `planning-spec`. ([#219](https://github.com/MetaMask/skills/pull/219)) +- Install `planning`, `planning-spec`, and `jira-brief` for MetaMask Extension as well as MetaMask Mobile, with the same rules in both repos. Core stays out of scope. Assess every installed `mms-*` skill by its description, follow an `mms-*` skill over a non-`mms-*` one when both fit, and drop the fixed `mms-performance` read, which does not install for MetaMask Extension. ([#219](https://github.com/MetaMask/skills/pull/219)) - Update the MetaMask Mobile performance overlay and animation references for React Native 0.86.x, Expo SDK 57, and Reanimated 4.x with `react-native-worklets`. From a worklet, call `scheduleOnRN` (`runOnJS` is a deprecated alias). Static-ESM tree-shaking stays off. ([#203](https://github.com/MetaMask/skills/pull/203)) - Require every revert yes/no to be one line that names the pull request or commit, the files, and exactly one yes/no question, whether or not security or privacy is involved. A shorter message is not that step. - Keep a new public method or other contract change on the brief path, not the yes/no, when the objection is that another package should own the edit. Put that objection in the brief. diff --git a/domains/planning/skills/jira-brief/skill.md b/domains/planning/skills/jira-brief/skill.md index 1dc6eafe..882f8276 100644 --- a/domains/planning/skills/jira-brief/skill.md +++ b/domains/planning/skills/jira-brief/skill.md @@ -6,8 +6,7 @@ description: >- .briefs/.md with the Goal, Decisions Already Made, Open Decisions, and Code Surfaces sections. Name the path in chat. Do not paste the file or write to Jira. Do not edit product code, and do not say that in chat. -base: true -maturity: stable +maturity: experimental --- # Jira brief diff --git a/domains/planning/skills/planning-spec/skill.md b/domains/planning/skills/planning-spec/skill.md index b371176b..d25a2b7b 100644 --- a/domains/planning/skills/planning-spec/skill.md +++ b/domains/planning/skills/planning-spec/skill.md @@ -5,10 +5,9 @@ description: >- when the user asks for a planning spec. Ask one unblocked product or engineering question at a time, the one that most reduces uncertainty, then write one English file at - .specs/spec-XXX-short-description.md in the MetaMask Mobile or MetaMask Extension checkout. Do - not edit product code, and do not say that in chat. -base: true -maturity: stable + .specs/spec-XXX-short-description.md in the MetaMask Mobile or MetaMask + Extension checkout. Do not edit product code, and do not say that in chat. +maturity: experimental --- # Planning spec diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index 52ad97e5..d2496087 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -115,7 +115,7 @@ Run these before an edit that proceeds without a brief, before the revert yes/no - Scope is ambiguous. The ask does not name the target, the action, and the expected result, or it leaves an open product or contract decision. - The change is large. Large means only a new product area, or a cross-system design whose scope is not decided. A long diff, several screens, security, a contract or API change, keyring, vault, auth, migrations, or persisted state is not large by itself. - The work is security-sensitive. That means auth, secrets, logs or exports of state, permissions, keyring or vault, migrations, or persisted state. Stop for agreement before the edit. This is not large by itself. -- The work is performance-sensitive. That means a screen, list, animation, polling, prefetch, realtime data, startup, account or network switch, selector, context provider, bundle, memory, battery, latency, or profiling. Stop for agreement before the edit. This is not large by itself. A copy typo, comment, or behavior-preserving rename is not performance-sensitive. +- The work is performance-sensitive. That means a screen's render or data path, list, animation, polling, prefetch, realtime data, startup, account or network switch, selector, context provider, bundle, memory, battery, latency, or profiling. Stop for agreement before the edit. This is not large by itself. A copy typo, comment, or behavior-preserving rename is not performance-sensitive. - The engineer asks for `mms-planning`, a plan, or a planning spec. Do not use this skill before every edit. From 262d2f8c06a4ca1930b68d0fd6507c38c29a110c Mon Sep 17 00:00:00 2001 From: Michael Ganchas Date: Thu, 5 Nov 2026 16:14:46 +0000 Subject: [PATCH 05/12] fix(planning): treat only a new or changed selector as performance-sensitive Reading an existing selector was pausing fully specified UI that only displays data already in the store. --- CHANGELOG.md | 2 +- domains/planning/skills/planning/skill.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 77c7c10c..3a9299ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Update the `testing/visual-testing` skill for `@metamask/client-mcp-core` 0.13.1: remove the knowledge store commands and the mandatory knowledge-reuse step, and document the global `--observe` and `--pretty` flags, one-line JSON output, observations without app state, `run-steps` `observe` (replaces `includeObservations`), timed-out calls being cancelled, and one element per ref. Replace the removed `yarn build:test:webpack` script with `yarn build:test`. -- Narrow `planning` (`mms-planning`) to run only when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, or the engineer asks. Security and performance stop for agreement before the edit, even when fully specified, and get a spec only when also large. `large` means only a new product area or a cross-system design whose scope is not decided. Cheap uncertainty proceeds with one confirmation line; risk uncertainty stops for a one-line short brief. Once the skill applies, the catalog is read on every path before the edit, brief, or yes/no. Drop the `A Jira ticket would improve this context.` line; `jira-brief` still reads a ticket when one is identified. Mark `planning`, `planning-spec`, and `jira-brief` `maturity: experimental` and remove `base: true`, so a default stable sync installs none of them. An installed copy keeps the old always-on trigger until a sync with `--maturity experimental` or a prune. Drop the `-pt.md` sibling instruction from `planning-spec`. ([#219](https://github.com/MetaMask/skills/pull/219)) +- Narrow `planning` (`mms-planning`) to run only when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, or the engineer asks. Security and performance stop for agreement before the edit, even when fully specified, and get a spec only when also large. Reading an existing selector is not performance-sensitive; a new or changed selector is. `large` means only a new product area or a cross-system design whose scope is not decided. Cheap uncertainty proceeds with one confirmation line; risk uncertainty stops for a one-line short brief. Once the skill applies, the catalog is read on every path before the edit, brief, or yes/no. Drop the `A Jira ticket would improve this context.` line; `jira-brief` still reads a ticket when one is identified. Mark `planning`, `planning-spec`, and `jira-brief` `maturity: experimental` and remove `base: true`, so a default stable sync installs none of them. An installed copy keeps the old always-on trigger until a sync with `--maturity experimental` or a prune. Drop the `-pt.md` sibling instruction from `planning-spec`. ([#219](https://github.com/MetaMask/skills/pull/219)) - Install `planning`, `planning-spec`, and `jira-brief` for MetaMask Extension as well as MetaMask Mobile, with the same rules in both repos. Core stays out of scope. Assess every installed `mms-*` skill by its description, follow an `mms-*` skill over a non-`mms-*` one when both fit, and drop the fixed `mms-performance` read, which does not install for MetaMask Extension. ([#219](https://github.com/MetaMask/skills/pull/219)) - Update the MetaMask Mobile performance overlay and animation references for React Native 0.86.x, Expo SDK 57, and Reanimated 4.x with `react-native-worklets`. From a worklet, call `scheduleOnRN` (`runOnJS` is a deprecated alias). Static-ESM tree-shaking stays off. ([#203](https://github.com/MetaMask/skills/pull/203)) - Require every revert yes/no to be one line that names the pull request or commit, the files, and exactly one yes/no question, whether or not security or privacy is involved. A shorter message is not that step. diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index d2496087..877a0041 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -115,7 +115,7 @@ Run these before an edit that proceeds without a brief, before the revert yes/no - Scope is ambiguous. The ask does not name the target, the action, and the expected result, or it leaves an open product or contract decision. - The change is large. Large means only a new product area, or a cross-system design whose scope is not decided. A long diff, several screens, security, a contract or API change, keyring, vault, auth, migrations, or persisted state is not large by itself. - The work is security-sensitive. That means auth, secrets, logs or exports of state, permissions, keyring or vault, migrations, or persisted state. Stop for agreement before the edit. This is not large by itself. -- The work is performance-sensitive. That means a screen's render or data path, list, animation, polling, prefetch, realtime data, startup, account or network switch, selector, context provider, bundle, memory, battery, latency, or profiling. Stop for agreement before the edit. This is not large by itself. A copy typo, comment, or behavior-preserving rename is not performance-sensitive. +- The work is performance-sensitive. That means a screen's render or data path, list, animation, polling, prefetch, realtime data, startup, account or network switch, a new or changed selector, context provider, bundle, memory, battery, latency, or profiling. Stop for agreement before the edit. This is not large by itself. A copy typo, comment, or behavior-preserving rename is not performance-sensitive. - The engineer asks for `mms-planning`, a plan, or a planning spec. Do not use this skill before every edit. From acc8af42e60bfbba9402e475e85d8d5f9d36e0e4 Mon Sep 17 00:00:00 2001 From: Michael Ganchas Date: Thu, 5 Nov 2026 16:16:57 +0000 Subject: [PATCH 06/12] fix(planning): do not pause for reading an existing selector A screen render still counted as performance-sensitive when it only showed a value already in the store. A new or changed selector still stops. --- CHANGELOG.md | 2 +- domains/planning/skills/planning/skill.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a9299ad..d26feeef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Update the `testing/visual-testing` skill for `@metamask/client-mcp-core` 0.13.1: remove the knowledge store commands and the mandatory knowledge-reuse step, and document the global `--observe` and `--pretty` flags, one-line JSON output, observations without app state, `run-steps` `observe` (replaces `includeObservations`), timed-out calls being cancelled, and one element per ref. Replace the removed `yarn build:test:webpack` script with `yarn build:test`. -- Narrow `planning` (`mms-planning`) to run only when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, or the engineer asks. Security and performance stop for agreement before the edit, even when fully specified, and get a spec only when also large. Reading an existing selector is not performance-sensitive; a new or changed selector is. `large` means only a new product area or a cross-system design whose scope is not decided. Cheap uncertainty proceeds with one confirmation line; risk uncertainty stops for a one-line short brief. Once the skill applies, the catalog is read on every path before the edit, brief, or yes/no. Drop the `A Jira ticket would improve this context.` line; `jira-brief` still reads a ticket when one is identified. Mark `planning`, `planning-spec`, and `jira-brief` `maturity: experimental` and remove `base: true`, so a default stable sync installs none of them. An installed copy keeps the old always-on trigger until a sync with `--maturity experimental` or a prune. Drop the `-pt.md` sibling instruction from `planning-spec`. ([#219](https://github.com/MetaMask/skills/pull/219)) +- Narrow `planning` (`mms-planning`) to run only when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, or the engineer asks. Security and performance stop for agreement before the edit, even when fully specified, and get a spec only when also large. Reading an existing selector to show a value already in the store is not performance-sensitive, even on a screen. A new or changed selector is. `large` means only a new product area or a cross-system design whose scope is not decided. Cheap uncertainty proceeds with one confirmation line; risk uncertainty stops for a one-line short brief. Once the skill applies, the catalog is read on every path before the edit, brief, or yes/no. Drop the `A Jira ticket would improve this context.` line; `jira-brief` still reads a ticket when one is identified. Mark `planning`, `planning-spec`, and `jira-brief` `maturity: experimental` and remove `base: true`, so a default stable sync installs none of them. An installed copy keeps the old always-on trigger until a sync with `--maturity experimental` or a prune. Drop the `-pt.md` sibling instruction from `planning-spec`. ([#219](https://github.com/MetaMask/skills/pull/219)) - Install `planning`, `planning-spec`, and `jira-brief` for MetaMask Extension as well as MetaMask Mobile, with the same rules in both repos. Core stays out of scope. Assess every installed `mms-*` skill by its description, follow an `mms-*` skill over a non-`mms-*` one when both fit, and drop the fixed `mms-performance` read, which does not install for MetaMask Extension. ([#219](https://github.com/MetaMask/skills/pull/219)) - Update the MetaMask Mobile performance overlay and animation references for React Native 0.86.x, Expo SDK 57, and Reanimated 4.x with `react-native-worklets`. From a worklet, call `scheduleOnRN` (`runOnJS` is a deprecated alias). Static-ESM tree-shaking stays off. ([#203](https://github.com/MetaMask/skills/pull/203)) - Require every revert yes/no to be one line that names the pull request or commit, the files, and exactly one yes/no question, whether or not security or privacy is involved. A shorter message is not that step. diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index 877a0041..b79b97a0 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -115,7 +115,7 @@ Run these before an edit that proceeds without a brief, before the revert yes/no - Scope is ambiguous. The ask does not name the target, the action, and the expected result, or it leaves an open product or contract decision. - The change is large. Large means only a new product area, or a cross-system design whose scope is not decided. A long diff, several screens, security, a contract or API change, keyring, vault, auth, migrations, or persisted state is not large by itself. - The work is security-sensitive. That means auth, secrets, logs or exports of state, permissions, keyring or vault, migrations, or persisted state. Stop for agreement before the edit. This is not large by itself. -- The work is performance-sensitive. That means a screen's render or data path, list, animation, polling, prefetch, realtime data, startup, account or network switch, a new or changed selector, context provider, bundle, memory, battery, latency, or profiling. Stop for agreement before the edit. This is not large by itself. A copy typo, comment, or behavior-preserving rename is not performance-sensitive. +- The work is performance-sensitive. That means a screen's render or data path, list, animation, polling, prefetch, realtime data, startup, account or network switch, a new or changed selector, context provider, bundle, memory, battery, latency, or profiling. Stop for agreement before the edit. This is not large by itself. A copy typo, comment, behavior-preserving rename, or reading an existing selector to show a value already in the store, is not performance-sensitive. - The engineer asks for `mms-planning`, a plan, or a planning spec. Do not use this skill before every edit. From 1cbb8fa149227e657330b8474f76ea05afbecbcf Mon Sep 17 00:00:00 2001 From: Michael Ganchas Date: Thu, 5 Nov 2026 16:27:57 +0000 Subject: [PATCH 07/12] fix(planning): stop when performance sensitivity is uncertain Treat uncertainty about performance as risk uncertainty. On Mobile, read mms-performance when the work is performance-sensitive. --- CHANGELOG.md | 2 +- domains/planning/skills/planning/repos/metamask-mobile.md | 2 ++ domains/planning/skills/planning/skill.md | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d26feeef..98201add 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Update the `testing/visual-testing` skill for `@metamask/client-mcp-core` 0.13.1: remove the knowledge store commands and the mandatory knowledge-reuse step, and document the global `--observe` and `--pretty` flags, one-line JSON output, observations without app state, `run-steps` `observe` (replaces `includeObservations`), timed-out calls being cancelled, and one element per ref. Replace the removed `yarn build:test:webpack` script with `yarn build:test`. -- Narrow `planning` (`mms-planning`) to run only when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, or the engineer asks. Security and performance stop for agreement before the edit, even when fully specified, and get a spec only when also large. Reading an existing selector to show a value already in the store is not performance-sensitive, even on a screen. A new or changed selector is. `large` means only a new product area or a cross-system design whose scope is not decided. Cheap uncertainty proceeds with one confirmation line; risk uncertainty stops for a one-line short brief. Once the skill applies, the catalog is read on every path before the edit, brief, or yes/no. Drop the `A Jira ticket would improve this context.` line; `jira-brief` still reads a ticket when one is identified. Mark `planning`, `planning-spec`, and `jira-brief` `maturity: experimental` and remove `base: true`, so a default stable sync installs none of them. An installed copy keeps the old always-on trigger until a sync with `--maturity experimental` or a prune. Drop the `-pt.md` sibling instruction from `planning-spec`. ([#219](https://github.com/MetaMask/skills/pull/219)) +- Narrow `planning` (`mms-planning`) to run only when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, or the engineer asks. Security and performance stop for agreement before the edit, even when fully specified, and get a spec only when also large. Reading an existing selector to show a value already in the store is not performance-sensitive, even on a screen. A new or changed selector is. `large` means only a new product area or a cross-system design whose scope is not decided. Cheap uncertainty proceeds with one confirmation line; risk uncertainty stops for a one-line short brief. Uncertainty about whether the work is performance-sensitive is risk uncertainty. On MetaMask Mobile, read `mms-performance` when the work is performance-sensitive. Once the skill applies, the catalog is read on every path before the edit, brief, or yes/no. Drop the `A Jira ticket would improve this context.` line; `jira-brief` still reads a ticket when one is identified. Mark `planning`, `planning-spec`, and `jira-brief` `maturity: experimental` and remove `base: true`, so a default stable sync installs none of them. An installed copy keeps the old always-on trigger until a sync with `--maturity experimental` or a prune. Drop the `-pt.md` sibling instruction from `planning-spec`. ([#219](https://github.com/MetaMask/skills/pull/219)) - Install `planning`, `planning-spec`, and `jira-brief` for MetaMask Extension as well as MetaMask Mobile, with the same rules in both repos. Core stays out of scope. Assess every installed `mms-*` skill by its description, follow an `mms-*` skill over a non-`mms-*` one when both fit, and drop the fixed `mms-performance` read, which does not install for MetaMask Extension. ([#219](https://github.com/MetaMask/skills/pull/219)) - Update the MetaMask Mobile performance overlay and animation references for React Native 0.86.x, Expo SDK 57, and Reanimated 4.x with `react-native-worklets`. From a worklet, call `scheduleOnRN` (`runOnJS` is a deprecated alias). Static-ESM tree-shaking stays off. ([#203](https://github.com/MetaMask/skills/pull/203)) - Require every revert yes/no to be one line that names the pull request or commit, the files, and exactly one yes/no question, whether or not security or privacy is involved. A shorter message is not that step. diff --git a/domains/planning/skills/planning/repos/metamask-mobile.md b/domains/planning/skills/planning/repos/metamask-mobile.md index 414e0744..c3f6ccfd 100644 --- a/domains/planning/skills/planning/repos/metamask-mobile.md +++ b/domains/planning/skills/planning/repos/metamask-mobile.md @@ -6,3 +6,5 @@ parent: planning # Planning — MetaMask Mobile This skill installs for MetaMask Mobile and MetaMask Extension. + +When the work is performance-sensitive, read `mms-performance` before the edit, brief, or yes/no. diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index b79b97a0..76206ac3 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -46,7 +46,7 @@ Uncertainty splits by whether a wrong edit is cheap to undo. Cheap uncertainty is only whether the engineer will keep the result, or whether an existing spec, plan, or ticket covers the change, and only when the change is not security-sensitive or performance-sensitive. Do not stop for a brief. Proceed as in step 3. End the final summary with one line that names that uncertainty and asks the engineer to confirm it. That line does not wait before the edit. -Risk uncertainty is whether the work is security-sensitive, a contract or API change, or large, including whether CI work is large or a contract or API change. Stop before the first product edit. Write a short brief, not the brief in step 4. The short brief is one line that names the uncertainty. It has no scope essay, no performance, UX, or test sections, and no spec. Then ask `Do you agree, or do you want to discuss something in more detail?` and wait. On agreement, the edit may start. More detail stays stopped. +Risk uncertainty is whether the work is security-sensitive, performance-sensitive, a contract or API change, or large, including whether CI work is large or a contract or API change. Stop before the first product edit. Write a short brief, not the brief in step 4. The short brief is one line that names the uncertainty. It has no scope essay, no performance, UX, or test sections, and no spec. Then ask `Do you agree, or do you want to discuss something in more detail?` and wait. On agreement, the edit may start. More detail stays stopped. Uncertainty about behavior, a contract, or a risk surface means the change is not mechanical. From 2af385ddf7309e1606fe901358c8c9756cf47559 Mon Sep 17 00:00:00 2001 From: mganchas Date: Fri, 6 Nov 2026 13:51:40 +0000 Subject: [PATCH 08/12] Update domains/planning/skills/planning/skill.md Co-authored-by: Nico MASSART --- domains/planning/skills/planning/skill.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index 76206ac3..b6e2797c 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -9,7 +9,7 @@ description: >- or a cross-system design whose scope is not decided. Security, performance, a contract or API change, a long diff, or several screens is not large by itself. Security and performance stop for agreement before the edit, even - when fully specified, and get a spec only when also large. Do not use it + itself. Contract or API changes require a brief. Security and performance stop for agreement before the edit, even when fully specified. Recommend a spec only when the change is also large. Do not use it before every edit. When it applies, read the installed mms-* catalog and every matching skill before the edit, brief, or yes/no. maturity: experimental From 2d6e16260fb81b5c84c24fa3dc21f2477a64c7ba Mon Sep 17 00:00:00 2001 From: mganchas Date: Fri, 6 Nov 2026 13:51:49 +0000 Subject: [PATCH 09/12] Update domains/planning/skills/planning/skill.md Co-authored-by: Nico MASSART --- domains/planning/skills/planning/skill.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index b6e2797c..b4083791 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -3,7 +3,7 @@ name: planning description: >- Use in MetaMask Mobile or MetaMask Extension when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, - or the engineer asks for mms-planning or a plan. Ambiguous means the ask + a contract or API is being changed, or the engineer asks for mms-planning or a plan does not name the target, the action, and the expected result, or it leaves an open product or contract decision. Large means only a new product area, or a cross-system design whose scope is not decided. Security, performance, From 6b839fa5d015adedfe2c7e6be64de75cf13f05ad Mon Sep 17 00:00:00 2001 From: mganchas Date: Fri, 6 Nov 2026 13:52:12 +0000 Subject: [PATCH 10/12] Update domains/planning/skills/planning/skill.md Co-authored-by: Nico MASSART --- domains/planning/skills/planning/skill.md | 1 + 1 file changed, 1 insertion(+) diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index b4083791..419574a6 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -114,6 +114,7 @@ Run these before an edit that proceeds without a brief, before the revert yes/no - Scope is ambiguous. The ask does not name the target, the action, and the expected result, or it leaves an open product or contract decision. - The change is large. Large means only a new product area, or a cross-system design whose scope is not decided. A long diff, several screens, security, a contract or API change, keyring, vault, auth, migrations, or persisted state is not large by itself. +- The change introduces or modifies a public contract or API, including adding a public method. Stop for a brief, even when the change is fully specified. Recommend a spec only when the change is also large. - The work is security-sensitive. That means auth, secrets, logs or exports of state, permissions, keyring or vault, migrations, or persisted state. Stop for agreement before the edit. This is not large by itself. - The work is performance-sensitive. That means a screen's render or data path, list, animation, polling, prefetch, realtime data, startup, account or network switch, a new or changed selector, context provider, bundle, memory, battery, latency, or profiling. Stop for agreement before the edit. This is not large by itself. A copy typo, comment, behavior-preserving rename, or reading an existing selector to show a value already in the store, is not performance-sensitive. - The engineer asks for `mms-planning`, a plan, or a planning spec. From 713853fe7cf7e6d36090b632b5a6b02383722adf Mon Sep 17 00:00:00 2001 From: mganchas Date: Fri, 6 Nov 2026 14:01:42 +0000 Subject: [PATCH 11/12] Update domains/planning/skills/planning/skill.md Co-authored-by: Nico MASSART --- domains/planning/skills/planning/skill.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index 419574a6..d3460499 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -23,7 +23,7 @@ When this skill applies, follow this procedure before the first edit of that tas ### Catalog -Run this before any edit, brief, revert yes/no, or fully specified yes/no. Mechanical, revert, unkept spike or POC, routine CI-only, and fully specified asks do not skip it. Do not start a later step until this step has run. If a later step is reached before it has run, run it first. +When `mms-planning` is triggered, run this catalog step before any edit, brief, or approval question. This applies to every execution path, including mechanical changes, reverts, spikes or POCs, routine CI-only work, and fully specified requests. Do not proceed to another step until the catalog check is complete. Read the installed `mms-*` catalog. Assess every installed `mms-*` skill by its description. Read the body of every skill whose area the task touches. A partial or uncertain fit is read. Skip a skill only when the task has no surface for it. When an installed `mms-*` skill and a skill outside that catalog both fit, follow the `mms-*` skill. Prefer an installed skill over restating its guidance. The engineer does not have to name a skill. From 1d402d661ca2851f1c6239b6e122be9c78e00f8a Mon Sep 17 00:00:00 2001 From: Michael Ganchas Date: Fri, 6 Nov 2026 14:20:53 +0000 Subject: [PATCH 12/12] fix(planning): repair the description and keep the contract trigger The accepted description edit dropped the ambiguous-scope sentence and repeated the security line. Contract or API changes stay a trigger and stop for a brief. The catalog still runs first if a later step starts early. --- CHANGELOG.md | 2 +- domains/planning/skills/planning/skill.md | 22 ++++++++++++---------- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0bd86675..8df7c7c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,7 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Update the `testing/mobile-visual-testing` skill for `@metamask/client-mcp-core` 0.13.1 and `@metamask/device-mcp` 0.7.0: remove the knowledge store commands, the knowledge-reuse step and the `--goal` / `--flow-tags` launch flags, and document the global `--observe` and `--pretty` flags, one-line JSON output, observations without app state, the partial mobile `get-state`, `run-steps` `observe` (replaces `includeObservations`) and the 30 s `batchTimeoutMs` cap, timed-out calls being cancelled, calling `node_modules/.bin/mm` directly, and the Android `helper-first` snapshot default. - Update the `testing/visual-testing` skill for `@metamask/client-mcp-core` 0.13.1: remove the knowledge store commands and the mandatory knowledge-reuse step, and document the global `--observe` and `--pretty` flags, one-line JSON output, observations without app state, `run-steps` `observe` (replaces `includeObservations`), timed-out calls being cancelled, and one element per ref. Replace the removed `yarn build:test:webpack` script with `yarn build:test`. -- Narrow `planning` (`mms-planning`) to run only when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, or the engineer asks. Security and performance stop for agreement before the edit, even when fully specified, and get a spec only when also large. Reading an existing selector to show a value already in the store is not performance-sensitive, even on a screen. A new or changed selector is. `large` means only a new product area or a cross-system design whose scope is not decided. Cheap uncertainty proceeds with one confirmation line; risk uncertainty stops for a one-line short brief. Uncertainty about whether the work is performance-sensitive is risk uncertainty. On MetaMask Mobile, read `mms-performance` when the work is performance-sensitive. Once the skill applies, the catalog is read on every path before the edit, brief, or yes/no. Drop the `A Jira ticket would improve this context.` line; `jira-brief` still reads a ticket when one is identified. Mark `planning`, `planning-spec`, and `jira-brief` `maturity: experimental` and remove `base: true`, so a default stable sync installs none of them. An installed copy keeps the old always-on trigger until a sync with `--maturity experimental` or a prune. Drop the `-pt.md` sibling instruction from `planning-spec`. ([#219](https://github.com/MetaMask/skills/pull/219)) +- Narrow `planning` (`mms-planning`) to run only when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, a contract or API is being changed, or the engineer asks. A contract or API change stops for a brief even when fully specified. Security and performance stop for agreement before the edit, even when fully specified, and get a spec only when also large. Reading an existing selector to show a value already in the store is not performance-sensitive, even on a screen. A new or changed selector is. `large` means only a new product area or a cross-system design whose scope is not decided. Cheap uncertainty proceeds with one confirmation line; risk uncertainty stops for a one-line short brief. Uncertainty about whether the work is performance-sensitive is risk uncertainty. On MetaMask Mobile, read `mms-performance` when the work is performance-sensitive. Once the skill applies, the catalog is read on every path before the edit, brief, or yes/no. Drop the `A Jira ticket would improve this context.` line; `jira-brief` still reads a ticket when one is identified. Mark `planning`, `planning-spec`, and `jira-brief` `maturity: experimental` and remove `base: true`, so a default stable sync installs none of them. An installed copy keeps the old always-on trigger until a sync with `--maturity experimental` or a prune. Drop the `-pt.md` sibling instruction from `planning-spec`. ([#219](https://github.com/MetaMask/skills/pull/219)) - Install `planning`, `planning-spec`, and `jira-brief` for MetaMask Extension as well as MetaMask Mobile, with the same rules in both repos. Core stays out of scope. Assess every installed `mms-*` skill by its description, follow an `mms-*` skill over a non-`mms-*` one when both fit, and drop the fixed `mms-performance` read, which does not install for MetaMask Extension. ([#219](https://github.com/MetaMask/skills/pull/219)) - Update the MetaMask Mobile performance overlay and animation references for React Native 0.86.x, Expo SDK 57, and Reanimated 4.x with `react-native-worklets`. From a worklet, call `scheduleOnRN` (`runOnJS` is a deprecated alias). Static-ESM tree-shaking stays off. ([#203](https://github.com/MetaMask/skills/pull/203)) - Require every revert yes/no to be one line that names the pull request or commit, the files, and exactly one yes/no question, whether or not security or privacy is involved. A shorter message is not that step. diff --git a/domains/planning/skills/planning/skill.md b/domains/planning/skills/planning/skill.md index d3460499..e27dd9c5 100644 --- a/domains/planning/skills/planning/skill.md +++ b/domains/planning/skills/planning/skill.md @@ -3,15 +3,17 @@ name: planning description: >- Use in MetaMask Mobile or MetaMask Extension when scope is ambiguous, the change is large, the work is security-sensitive or performance-sensitive, - a contract or API is being changed, or the engineer asks for mms-planning or a plan - does not name the target, the action, and the expected result, or it leaves - an open product or contract decision. Large means only a new product area, - or a cross-system design whose scope is not decided. Security, performance, - a contract or API change, a long diff, or several screens is not large by - itself. Security and performance stop for agreement before the edit, even - itself. Contract or API changes require a brief. Security and performance stop for agreement before the edit, even when fully specified. Recommend a spec only when the change is also large. Do not use it - before every edit. When it applies, read the installed mms-* catalog and - every matching skill before the edit, brief, or yes/no. + a contract or API is being changed, or the engineer asks for mms-planning + or a plan. Ambiguous means the ask does not name the target, the action, + and the expected result, or it leaves an open product or contract decision. + Large means only a new product area, or a cross-system design whose scope + is not decided. Security, performance, a contract or API change, a long + diff, or several screens is not large by itself. Contract or API changes + stop for a brief. Security and performance stop for agreement before the + edit, even when fully specified. Recommend a spec only when the change is + also large. Do not use it before every edit. When it applies, read the + installed mms-* catalog and every matching skill before the edit, brief, + or yes/no. maturity: experimental --- @@ -23,7 +25,7 @@ When this skill applies, follow this procedure before the first edit of that tas ### Catalog -When `mms-planning` is triggered, run this catalog step before any edit, brief, or approval question. This applies to every execution path, including mechanical changes, reverts, spikes or POCs, routine CI-only work, and fully specified requests. Do not proceed to another step until the catalog check is complete. +When `mms-planning` is triggered, run this catalog step before any edit, brief, or approval question. This applies to every execution path, including mechanical changes, reverts, spikes or POCs, routine CI-only work, and fully specified requests. Do not proceed to another step until the catalog check is complete. If a later step is reached before it has run, run it first. Read the installed `mms-*` catalog. Assess every installed `mms-*` skill by its description. Read the body of every skill whose area the task touches. A partial or uncertain fit is read. Skip a skill only when the task has no surface for it. When an installed `mms-*` skill and a skill outside that catalog both fit, follow the `mms-*` skill. Prefer an installed skill over restating its guidance. The engineer does not have to name a skill.