mustflow 2.103.3 → 2.103.12

package/templates/default/locales/en/.mustflow/skills/react-code-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.react-code-change
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: react-code-change
-description: Apply this skill when React, React DOM, React Server Components, Server Actions, React Compiler, Hooks, Suspense, Actions, forms, refs, context, concurrent rendering, SSR streaming, resource hints, package metadata, or React-related tests are created, changed, reviewed, or upgraded.
+description: Apply this skill when React, React DOM, React Server Components, Server Actions, React Compiler, Hooks, Suspense, Actions, forms, refs, context, render performance, concurrent rendering, SSR streaming, resource hints, package metadata, or React-related tests are created, changed, reviewed, or upgraded.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -75,6 +75,10 @@ expect current React guidance and small, compatible changes.
 - State and mutation evidence: local state owner, derived values, external
   stores, context providers, forms, Actions, optimistic updates, and rollback
   behavior.
+- Render performance evidence: React DevTools Profiler or `<Profiler>` data when
+  available, render count, render duration, prop identity changes, context update
+  scope, list size, DOM node count, key stability, layout effect use, first-load
+  bundle ownership, and offscreen DOM cost.
 - Configured verification intents for lint, build, tests, docs, package, and
   mustflow checks.
 
@@ -186,14 +190,49 @@ expect current React guidance and small, compatible changes.
      errors, resets, progressive enhancement, and rollback.
    - Keep explicit error handling, authorization, validation, idempotency, and
      rollback behavior. Do not hide server failures behind optimistic UI.
-10. **Respect React 19.2 rendering and performance APIs.**
+10. **Review React render hot paths with evidence.**
+    - Use React DevTools Profiler, `<Profiler>`, framework traces, or existing
+      render-count evidence before claiming a render-performance fix. If none is
+      configured, report static render risk instead of measured speedup.
+    - Check whether state is owned too high in the tree. Search inputs, tabs,
+      modal flags, hover state, and local drafts should not rerender a whole page
+      unless that page truly owns the state.
+    - Check `memo` failures from unstable props. Inline objects, arrays, functions,
+      and selector results can make `React.memo` ineffective; prefer primitive
+      props, stable callbacks, or moving object creation behind a real dependency.
+    - Move expensive render-time `filter`, `sort`, `map`, grouping, and lookup work
+      behind `useMemo`, server-side pagination, route loaders, or pre-indexed data
+      when input size can grow.
+    - Large lists need pagination, infinite query boundaries, virtualization, or a
+      documented hard cap. Do not render thousands of rows because the sample data
+      has twenty.
+    - Reject unstable keys such as array index for reorderable data and
+      `Math.random()` for any list. Use stable item identity so React preserves
+      row state and avoids forced remounts.
+    - Split oversized context values by change frequency and ownership. `memo`
+      does not stop rerenders caused by a fresh context value.
+    - Do not use `useEffect` plus `setState` for values derived from current props
+      or state. Compute during render or memoize the calculation to avoid the
+      extra render pass.
+    - For search and filtering, keep the controlled input urgent and move heavy
+      result updates behind `useDeferredValue`, `useTransition`, server filtering,
+      or pagination when the supported React version and UX allow it.
+    - Use `useLayoutEffect` only when pre-paint measurement is required. Avoid
+      DOM read/write interleaving that causes layout thrashing.
+    - Lazy-load heavy charts, editors, maps, markdown renderers, syntax
+      highlighters, and modal-only widgets when they are not needed for the first
+      interaction path.
+    - For large offscreen sections, consider `content-visibility` plus
+      `contain-intrinsic-size`, framework lazy boundaries, or route splitting when
+      browser support and layout stability are acceptable.
+11. **Respect React 19.2 rendering and performance APIs.**
     - Treat `<Activity>` as hidden UI with preserved state, unmounted effects,
       and lower-priority hidden updates, not as `display: none` or ordinary
       conditional rendering.
     - Use React Performance Tracks, React DevTools, or existing profiler evidence
       when claiming render, effect, Scheduler, transition, or component
       performance improvements.
-11. **Keep server rendering and RSC boundaries exact.**
+12. **Keep server rendering and RSC boundaries exact.**
     - Distinguish Server Components from Server Actions. `"use server"` marks
       server functions or modules for actions; it is not a Server Component tag.
     - Keep browser APIs, client state, and event handlers out of Server
@@ -206,13 +245,13 @@ expect current React guidance and small, compatible changes.
     - In Node environments, do not assume Web Streams are faster than Node
       streams; preserve the existing SSR stream API unless the task proves the
       runtime benefit and compression behavior.
-12. **Use React DOM document and resource APIs close to the owner.**
+13. **Use React DOM document and resource APIs close to the owner.**
     - Metadata, stylesheets with `precedence`, async scripts, `preinit`,
       `preload`, `preconnect`, and `prefetchDNS` may belong near the component
       that needs them when React and the framework support that behavior.
     - Avoid duplicate head managers, resource hint spam, and hints for assets
       whose timing or priority is unproven.
-13. **Verify through the repository contract.**
+14. **Verify through the repository contract.**
     - Run the smallest configured checks that cover changed React code, package
       metadata, build output, docs, and tests.
     - Report missing browser, hydration, SSR, RSC, compiler, profiler, or
@@ -225,12 +264,16 @@ expect current React guidance and small, compatible changes.
   status are known or explicitly reported as unknown.
 - Effects, state, memoization, context, refs, forms, Suspense, and async
   boundaries follow React's current model for the supported version.
+- Render performance claims are backed by profiler or render-count evidence, or
+  static risks such as state too high, unstable props, render-time transforms,
+  huge lists, unstable keys, oversized context, derived-state effects, layout
+  thrashing, eager heavy widgets, and offscreen DOM cost are reported honestly.
 - React 19 and React 19.2 APIs are not introduced into code that still promises
   older React compatibility.
 - SSR, RSC, Server Action, browser-only, and resource-hint boundaries are
   preserved.
-- Performance claims have profiler or benchmark evidence, or are reported as
-  unverified.
+- Performance claims have profiler, benchmark, render-count, or configured
+  evidence, or are reported as unverified.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -271,6 +314,9 @@ surfaces changed.
 - React surface and supported version checked
 - Compiler, lint, effect, state, memoization, context, ref, form, Suspense, SSR,
   RSC, and resource-boundary notes
+- Render performance notes: profiler evidence, state ownership, prop identity,
+  render-time work, list size, key stability, context scope, derived state,
+  layout effects, lazy loading, and offscreen DOM
 - Freshness-sensitive React claims checked or left conservative
 - Files changed
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/vertical-slice-tdd/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.vertical-slice-tdd
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: vertical-slice-tdd
@@ -30,7 +30,7 @@ metadata:
 
 Support explicit test-driven development without making test-first work mandatory for every mustflow task.
 
-This skill keeps TDD work in narrow vertical behavior slices: one observable contract, one focused test change, the smallest implementation that proves it, and only then a local refactor inside the covered slice.
+This skill keeps TDD work in one vertical behavior slice at a time: choose the next test by risk and evidence value, prove one observable contract, attack the test for false-green weakness, implement only enough behavior to pass, and only then refactor inside the covered slice.
 
 <!-- mustflow-section: use-when -->
 ## Use When
@@ -54,6 +54,7 @@ This skill keeps TDD work in narrow vertical behavior slices: one observable con
 
 - User request or issue evidence that makes TDD or slice-by-slice work appropriate.
 - The observable behavior contract for the first slice.
+- A short test list or risk list, ordered by which test would expose the most important uncertainty next.
 - Existing tests, fixtures, and helpers near that behavior.
 - The expected RED category and baseline status before implementation.
 - Relevant command-intent contract entries for the narrowest verification path.
@@ -78,9 +79,11 @@ This skill keeps TDD work in narrow vertical behavior slices: one observable con
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Select one vertical behavior slice.
+1. Select the next evidence-bearing slice.
    - Name the user-visible or public behavior.
    - Define the smallest input, action, and observable output that prove the slice.
+   - Prefer the test that would reveal the riskiest unknown, boundary, integration contract, or regression path, not merely the easiest happy path.
+   - Treat Red-Green-Refactor as the inner loop, not the whole method. Do not start adding tests before choosing why this test is the next useful evidence.
    - Keep cross-cutting infrastructure, broad refactors, and speculative future cases outside the slice.
 2. Find existing coverage.
    - Prefer extending a nearby existing test when it already owns the behavior surface.
@@ -90,30 +93,39 @@ This skill keeps TDD work in narrow vertical behavior slices: one observable con
    - Use `test-design-guard` to select the test shape and assertion.
    - Assert observable behavior such as a return value, exit code, output, file effect, state transition, schema result, or error shape.
    - Keep mocks supportive rather than the only behavior evidence, unless the interaction itself is the public contract.
-4. Classify the RED result before implementation.
+4. Attack the test before trusting it.
+   - Ask what bug could still pass this test. Strengthen the assertion when the answer is concrete and in scope.
+   - Prefer property, contract, approval, integration, or mutation-style evidence only when `test-design-guard` shows that shape fits the contract and stays bounded.
+   - For legacy code, use characterization or approval-style evidence to freeze current behavior before refactoring when the intended behavior is not yet trusted.
+   - For API or service boundaries, prefer consumer, schema, or contract evidence over mocks of the provider's imagined behavior.
+   - If implementation was AI-assisted, check that generated code did not outrun the selected test by adding untested branches, features, or public behavior.
+5. Classify the RED result before implementation.
    - `behavior_red` is the only valid behavior RED.
    - `api_scaffold_red` may be reported only for an explicitly new public API scaffold and must not be counted as behavior coverage.
    - `invalid_red` includes setup failures, wrong imports, missing unrelated symbols, runner failures, fixture failures, syntax or type errors, bad mocks, missing awaits, environment failures, and unrelated baseline failures.
    - If RED is invalid, fix the test setup or report the invalid evidence before changing implementation behavior.
-5. Implement the smallest behavior change.
+6. Implement the smallest behavior change.
    - Change only the code needed for the current observable contract.
    - Preserve existing public behavior outside the slice.
    - Avoid introducing abstractions unless they directly reduce complexity in the current slice.
-6. Verify GREEN with the narrowest configured command intent.
+   - Do not accept a broad AI-generated implementation just because the narrow test turned green; trim or defer unproven behavior.
+7. Verify GREEN with the narrowest configured command intent.
    - Start with the intent that covers the changed test and implementation surface.
    - Escalate only when the slice crosses public surfaces, package or template contracts, or the related selector cannot cover the changed files.
    - Keep command evidence separate from RED evidence and implementation notes.
-7. Refactor only after GREEN.
+8. Refactor only after GREEN.
    - Limit refactoring to code covered by the slice.
    - Re-run the same configured verification intent after behavior-preserving cleanup when the refactor is non-trivial.
-8. Decide whether to continue.
+9. Decide whether to continue.
    - Repeat only when the next slice is clearly in scope.
+   - Reorder the remaining test list when new evidence changes the highest-risk unknown.
    - Stop and report deferred slices when the remaining work is broader than the user request or needs a new decision.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - Each completed slice has a named behavior contract, RED category, implementation summary, and GREEN verification evidence.
+- Each completed slice records why that test was chosen next and how false-green risk was checked.
 - Invalid RED and scaffold-only RED are not reported as behavior coverage.
 - Deferred slices, rejected speculative cases, skipped checks, and remaining risks are explicit.
 - No command execution claim relies on anything outside the configured command intents.
@@ -145,10 +157,12 @@ Prefer the narrowest configured intent that proves the current slice. Escalate o
 ## Output Format
 
 - TDD trigger and slice scope
+- Next-test selection rationale
 - Existing coverage reused
 - Slices completed
 - Slices deferred
 - Cases rejected as duplicate or speculative
+- False-green checks and test-strength limits
 - RED Evidence:
   - category: `behavior_red`, `api_scaffold_red`, `invalid_red`, or `not_applicable`
   - command intent

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.103.3"
+version = "2.103.12"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"