@ibotor/smart-trellis 0.5.23 → 0.5.24

package/dist/templates/common/bundled-skills/trellis-quality-review/references/copy-fidelity.md

@@ -0,0 +1,56 @@
+# Copy Fidelity
+
+User-visible copy is product behavior. Review it separately from code quality.
+
+## What Counts as Copy
+
+Check every added or modified:
+
+- label
+- title
+- placeholder
+- tooltip
+- helper text
+- description
+- radio/checkbox/select option
+- button text
+- validation message
+- empty state
+- modal title
+- table column title
+- confirmation text
+- option order
+
+## Classification
+
+For each changed copy or option-order line, classify it as:
+
+- **Exact requirement text:** the text/order appears in the user's requirement.
+- **Necessary adaptation:** minimal wording/order change required by the feature.
+- **Existing text preserved:** adjacent text appears in diff context but was not changed.
+- **Out-of-scope copy change:** copy/order was polished, rewritten, moved, or added without requirement support.
+
+## Rules
+
+1. Revert out-of-scope copy changes to the previous text/order when safe.
+2. When reordering options for a required default or required order, do not change child descriptions/helper text unless explicitly requested.
+3. Do not improve tone, punctuation, wording, examples, or explanatory text during review unless the requirement asks for it.
+4. Preserve helper descriptions, placeholders, and validation messages unless the requested feature cannot work without changing them.
+5. If copy ownership is unclear, ask before changing more text.
+
+## Diff Scan
+
+Use this scan as a starting point, then manually check each hit against the requirement:
+
+```bash
+git diff -U0 HEAD -- '*.vue' '*.ts' '*.tsx' | rg '^[+-][^+-].*(label|title|placeholder|help|message|Radio|Checkbox|Button|Tooltip|content|confirmText|cancelText|text-|请选择|请输入|验证|账户|服务商|域名|说明|提示)'
+```
+
+## Common Copy Mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Treating wording polish as harmless | Treat copy as behavior and verify it against the requirement |
+| Changing radio descriptions when only label/default changed | Preserve existing helper text |
+| Reordering options without requirement support | Restore order unless required |
+| Editing placeholder/help text for consistency | Leave it unchanged unless requested |

package/dist/templates/common/bundled-skills/trellis-quality-review/references/decision-tree.md

@@ -0,0 +1,102 @@
+# Decision Tree
+
+Use this routing tree after reading `SKILL.md` and before deeper review. Its purpose is to make reference loading deterministic so copy, formatting, framework, and reporting checks are not skipped.
+
+## Start Gate
+
+1. **Is there a frontend diff?**
+   - Check with `scripts/diff_scans.sh --files` when available, or manually run `git diff --name-only HEAD -- '*.vue' '*.ts' '*.tsx' '*.jsx' '*.js' '*.css' '*.scss'`.
+   - Use `scripts/diff_scans.sh --cached` for staged-only review or `scripts/diff_scans.sh --base main` for branch/PR-style review when appropriate.
+   - If no frontend files changed, do not continue with this skill unless the user explicitly requested frontend review planning.
+   - If frontend files changed, continue.
+
+2. **Can you restate the current requirement?**
+   - If yes, write the one-sentence requirement and continue.
+   - If no, inspect the conversation and diff.
+   - If still unclear and further edits depend on interpretation, ask the user before changing code.
+
+3. **Does the change qualify for the small-change fast path?**
+   Signals include a one-file or very localized UI/copy/style/config change with no API, state-flow, validation, routing, permissions, shared type, or data transformation impact.
+   - If yes, read `references/small-change-fast-path.md`, confirm the diff contains only the requested change, and skip full review unless inspection finds scope expansion.
+   - If no, continue with the normal review tree.
+
+4. **Load scope control for normal review.**
+   - Read `references/scope-control.md`.
+   - Classify changed blocks as in-requirement, necessary-adjacent, or out-of-scope before cleanup.
+
+## Framework Branch
+
+5. **Does the diff include Vue, Vite Vue, Pinia, Vue Router, or `.vue` files?**
+   - If yes, use `vue-best-practices` and read `references/framework-rules.md`.
+   - Run or reproduce the Vue added-line scan for `v-model:` when relevant.
+
+6. **Does the diff include React, Next.js, JSX/TSX, React hooks, or Next route/page files?**
+   - If yes, use `vercel-react-best-practices` and read `references/framework-rules.md`.
+   - Check server/client boundaries, hook placement, page/container responsibilities, and unnecessary memoization.
+
+7. **Does any changed file own multiple responsibilities touched by this requirement?**
+   - If yes, build the responsibility map from `scope-control.md` and `framework-rules.md`.
+   - Before splitting components, extracting composables/hooks, moving helpers, or changing ownership, read `references/safe-refactor-boundaries.md`.
+   - Split or extract only when the current requirement created unclear ownership or repeated logic and the safe-refactor checks pass.
+   - If no, avoid structural refactor.
+
+## Diff Fidelity Branch
+
+8. **Could modified existing files contain formatting-only churn?**
+   Signals include changed indentation, wrapping, import/object layout, blank lines, class ordering, or formatter output.
+   - If yes, read `references/formatting-fidelity.md`.
+   - Compare normal diff and whitespace-insensitive diff for affected files.
+   - Restore out-of-scope formatting when safe.
+
+9. **Could user-visible copy or option order have changed?**
+   Signals include changed `label`, `title`, `placeholder`, `help`, `message`, button text, validation text, modal/table text, radio/select options, or localized strings.
+   - If yes, read `references/copy-fidelity.md`.
+   - Classify each changed copy/order line against the requirement.
+   - Restore out-of-scope copy/order changes when safe.
+
+10. **Did the current diff add suspicious frontend patterns?**
+   Use `scripts/diff_scans.sh` when available. Signals include:
+   - debug or suppression lines: `console.log`, `debugger`, `eslint-disable`, `@ts-ignore`, `@ts-expect-error`, `TODO`, `FIXME`
+   - TypeScript risk lines: `any`, `as any`, `as unknown as`, non-null assertions
+   - Vue risk lines: `v-model:`, deep watchers, direct prop mutation patterns
+   - React/Next/browser-boundary risk lines: `use client`, `dangerouslySetInnerHTML`, `window`, `document`, web storage access
+   - copy/accessibility text lines: labels, placeholders, messages, `aria-label`, `alt`
+   - If yes, inspect and fix only current-work instances unless adjacent legacy code blocks correctness.
+   - Treat scan hits as signals, not automatic defects.
+   - If ownership is unclear, mention it in Notes instead of expanding scope.
+
+## Severity, Verification, and Report Branch
+
+11. **Before fixing or deferring findings, has severity been classified?**
+    - Read `references/severity.md`.
+    - Classify findings as Blocker, Must Fix Before Handoff, Should Fix If In Scope, or Note Only.
+    - Fix Blocker findings when possible.
+    - Fix Must Fix findings when introduced by the current diff and ownership is clear.
+    - Fix Should Fix findings only when the edit is small and inside scope.
+    - Record Note Only findings without expanding the diff.
+
+12. **Before final response, has verification been selected and run or intentionally skipped?**
+    - If claiming completion or correctness, use `verification-before-completion`.
+    - Read `references/verification-selection.md` before choosing lint, typecheck, test, build, or diff-only verification.
+    - Choose the smallest relevant verification set from project scripts and docs.
+    - If verification is skipped, state why.
+
+13. **Before final response, load report format.**
+    - Read `references/report-format.md`.
+    - Include Scope Check, Formatting Fidelity, Copy Fidelity, Changed, Removed, Verified, and Notes.
+
+## Quick Routing Table
+
+| Signal | Required action |
+| --- | --- |
+| Tiny localized UI/copy/style/config change | Read `small-change-fast-path.md`; use diff inspection unless disqualified |
+| Any normal frontend diff | Read `scope-control.md` |
+| `.vue`, Pinia, Vue Router, Vite Vue | Use `vue-best-practices`; read `framework-rules.md` |
+| React, Next.js, `.tsx`, hooks | Use `vercel-react-best-practices`; read `framework-rules.md` |
+| Component split, hook/composable extraction, helper move, ownership change | Read `safe-refactor-boundaries.md` |
+| Formatting-only looking diff | Read `formatting-fidelity.md` |
+| Label/title/placeholder/message/options changed | Read `copy-fidelity.md` |
+| Added debug/type suppression lines | Classify severity, then fix current-work instances or explain why not |
+| Deciding fix vs defer | Read `severity.md` |
+| Choosing verification | Read `verification-selection.md` |
+| Final handoff | Use `verification-before-completion`; read `report-format.md` |

package/dist/templates/common/bundled-skills/trellis-quality-review/references/formatting-fidelity.md

@@ -0,0 +1,37 @@
+# Formatting Fidelity
+
+Formatting-only diffs are code changes. Review them separately from logic and copy.
+
+## Default Rule
+
+Preserve existing formatting for existing code unless the user explicitly asked to format, or the touched new/changed code cannot pass required verification without a minimal formatting change.
+
+For every modified existing file, compare normal and whitespace-insensitive diffs:
+
+```bash
+git diff HEAD -- path/to/file
+git diff -w HEAD -- path/to/file
+```
+
+## Classification
+
+- **Necessary formatting:** layout required for newly added code or to satisfy a non-formatting correctness/lint issue in the touched block.
+- **Out-of-scope formatting:** single-line/multiline wrapping, indentation, blank-line, object/call layout, chain layout, or trailing whitespace changes that do not change behavior and were not required.
+- **Formatter conflict:** preserving original code style makes `prettier/prettier` complain, but changing it would reformat existing out-of-scope code.
+
+## Rules
+
+1. If normal diff shows a block but `git diff -w` makes it disappear, treat it as likely out-of-scope formatting until proven necessary.
+2. Do not run broad `eslint --fix` or prettier on existing files during scope review unless the user asked for formatting.
+3. Revert out-of-scope formatting to the previous layout when safe.
+4. If formatter rules conflict with scope preservation, prefer scope preservation for existing code.
+5. When needed, run scoped lint with formatting rules disabled and report the conflict instead of expanding the diff.
+6. New code should still be readable and locally consistent, but do not reflow surrounding old code just to match formatter output.
+
+## High-Signal Questions
+
+- Did this file change only because a formatter touched it?
+- Does `git diff -w` remove the entire block?
+- Did line wrapping change without behavior or type impact?
+- Did import/order/object layout change without necessity?
+- Would reverting formatting leave the requested behavior intact?

package/dist/templates/common/bundled-skills/trellis-quality-review/references/framework-rules.md

@@ -0,0 +1,59 @@
+# Framework Rules
+
+Use this reference when the review touches Vue, React, Next.js, routes, stores, components, composables, hooks, or styling conventions.
+
+## Shared Frontend Rules
+
+- Keep page/container files focused on orchestration.
+- Keep presentational components focused on one UI section.
+- Keep stateful side effects in composables/hooks.
+- Keep pure feature-local logic in local helpers.
+- Avoid magic strings when a small typed union or constant improves clarity.
+- Avoid adding comments unless they explain business rules, side effects, temporary mock behavior, or non-obvious constraints.
+- Do not create broad shared abstractions for logic used only once.
+- Before structural refactors, use `safe-refactor-boundaries.md` to decide whether the split is safer than keeping code local.
+
+## Vue / Vite / Pinia
+
+Load `vue-best-practices` before editing Vue code.
+
+Check current-work code for:
+
+- Composition API and `<script setup>` usage where the project uses it.
+- typed `defineProps`, `defineEmits`, and `defineModel` usage.
+- section-local state staying near the owning component.
+- composables owning stateful logic and side effects, not presentational markup.
+- Pinia stores used for shared application state, not one-off local UI state.
+- route/page components doing orchestration rather than owning multiple unrelated UI sections.
+- newly introduced `v-model:` usage if the project lint rule disallows arguments.
+
+Diff-only scan for Vue projects with `vue/no-v-model-argument`:
+
+```bash
+git diff -U0 HEAD -- '*.vue' | rg '^\+[^+].*v-model:'
+```
+
+If an added line contains `v-model:value="..."` and the project uses `vue/no-v-model-argument`, rewrite the touched code to the project-approved binding/event style instead of editing unrelated old occurrences.
+
+## React / Next.js
+
+Load `vercel-react-best-practices` before editing React or Next.js code.
+
+Check current-work code for:
+
+- server/client component boundary correctness in Next.js.
+- unnecessary client components or broad `use client` placement.
+- hooks used only in valid component/hook contexts.
+- derived state that can be computed instead of stored.
+- callback/prop contracts that are typed and stable enough for the feature.
+- expensive render work introduced by the current change.
+- route/page files doing orchestration rather than owning large reusable UI sections.
+
+Do not add memoization by default. Add it only when there is a clear render-cost or identity-stability reason related to the current change.
+
+## Styling
+
+- Preserve layout unless the requirement asks for visual changes.
+- Do not normalize class ordering, spacing, or style object layout unless required by touched code or lint.
+- Avoid moving styles across files just for preference.
+- If design tokens exist, use project conventions already present in nearby code.

package/dist/templates/common/bundled-skills/trellis-quality-review/references/report-format.md

@@ -0,0 +1,23 @@
+# Report Format
+
+Keep the final report concise and evidence-based.
+
+Use this structure:
+
+- **Scope Check:** whether the diff stayed within the requested requirement, plus any out-of-scope code intentionally left unchanged.
+- **Severity:** Blocker, Must Fix, Should Fix, and Note Only summary for current-diff findings.
+- **Formatting Fidelity:** whether normal diff vs `git diff -w` was checked, what formatting-only changes were restored, and any remaining formatter conflicts.
+- **Copy Fidelity:** whether changed user-visible text/order was checked against the requirement, what was restored, and any remaining necessary copy changes.
+- **Changed:** cleanup, refactor, comment, or boundary changes made during review.
+- **Removed:** dead code blocks, unused imports, unused state, or files removed.
+- **Verified:** exact commands and exit status.
+- **Notes:** skipped findings, historical issues, or remaining risks with reasons.
+
+## Reporting Rules
+
+- Do not claim checks passed unless command output was read and exit status was successful.
+- If verification fails due to historical or unrelated issues, say so explicitly and explain whether the current change appears related.
+- If you skipped lint/typecheck/test/build, explain why.
+- Avoid long narrative. Prefer short bullets with concrete evidence.
+- Mention out-of-scope issues without fixing them unless they block the current requirement.
+- Keep Severity concise; do not list every Note Only issue when one representative summary is enough.

package/dist/templates/common/bundled-skills/trellis-quality-review/references/safe-refactor-boundaries.md

@@ -0,0 +1,158 @@
+# Safe Refactor Boundaries
+
+Use this reference before splitting components, extracting composables/hooks, moving helpers, or changing ownership. The goal is to reduce responsibility pile-up without creating abstraction churn or expanding beyond the current diff.
+
+## Core Rule
+
+Refactor only when it improves the current requirement's clarity, correctness, or maintainability inside the review boundary. File size alone is not enough.
+
+A safe refactor has all of these properties:
+
+- The problematic responsibility is touched by the current diff.
+- The target boundary is obvious and nameable.
+- The extracted interface is smaller than the code it hides.
+- The move does not require unrelated callers, routes, stores, styles, or tests to change.
+- Behavior, copy, layout, and public contracts remain unchanged unless required.
+- Verification can cover the moved logic or affected render path.
+
+## Strong Signals to Split or Extract
+
+Consider a targeted split when at least one is true:
+
+- A page/container now owns orchestration plus multiple changed UI sections.
+- A component now mixes rendering with request orchestration, validation, mapping, and modal/table/form state touched by this requirement.
+- The current diff duplicates non-trivial logic in two or more places.
+- Newly added side effects make the render component hard to follow.
+- Newly added pure mapping/formatting/validation logic obscures the UI path.
+- A modal/drawer/wizard section has its own state, validation, and actions that can be named independently.
+- A hook/composable would isolate stateful behavior used by the current feature without becoming a generic utility.
+
+## Strong Signals Not to Refactor
+
+Avoid structural refactor when any is true:
+
+- The file is merely large, but the current change touches a small localized area.
+- The split would require moving unrelated markup, styles, tests, or callers.
+- The extracted function/component would have many props or return values just to keep behavior working.
+- The new abstraction would be used once and does not hide meaningful complexity.
+- Naming the boundary requires vague words like `Common`, `Base`, `Manager`, `Handler`, or `Utils`.
+- The refactor would change user-visible copy, layout, option order, focus behavior, or event timing.
+- The user requested a micro-change or explicitly asked to avoid broad cleanup.
+
+## Boundary Heuristics
+
+### Page / Route / Container
+
+Should own:
+
+- route params and navigation glue
+- top-level data loading orchestration
+- composition of feature sections
+- passing typed props and event handlers to children
+
+Should not accumulate:
+
+- multiple independent UI sections with detailed markup
+- modal internals
+- table cell formatting details
+- form field validation internals
+- low-level API payload mapping when it obscures orchestration
+
+### Component
+
+Should own:
+
+- one nameable UI section
+- local UI state for that section
+- typed props/events or callbacks
+- minimal formatting needed for display
+
+Extract when the component contains multiple independently nameable regions touched by this requirement, such as search form + table + edit modal + upload drawer.
+
+Do not extract when the child would only wrap a few lines and add prop plumbing without hiding complexity.
+
+### Composable / Hook
+
+Should own:
+
+- stateful logic and side effects
+- async request lifecycle
+- derived state tied to the feature
+- event handlers whose behavior is not just presentational
+
+Good candidates:
+
+- `useUserTableData`
+- `useDomainForm`
+- `useUploadDialog`
+
+Weak candidates:
+
+- `useHelpers`
+- `useCommon`
+- `usePageLogic`
+- a hook returning 15 unrelated values
+
+### Helper
+
+Should own pure logic:
+
+- formatters
+- mappers
+- validators
+- sort/filter predicates
+- small calculations
+
+Keep helpers local when used only by one component/composable. Move to a separate file only when the helper is non-trivial, reused by current-work code, or makes the owning file materially clearer.
+
+### Types
+
+Keep feature-local types near the owning component/composable when they are not reused.
+
+Move types to shared files only when:
+
+- multiple current-work files consume them
+- they represent API or route/store boundaries
+- colocating them would create import cycles or unclear ownership
+
+## Vue-Specific Guidance
+
+- Prefer `<script setup>` and typed props/emits when the project uses that style.
+- Keep section-local refs in the section component unless parent orchestration needs them.
+- Extract a composable when state transitions, async effects, watchers, or derived state dominate the component.
+- Avoid Pinia for one-off UI state; use Pinia when state is shared across routes/features or must outlive the component.
+- Avoid composables that return large bags of unrelated refs; split by feature behavior instead.
+
+## React / Next-Specific Guidance
+
+- Keep route/page components focused on orchestration and server/client boundary correctness.
+- Do not add `use client` broadly just to support a small interactive child; prefer isolating the client component when feasible and in scope.
+- Extract a hook when stateful behavior or side effects obscure the component body.
+- Extract a component when a nameable UI section has its own props and events.
+- Do not add `useMemo`/`useCallback` as a refactor unless identity stability or render cost is a real current-diff concern.
+
+## Safe Refactor Procedure
+
+1. Name the responsibility that is piled up.
+2. Confirm it is touched by the current requirement.
+3. Choose the smallest boundary that hides complexity without leaking many props/returns.
+4. Preserve public behavior, copy, layout, and event timing.
+5. Move only the directly related code.
+6. Re-run the smallest relevant verification from `verification-selection.md`.
+7. If any step requires broad unrelated edits, stop and record the idea as Note Only.
+
+## Reporting
+
+When you refactor, report why the boundary was safe:
+
+```text
+Changed:
+- Extracted EditDomainModal because the current diff added independent modal state, validation, and submit handling; parent now only orchestrates open/close and refresh.
+```
+
+When you do not refactor, report why not when relevant:
+
+```text
+Severity:
+- Should Fix: did not split SettingsPage because the large table section was pre-existing and untouched by this request.
+```

package/dist/templates/common/bundled-skills/trellis-quality-review/references/scope-control.md

@@ -0,0 +1,49 @@
+# Scope Control
+
+Use this gate before any cleanup or refactor. The purpose is to protect the user's requested change from scope creep.
+
+## Default Rule
+
+Change only what the requirement asks for, plus the smallest necessary adjacent code to keep it correct, typed, lint-clean, or buildable.
+
+Do not opportunistically optimize, polish, reorder, refactor, rename, reformat, or clean up code the requirement does not touch.
+
+Preserve existing user-visible text, helper descriptions, option order, placeholders, tooltips, validation messages, comments, and layout unless the requirement explicitly asks to change them or the feature cannot work without the change.
+
+If the user says “do not change anything not mentioned”, treat all non-required UI/text changes as high-risk and list them explicitly in the review.
+
+## Gate Steps
+
+1. Restate the current requirement in one sentence.
+2. Inspect `git status` and `git diff HEAD` before editing.
+3. Classify each changed block:
+   - **In requirement:** directly implements or verifies the requested change.
+   - **Necessary adjacent:** required to keep the requested change correct, typed, lint-clean, or buildable.
+   - **Out of scope:** opportunistic old-code optimization, unrelated formatting, broad refactor, unrelated dead-code cleanup, renamed abstractions, style changes, user-visible copy changes, helper-description changes, or option-order changes not needed by the requirement.
+4. Only edit **In requirement** and **Necessary adjacent** blocks.
+5. For **Out of scope** blocks, do not extend the change.
+6. Revert your own out-of-scope edits when safe.
+7. If an out-of-scope edit predates the session or ownership is unclear, leave it untouched and mention it in Notes.
+8. If classification is unclear and would change more code, ask the user instead of deciding silently.
+
+## Responsibility Map
+
+Use this map to decide whether structure changes are justified:
+
+- **route/page/container:** orchestration, data loading, high-level composition
+- **component:** one UI section with typed props/emits or typed component props/callbacks
+- **composable/hook:** stateful logic, side effects, derived state, lifecycle coordination
+- **helper:** pure feature-local logic
+- **api/types:** external boundary and shared contracts
+
+Split only when the current requirement created unclear ownership or repeated logic. Keep feature-local types/helpers near the owning unit unless reused broadly.
+
+## Common Scope Mistakes
+
+| Mistake | Correction |
+| --- | --- |
+| Optimizing old code during requirement review | Record it in Notes unless it blocks the current requirement |
+| Splitting every type/helper into standalone files | Keep local helpers local unless reused |
+| Moving UI state into parent unnecessarily | Keep section-local state near the section |
+| Letting old violations expand scope | Fix only newly introduced violations unless adjacent legacy code blocks correctness |
+| Trusting visual refactor | Preserve behavior and verify with commands |

package/dist/templates/common/bundled-skills/trellis-quality-review/references/severity.md

@@ -0,0 +1,105 @@
+# Severity
+
+Classify findings before fixing them. Severity applies to the current review boundary: default to `git diff HEAD` unless the user requested staged-only or a specific base ref. Historical or untouched issues are usually Note Only unless they block the current requirement.
+
+## Levels
+
+### Blocker
+
+Must be fixed before handoff. The current diff introduces or exposes a problem that can break build, typecheck, runtime behavior, critical user flow, permissions, data integrity, or security.
+
+Frontend examples:
+
+- current diff causes build, typecheck, or required test failure
+- key page crashes or fails to render
+- form cannot submit, primary action cannot be clicked, or required user flow is broken
+- API payload or response mapping is wrong for the changed feature
+- permission/auth guard is loosened or bypassed
+- Next.js server/client boundary error prevents render or build
+- changed props/types break touched consumers
+- unsanitized user-controlled `dangerouslySetInnerHTML` or equivalent XSS risk
+- production-executed `debugger`
+
+Action: fix in the current review if possible, rerun relevant verification, and report as blocking if not resolved.
+
+### Must Fix Before Handoff
+
+Should be fixed before delivery when introduced by the current diff, even if it does not immediately fail build.
+
+Frontend examples:
+
+- added `console.log`, `debugger`, unexplained `@ts-ignore`, `@ts-expect-error`, or broad `eslint-disable`
+- current-work dead code: unused props, emits, refs, state, imports, branches, mock fields
+- out-of-scope user-visible copy, helper text, placeholder, validation message, or option-order changes
+- out-of-scope formatting churn mixed into the diff
+- current diff introduces obvious duplicated logic that can be removed locally
+- local UI state was lifted or globalized without requirement support
+- newly added loading/error state is never rendered or consumed
+- temporary mock/demo data is scattered in production components
+
+Action: fix when ownership is clear and the fix stays inside the requirement boundary. If ownership is unclear, record in Notes instead of expanding scope.
+
+### Should Fix If In Scope
+
+Real issue, but fix only when it is clearly within the current requirement and the change is small.
+
+Frontend examples:
+
+- unclear name in newly added function, prop, event, or variable
+- newly added condition is hard to read but safe
+- new component is somewhat large but not yet clearly multi-responsibility
+- duplicated new snippet appears twice and a local helper would clarify it
+- type could be narrower, but current type is safe
+- composable/hook return shape is slightly broad but still understandable
+- helper extraction would improve clarity but requires moving files or touching callers
+- tests are not ideal, but selected verification covers the main changed path
+
+Action: fix only if the edit is small and does not expand scope. Otherwise mention as a follow-up Note.
+
+### Note Only
+
+Do not fix during this review. The issue is historical, untouched, unclear ownership, or not needed for the current requirement.
+
+Frontend examples:
+
+- old component is large but this task touched only a tiny unrelated line
+- historical lint/typecheck/test failures
+- old copy inconsistency
+- legacy form validation pattern
+- old API layer or directory structure concerns
+- untouched hook/composable design issue
+- existing `any`, formatter churn, or test gap not introduced by the current diff
+
+Action: record briefly in Notes when useful. Do not mark the current task failed unless it blocks the current requirement.
+
+## Classification Flow
+
+1. **Was it introduced or exposed by the current review diff?**
+   - No: Note Only, unless it blocks the current requirement.
+   - Yes: continue.
+
+2. **Can it break build, typecheck, runtime behavior, critical flow, permissions, data integrity, or security?**
+   - Yes: Blocker.
+   - No: continue.
+
+3. **Is it current-work debug code, unexplained suppression, dead code, out-of-scope copy, or out-of-scope formatting?**
+   - Yes: Must Fix Before Handoff.
+   - No: continue.
+
+4. **Is the fix small, local, and inside the current requirement boundary?**
+   - Yes: Should Fix If In Scope.
+   - No: Note Only.
+
+## Reporting
+
+Keep severity concise. Prefer counts and high-signal examples over long lists.
+
+Example:
+
+```text
+Severity:
+- Blocker: none
+- Must Fix: removed added console.log; restored out-of-scope placeholder change
+- Should Fix: did not split SettingsPanel because it would touch unrelated sections
+- Note Only: pre-existing vue-tsc errors in src/legacy/* are unrelated to touched files
+```

package/dist/templates/common/bundled-skills/trellis-quality-review/references/small-change-fast-path.md

@@ -0,0 +1,51 @@
+# Small-Change Fast Path
+
+Use this path for tiny, low-risk frontend changes where full quality review would create more churn than value.
+
+## Qualifying Changes
+
+A change qualifies only when all are true:
+
+- The user's request is narrow and explicit.
+- The diff is limited to one file or a very small localized area.
+- The change does not affect API shape, routing, permissions, state flow, data transformation, validation behavior, dependency configuration, or shared types.
+- The change is easy to verify by reading the diff.
+- No suspicious added lines appear, such as `console.log`, `debugger`, `@ts-ignore`, `eslint-disable`, `TODO`, or `FIXME`.
+
+Common qualifying examples:
+
+- UI spacing, width, color, or alignment constants
+- single label/copy change explicitly requested by the user
+- table column width/order requested by the user
+- small style/class adjustment
+- single local config flag with no behavior cascade
+
+## Disqualifiers
+
+Do not use the fast path if any are true:
+
+- The change affects component boundaries, composables/hooks, stores, route logic, API calls, form validation, permissions, upload/download behavior, or data mapping.
+- The diff spans multiple modules or shared abstractions.
+- The change introduces or edits TypeScript types used outside the local file.
+- The diff includes unrelated formatting or copy churn.
+- The user asks for a full review, cleanup, refactor, verification, or confidence before handoff.
+- The project currently has failing diagnostics that may be related to the touched code.
+
+## Fast Path Procedure
+
+1. Restate the small requirement in one sentence.
+2. Inspect the relevant diff only.
+3. Confirm the diff contains only the requested localized change.
+4. Do not run broad lint, typecheck, unit tests, or build by default.
+5. If a minimal targeted command is obvious and cheap, run it only when it directly validates the change.
+6. Report that the fast path was used and whether verification was limited to diff inspection.
+
+## Required Final Note
+
+When using this path, include a short note like:
+
+```text
+Used small-change fast path: skipped lint/typecheck/test/build because the diff is a localized UI/copy/config change and diff inspection confirmed scope.
+```
+
+If the diff inspection finds scope expansion, leave the fast path and return to the normal decision tree.