@hinen/pro-element-plus 1.7.16 → 1.8.0

package/dist/skills/optimizing-component-skills/REVIEW.md

@@ -0,0 +1,775 @@
+# optimizing-component-skills Review Log
+
+## Goal
+
+This document tracks the package-level review of component-related skills under `packages/pro-element-plus/skills/`.
+
+Current workflow:
+
+1. Audit existing skills.
+2. Record findings and recommendations here.
+3. Wait for human confirmation on proposed changes.
+4. Apply approved updates to skills.
+5. Append implementation and verification results.
+
+## Scope
+
+The current review covers these groups:
+
+- Router skills
+- Page-shell and overlay skills
+- Direct component skills
+- Form foundation skills
+- Form field wrapper skills
+- Supporting `references/*` materials when they materially affect skill quality
+
+## Status Model
+
+- `not-reviewed`
+- `reviewed-awaiting-confirmation`
+- `approved-for-update`
+- `updated`
+- `verified`
+- `blocked`
+
+## Skill Inventory
+
+### Routers
+
+| Skill                     | Priority | Status   |
+| ------------------------- | -------- | -------- |
+| choosing-components       | P0       | verified |
+| building-form-workflows   | P0       | verified |
+| building-query-pages      | P0       | verified |
+| building-selection-inputs | P0       | verified |
+| building-modal-workflows  | P0       | verified |
+
+### Page shells, overlays, and direct components
+
+| Skill                 | Priority | Status   |
+| --------------------- | -------- | -------- |
+| using-query-form      | P1       | verified |
+| using-data-table      | P1       | verified |
+| using-config-provider | P1       | verified |
+| using-modal           | P1       | verified |
+| using-drawer          | P1       | verified |
+| using-select          | P2       | verified |
+| using-data-select     | P2       | verified |
+| using-radio-group     | P2       | verified |
+| using-checkbox-group  | P2       | verified |
+| using-image           | P2       | verified |
+| using-ellipsis-text   | P2       | verified |
+
+### Form foundations and field wrappers
+
+| Skill                     | Priority | Status   |
+| ------------------------- | -------- | -------- |
+| using-form-item           | P1       | verified |
+| using-form-fields         | P1       | verified |
+| using-form-text           | P2       | verified |
+| using-form-number         | P2       | verified |
+| using-form-select         | P2       | verified |
+| using-form-autocomplete   | P2       | verified |
+| using-form-checkbox-group | P2       | verified |
+| using-form-radio-group    | P2       | verified |
+| using-form-switch         | P2       | verified |
+| using-form-date-picker    | P2       | verified |
+| using-form-time-picker    | P2       | verified |
+| using-form-tree-select    | P2       | verified |
+| using-form-cascade-select | P2       | verified |
+| using-form-tag-input      | P2       | verified |
+| using-form-rate           | P2       | verified |
+
+## Next-wave planning
+
+The highest-value untouched area is now the **remaining wrapped field family** that still sits at `reviewed-awaiting-confirmation`.
+
+### Recommended next batches
+
+#### Batch A — remaining wrapped choice and scalar fields
+
+- `using-form-switch`
+- `using-form-date-picker`
+- `using-form-time-picker`
+
+Goal:
+
+- verify their `SKILL.md` boundaries against the current form-family router
+- improve any thin `examples.md`, `gotchas.md`, or `props.md` that still lag behind the now-stronger text/number/select siblings
+
+#### Batch B — hierarchical and collection fields
+
+- `using-form-tree-select`
+- `using-form-cascade-select`
+- `using-form-tag-input`
+
+Goal:
+
+- tighten routing against `FormSelect`, `FormAutocomplete`, and the selection router
+- strengthen examples and gotchas around hierarchical choice and collection semantics
+
+#### Batch C — specialized scalar field
+
+- `using-form-rate`
+
+Goal:
+
+- check whether its examples/gotchas/props depth matches the stronger wrapper family pattern
+- document its non-fit boundary against switch, radio, and numeric fields more explicitly if needed
+
+## Review Dimensions
+
+Each first-pass audit checks:
+
+1. Role clarity and intended use.
+2. Boundary clarity versus neighboring skills.
+3. Routing and handoff consistency.
+4. Coverage of common mistakes, examples, and references.
+5. Structural consistency with the package skill template.
+6. Evidence of duplication, ambiguity, or missing guidance.
+
+## Round 1
+
+### Summary
+
+Round 1 completed for all current component-related skills under `packages/pro-element-plus/skills/`.
+
+Overall assessment:
+
+- The skill system is already structurally strong and internally consistent.
+- Router skills are useful and readable, but some reference files are too thin and a few handoff guides overlap.
+- Shell and direct component skills are mostly solid; the clearest content gap is in `using-config-provider` and `using-image`.
+- Form skills are the most consistent part of the system and mainly need small consistency improvements rather than rewrites.
+
+### Findings
+
+#### Router skills
+
+| Skill                     | Result       | Findings                                                                                                                                                                                            |
+| ------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| choosing-components       | pass         | Clear top-level router role and exit criteria. Main improvement area is richer examples and less duplicated selection guidance relative to `building-selection-inputs`.                             |
+| building-form-workflows   | needs-review | Good separation from query pages and strong wrapper mental model, but `references/workflow.md` is very short and `references/field-selection.md` overlaps heavily with query-page routing material. |
+| building-query-pages      | needs-review | Strong page-shell decision logic (`QueryForm` vs `DataTable`), but `references/workflow.md` is thin and `references/field-selection.md` duplicates a large part of the form-workflow field map.     |
+| building-selection-inputs | pass         | Good visible-vs-dropdown and local-vs-request-driven routing. The selection guide substantially overlaps with `choosing-components/references/selection-guide.md`.                                  |
+| building-modal-workflows  | pass         | Strong shell-vs-content framing and clean handoff to form/query routers. Main gap is thin reference material, especially for overlay content decisions and close-handling examples.                 |
+
+#### Page-shell, overlay, and direct component skills
+
+| Skill                 | Result       | Findings                                                                                                                                                                                                                                                                                                  |
+| --------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| using-query-form      | pass         | Clear role and good separation from `DataTable`; no major structural issues found.                                                                                                                                                                                                                        |
+| using-data-table      | pass         | One of the strongest skills in the set; remote/static modes, imperative control, and common mistakes are well covered.                                                                                                                                                                                    |
+| using-config-provider | needs-review | Current scope is intentionally narrow and focused on shared `DataTable` empty/error UI. That is coherent with the file, but the package README suggests broader capability history, so the skill should either document that broader scope or explicitly state its current public boundary more strongly. |
+| using-modal           | pass         | Good direct shell guidance and good alignment with overlay router.                                                                                                                                                                                                                                        |
+| using-drawer          | pass         | Good direct shell guidance and good alignment with overlay router.                                                                                                                                                                                                                                        |
+| using-select          | pass         | Clear distinction from `using-data-select` and strong local-option guidance.                                                                                                                                                                                                                              |
+| using-data-select     | pass         | Clear request-driven positioning and good complement to `using-select`.                                                                                                                                                                                                                                   |
+| using-radio-group     | pass         | Clean single-choice guidance with correct routing boundary.                                                                                                                                                                                                                                               |
+| using-checkbox-group  | pass         | Clean multi-choice guidance with correct routing boundary.                                                                                                                                                                                                                                                |
+| using-image           | needs-review | The skill describes retry/reload behavior well, but the naming around the retry affordance should be aligned with actual public props and README wording so users can reliably find the toggle they need.                                                                                                 |
+| using-ellipsis-text   | pass         | Focused, stable, and structurally consistent.                                                                                                                                                                                                                                                             |
+
+#### Form foundations and field wrappers
+
+| Group                                    | Result | Findings                                                                                                                                                                                                                                |
+| ---------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| using-form-item                          | pass   | Clear base-wrapper abstraction; strong explanation of wrapper-first reasoning.                                                                                                                                                          |
+| using-form-fields                        | pass   | Clear family router; good bridge between wrapper semantics and concrete field skills.                                                                                                                                                   |
+| All concrete `using-form-*` field skills | pass   | This family is the most internally consistent part of the skill system. Structure, reference completeness, and value-semantics framing are all strong. Most improvements are parity and wording improvements, not architecture changes. |
+
+#### Cross-cutting findings
+
+1. **Reference depth is uneven.** Some `workflow.md` files are only 7-9 lines, which is enough to link out but not enough to act as a practical decision aid.
+2. **Selection guidance is duplicated.** `choosing-components/references/selection-guide.md` and `building-selection-inputs/references/selection-guide.md` are very similar.
+3. **Field-routing reference material overlaps.** `building-form-workflows/references/field-selection.md` and `building-query-pages/references/field-selection.md` share a large amount of mapping logic.
+4. **Form skills are in the best shape.** They already follow a stable template with complete `props.md`, `examples.md`, and `gotchas.md` coverage.
+5. **Round 1 found no evidence that the current router skills are missing.** They exist in the repository and should be treated as valid handoff destinations.
+
+### Proposed updates
+
+No skill files have been modified yet. Round 1 recommendations:
+
+### High priority
+
+1. Expand `building-form-workflows/references/workflow.md` into a more useful decision checklist.
+2. Expand `building-query-pages/references/workflow.md` with a stronger page-shell and `ConfigProvider` decision path.
+3. Reduce duplication between the two selection guides, either by consolidating them or by making one the canonical source and cross-linking from the other.
+4. Reduce duplication between the two field-selection references by tightening each file's scope and cross-linking more explicitly.
+
+### Medium priority
+
+5. Strengthen `building-modal-workflows` references with overlay-content routing examples and close-handling examples.
+6. Clarify `using-config-provider` scope against current package capabilities so users understand whether it is intentionally narrow or partially documented.
+7. Align `using-image` wording and references with the actual retry/reload prop naming exposed by the package.
+
+### Low priority
+
+8. Add richer real-world examples to `choosing-components` so the top-level router feels more concrete on first use.
+9. Review whether selected form-wrapper skills should add parity cross-links to direct-component counterparts where those counterparts exist and help users choose abstraction level faster.
+
+### Suggested first modification batch after human confirmation
+
+- `building-form-workflows/references/workflow.md`
+- `building-query-pages/references/workflow.md`
+- `choosing-components/references/selection-guide.md`
+- `building-selection-inputs/references/selection-guide.md`
+- `building-form-workflows/references/field-selection.md`
+- `building-query-pages/references/field-selection.md`
+- `using-config-provider/SKILL.md`
+- `using-image/SKILL.md`
+
+### Confirmed cleanup queue
+
+The current cleanup queue is organized by priority and evidence from Round 1 plus the follow-up EllipsisText audit.
+
+#### P0
+
+1. `building-form-workflows/references/workflow.md` — was too thin to act as a practical decision checklist; updated and verified on 2026-03-25.
+2. `building-query-pages/references/workflow.md` — was too thin and did not route clearly enough through page-shell and `ConfigProvider` decisions; updated and verified on 2026-03-25.
+3. `choosing-components/references/selection-guide.md` — overlapped heavily with `building-selection-inputs/references/selection-guide.md`; updated and verified on 2026-03-25.
+4. `building-selection-inputs/references/selection-guide.md` — overlapped heavily with `choosing-components/references/selection-guide.md`; updated and verified on 2026-03-25.
+5. `building-form-workflows/references/field-selection.md` — overlapped with query-page field routing and needed tighter scope; updated and verified on 2026-03-25.
+6. `building-query-pages/references/field-selection.md` — overlapped with form-workflow field routing and needed tighter scope; updated and verified on 2026-03-25.
+
+#### P1
+
+7. `using-config-provider/SKILL.md` — current skill was coherent but narrower than package capability signals; updated and verified on 2026-03-25.
+8. `building-modal-workflows/references/*` — references were usable but thin for overlay-content routing and close-handling examples; updated and verified on 2026-03-25.
+
+#### P2
+
+9. `using-image/SKILL.md` — retry/reload wording needed tighter alignment with package-facing naming signals; updated and verified on 2026-03-25.
+10. `using-ellipsis-text/*` — follow-up audit found missing default-behavior guidance, minimum setup detail, `lineClamp` precedence, `disabled` coverage, and dynamic overflow-update explanation; updated and verified on 2026-03-25.
+11. `choosing-components/references/examples` direction — richer real-world entry examples were needed after higher-priority dedupe work; updated and verified on 2026-03-25.
+
+### 2026-03-25 follow-up: using-ellipsis-text
+
+Follow-up audit against `src/components/EllipsisText/props.ts`, `src/components/EllipsisText/EllipsisText.vue`, `src/components/EllipsisText/EllipsisText.stories.tsx`, and `src/components/Tooltip/props.ts` found that the original skill was structurally solid but under-documented in five places that matter to LLM routing quality:
+
+1. default single-line truncation (`truncated: true`) was not called out clearly enough as the smallest correct setup;
+2. `lineClamp` default and precedence over single-line truncation were not stated directly;
+3. inherited `disabled` behavior was mentioned implicitly but not documented as a public control point;
+4. the need for real layout constraints to produce overflow was easy to miss;
+5. resize/content-change reactivity was mentioned at a high level but not reinforced in references and examples.
+
+Applied update scope:
+
+- `using-ellipsis-text/SKILL.md`
+- `using-ellipsis-text/references/props.md`
+- `using-ellipsis-text/references/examples.md`
+- `using-ellipsis-text/references/gotchas.md`
+
+Expected verification outcome:
+
+- skill now explains the smallest correct single-line setup;
+- references now document defaults, active-mode precedence, `disabled`, and dynamic updates;
+- examples and gotchas now warn about layout constraints and mode confusion more directly.
+
+Verification completed on 2026-03-25 by rereading the updated skill files against the component source and story files named above.
+
+### 2026-03-25 follow-up: building-form-workflows workflow guide
+
+Follow-up audit against `building-form-workflows/SKILL.md`, `building-form-workflows/references/workflow.md`, `building-form-workflows/references/field-selection.md`, `using-form-item/SKILL.md`, `using-form-fields/SKILL.md`, `using-query-form/SKILL.md`, `building-query-pages/SKILL.md`, and `building-query-pages/references/workflow.md` found four routing-quality gaps in the original workflow guide:
+
+1. the file was only a thin link list and did not behave like a practical decision checklist;
+2. it told readers to choose concrete `using-form-*` skills without pointing them to `field-selection.md`, which is the actual field-routing grid named by the parent skill;
+3. it did not clearly distinguish business-form workflow decisions from query-page workflow decisions;
+4. it did not send readers to `examples.md` or `gotchas.md` when the next problem was scenario fit or edge-case routing.
+
+Applied update scope:
+
+- `building-form-workflows/references/workflow.md`
+
+Expected verification outcome:
+
+- the workflow guide now starts with the business-form versus query-page boundary;
+- it routes through `using-form-item`, `using-form-fields`, and `field-selection.md` in a clearer order;
+- it tells readers when to reuse field semantics in `using-query-form` without collapsing the two workflows together;
+- it links out to `gotchas.md` and `examples.md` for final checks instead of duplicating those files inline.
+
+Verification completed on 2026-03-25 by rereading the updated workflow guide against the neighboring router and wrapper skills listed above.
+
+### 2026-03-25 follow-up: building-query-pages workflow guide
+
+Follow-up audit against `building-query-pages/SKILL.md`, `building-query-pages/references/workflow.md`, `building-query-pages/references/field-selection.md`, `using-query-form/SKILL.md`, `using-data-table/SKILL.md`, `using-config-provider/SKILL.md`, `building-form-workflows/SKILL.md`, and `building-form-workflows/references/workflow.md` found four routing-quality gaps in the original workflow guide:
+
+1. the file was only a thin link list and did not behave like a practical page-shell decision checklist;
+2. it mentioned query-field routing but did not send readers through `field-selection.md`, where the query-specific field grid actually lives;
+3. it did not explain clearly enough when `ConfigProvider` belongs in the page decision versus when table customization should stay local;
+4. it pointed toward `building-form-workflows` but did not explain the scope split between query-page shell decisions and business-form wrapper semantics.
+
+Applied update scope:
+
+- `building-query-pages/references/workflow.md`
+
+Expected verification outcome:
+
+- the workflow guide now starts with the query-page versus business-form boundary;
+- it routes through `using-query-form`, `using-data-table`, and `field-selection.md` in a clearer order;
+- it gives a narrower and more explicit decision for introducing `using-config-provider`;
+- it keeps `building-form-workflows` as a handoff for wrapper semantics without duplicating that workflow inline.
+
+Verification completed on 2026-03-25 by rereading the updated workflow guide against the neighboring shell and router skills listed above.
+
+### 2026-03-25 follow-up: selection-guide dedupe
+
+Follow-up audit against `choosing-components/SKILL.md`, `choosing-components/references/selection-guide.md`, `building-selection-inputs/SKILL.md`, `building-selection-inputs/references/selection-guide.md`, `using-select/SKILL.md`, `using-data-select/SKILL.md`, `using-checkbox-group/SKILL.md`, and `using-radio-group/SKILL.md` found four routing-quality gaps in the original pair of guides:
+
+1. the two `selection-guide.md` files repeated nearly the same direct-component and wrapper-routing logic;
+2. the top-level `choosing-components` guide was too deep in selection-specific content for a top-level router;
+3. the specialist `building-selection-inputs` guide did not go deep enough on the actual selection-control decision sequence;
+4. the pair did not clearly separate top-level family routing from selection-specific UX, data-source, and abstraction-level decisions.
+
+Applied update scope:
+
+- `choosing-components/references/selection-guide.md`
+- `building-selection-inputs/references/selection-guide.md`
+
+Expected verification outcome:
+
+- the `choosing-components` guide now acts as a top-level handoff layer instead of a duplicate specialist guide;
+- the `building-selection-inputs` guide now owns the concrete selection-control routing sequence;
+- direct-component versus wrapper routing still exists, but only the specialist guide carries the deeper decision ordering;
+- duplication between the two guides is materially reduced.
+
+Verification completed on 2026-03-25 by rereading both updated guides against their parent router skills and the adjacent direct selection skills listed above.
+
+### 2026-03-25 follow-up: field-selection dedupe
+
+Follow-up audit against `building-form-workflows/SKILL.md`, `building-form-workflows/references/field-selection.md`, `building-query-pages/SKILL.md`, `building-query-pages/references/field-selection.md`, `using-form-select/SKILL.md`, `using-form-autocomplete/SKILL.md`, `using-form-date-picker/SKILL.md`, `using-form-switch/SKILL.md`, and `using-data-select/SKILL.md` found four routing-quality gaps in the original pair of guides:
+
+1. both field-selection guides repeated most of the same wrapped-field categories;
+2. the business-form field grid did not clearly establish itself as the canonical base map for stored-value semantics;
+3. the query-page field grid repeated too much of the base field catalog instead of focusing on query-specific extensions such as request-driven option loading;
+4. the pair did not make the distinction clear enough between data-entry semantics and filter-surface semantics.
+
+Applied update scope:
+
+- `building-form-workflows/references/field-selection.md`
+- `building-query-pages/references/field-selection.md`
+
+Expected verification outcome:
+
+- the business-form field guide now acts as the canonical stored-value routing grid;
+- the query-page field guide now acts as an extension layer on top of that base map;
+- query-specific option-loading guidance is kept where it belongs;
+- duplication between the two field grids is materially reduced without collapsing their distinct roles.
+
+Verification completed on 2026-03-25 by rereading both updated guides against their parent router skills and the adjacent field skills listed above.
+
+### 2026-03-25 follow-up: using-config-provider
+
+Follow-up audit against `using-config-provider/SKILL.md`, `using-config-provider/references/{props,examples,gotchas}.md`, `building-query-pages/SKILL.md`, `using-data-table/SKILL.md`, and package-facing ConfigProvider mentions found four routing-quality gaps in the original skill:
+
+1. it explained the slot-based contract correctly but did not clearly state when to choose provider-level sharing versus local `DataTable` slots;
+2. it did not explain clearly enough that this skill is usually a downstream choice after query/list shell routing;
+3. package-facing docs hinted at locale-oriented copy responsibilities, but the skill gave no guidance on how to interpret those signals safely;
+4. the non-fit boundary against a broad global configuration system was present but could be stated more explicitly.
+
+Applied update scope:
+
+- `using-config-provider/SKILL.md`
+
+Expected verification outcome:
+
+- the skill now makes provider-vs-local-slot choice clearer;
+- it acknowledges its normal relationship to `building-query-pages` and `using-data-table`;
+- it treats README capability hints cautiously without overstating undocumented surface area;
+- its fit and non-fit guidance is sharper for LLM routing.
+
+Verification completed on 2026-03-25 by rereading the updated skill against its references plus the adjacent query-page and data-table skills named above.
+
+### 2026-03-25 follow-up: building-modal-workflows references
+
+Follow-up audit against `building-modal-workflows/SKILL.md`, `building-modal-workflows/references/{workflow,examples,gotchas}.md`, `using-modal/SKILL.md`, and `using-drawer/SKILL.md` found four routing-quality gaps in the original reference set:
+
+1. `workflow.md` stated the shell and close-handling principles but did not explain clearly enough how to route overlay body content into form versus query/list inner workflows;
+2. `examples.md` was too thin to help with overlay-content shape decisions and did not include a close-handling pattern;
+3. the reference set told readers to keep business-side close logic explicit but did not point clearly enough to the downstream shell examples where that pattern is demonstrated;
+4. `gotchas.md` did not explicitly warn that choosing the shell without checking the inner workflow can misroute the overlay design.
+
+Applied update scope:
+
+- `building-modal-workflows/references/workflow.md`
+- `building-modal-workflows/references/examples.md`
+- `building-modal-workflows/references/gotchas.md`
+
+Expected verification outcome:
+
+- overlay-content routing is now clearer between form content and query/list content;
+- close-handling guidance now points toward a concrete downstream shell pattern;
+- examples now cover short confirmations, side-panel editors, overlay-hosted forms, overlay-hosted query/list flows, and the minimum close-handling model;
+- the gotchas now warn more directly about shell choice without content-shape checks.
+
+Verification completed on 2026-03-25 by rereading the updated references against the parent overlay router and the adjacent `using-modal` and `using-drawer` skills.
+
+### 2026-03-25 follow-up: using-image
+
+Follow-up audit against `using-image/SKILL.md`, `using-image/references/{props,examples,gotchas}.md`, and package-facing Image wording found three routing-quality gaps in the original skill:
+
+1. the main skill mixed retry, refresh, and reload language in a way that made the public behavior naming less stable for LLM use;
+2. package-facing docs and local references did not present a perfectly uniform prop label, so the skill needed to emphasize the behavior contract more carefully than a single disputed name;
+3. the skill's common-mistake guidance referred too directly to one prop label instead of the safer product behavior: the built-in reload control after failure.
+
+Applied update scope:
+
+- `using-image/SKILL.md`
+
+Expected verification outcome:
+
+- the main skill now uses more consistent reload-after-failure language;
+- it keeps preview and empty-state routing intact while reducing terminology drift;
+- it warns readers to anchor on documented behavior when public docs use slightly different labels.
+
+Verification completed on 2026-03-25 by rereading the updated skill against its own references and the package-facing Image wording noted above.
+
+### 2026-03-25 follow-up: choosing-components examples
+
+Follow-up audit against `choosing-components/SKILL.md`, `choosing-components/references/examples.md`, `building-form-workflows/SKILL.md`, `building-query-pages/SKILL.md`, `building-modal-workflows/SKILL.md`, and `building-selection-inputs/SKILL.md` found three routing-quality gaps in the original examples file:
+
+1. the examples only covered the first hop into each workflow family and did not reflect the richer downstream handoffs added during the earlier workflow rewrites;
+2. there were no realistic compound scenarios such as overlays that host forms or query/list content, or selection controls that belong inside wrapped forms;
+3. the top-level router lacked an “unclear intent” example to help users classify whether their problem is really page shape, field choice, overlay shell, or selection modality.
+
+Applied update scope:
+
+- `choosing-components/references/examples.md`
+
+Expected verification outcome:
+
+- the top-level examples now look more like real product requests;
+- they route more clearly into the current downstream router boundaries;
+- they include compound and ambiguous entry cases instead of only single-family prompts.
+
+Verification completed on 2026-03-25 by rereading the updated examples against the current top-level and downstream router skills named above.
+
+### 2026-03-25 follow-up: selection parity batch
+
+Follow-up audit against `using-select/SKILL.md`, `using-data-select/SKILL.md`, `using-radio-group/SKILL.md`, `using-checkbox-group/SKILL.md`, `using-form-select/SKILL.md`, `using-form-checkbox-group/SKILL.md`, `using-form-radio-group/SKILL.md`, and `building-selection-inputs/SKILL.md` found three practical parity gaps after the router rewrites:
+
+1. `using-data-select` did not explain how to reason about request-driven selection inside wrapper flows and had no reciprocal handoff toward `using-form-select`;
+2. `building-selection-inputs` referenced generic `using-form-*` handoff in the body but did not list the wrapped selection destinations explicitly in its main related-skill section;
+3. `using-select` had a slightly confusing non-fit line that sent visible-choice cases to the router without acknowledging the concrete radio/checkbox alternatives.
+
+Applied update scope:
+
+- `using-data-select/SKILL.md`
+- `building-selection-inputs/SKILL.md`
+- `using-select/SKILL.md`
+
+Expected verification outcome:
+
+- request-aware dropdown routing now explains the wrapper boundary more explicitly;
+- the selection router now names the wrapped selection destinations directly instead of hiding them in references only;
+- the local select skill now points more cleanly toward visible-choice alternatives.
+
+Verification completed on 2026-03-25 by rereading the updated selection skills against the current selection router and adjacent direct/wrapper skill set.
+
+### 2026-03-26 follow-up: form foundation parity batch
+
+Follow-up audit against `using-form-item/SKILL.md`, `using-form-fields/SKILL.md`, `using-form-text/SKILL.md`, `using-form-number/SKILL.md`, `using-form-select/SKILL.md`, `using-form-autocomplete/SKILL.md`, and `building-form-workflows/SKILL.md` found three practical abstraction-level gaps after the router rewrites:
+
+1. `using-form-item` and `using-form-fields` did not clearly enough acknowledge `building-form-workflows` as the workflow layer above them;
+2. `using-form-fields` still looked slightly narrower than the actual family map because its inline family selection examples and related skills under-emphasized `FormAutocomplete` and the workflow router above it;
+3. `using-form-select` was strong as a concrete wrapped field, but its non-fit guidance did not clearly redirect users who were still deciding among wrapped field families rather than one select field in isolation.
+
+Applied update scope:
+
+- `using-form-item/SKILL.md`
+- `using-form-fields/SKILL.md`
+- `using-form-select/SKILL.md`
+- `using-query-form/SKILL.md`
+
+Expected verification outcome:
+
+- the base wrapper and family-level skills now state their relationship to the business-form workflow router more explicitly;
+- the family map now surfaces more wrapped-field destinations and the workflow-layer handoff more clearly;
+- the wrapped select skill now redirects earlier when the user is still at the family-selection stage and more clearly distinguishes itself from autocomplete or visible-choice wrappers;
+- `using-query-form` now makes wrapped select behavior more discoverable for common `valueType` routes.
+
+Verification completed on 2026-03-26 by rereading the updated form foundation skills against `building-form-workflows` and the surrounding wrapped-field skills.
+
+### 2026-03-26 follow-up: page-shell parity batch
+
+Follow-up audit against `using-data-table/SKILL.md`, `using-query-form/SKILL.md`, `using-modal/SKILL.md`, `using-drawer/SKILL.md`, `building-query-pages/SKILL.md`, `building-modal-workflows/SKILL.md`, and the corresponding workflow references found two practical shell-handoff gaps after the workflow/reference rewrites:
+
+1. the page-shell skills (`using-data-table`, `using-query-form`) did not acknowledge clearly enough that the same filter/list surfaces may live inside overlay shells rather than only normal page layouts;
+2. the narrow overlay skills (`using-modal`, `using-drawer`) linked to the overlay router but did not directly call out the most common inner body workflows: business forms and query/list shells.
+
+Applied update scope:
+
+- `using-data-table/SKILL.md`
+- `using-query-form/SKILL.md`
+- `using-modal/SKILL.md`
+- `using-drawer/SKILL.md`
+
+Expected verification outcome:
+
+- page-shell skills now mention overlay-shell hosting as a valid surrounding shell decision;
+- overlay-shell skills now expose clearer direct handoffs to business-form and query/list inner workflows;
+- reciprocal shell-level routing is stronger without changing the existing router hierarchy.
+
+Verification completed on 2026-03-26 by rereading the updated shell skills against the current page-shell and overlay-shell routers plus their workflow references.
+
+### 2026-03-26 follow-up: remaining choice-skill consistency batch
+
+Follow-up audit against `using-radio-group/SKILL.md`, `using-checkbox-group/SKILL.md`, `using-form-radio-group/SKILL.md`, `using-form-checkbox-group/SKILL.md`, `using-form-autocomplete/SKILL.md`, `building-selection-inputs/SKILL.md`, and `using-form-fields/SKILL.md` found one small but real parity gap after the earlier selection and form-foundation batches:
+
+1. the wrapped choice-oriented skills (`using-form-radio-group`, `using-form-checkbox-group`, `using-form-autocomplete`) still routed through `using-form-fields`, but did not explicitly acknowledge `building-selection-inputs` as the specialist selection router above the direct/wrapped choice split.
+
+Applied update scope:
+
+- `using-form-radio-group/SKILL.md`
+- `using-form-checkbox-group/SKILL.md`
+- `using-form-autocomplete/SKILL.md`
+
+Expected verification outcome:
+
+- the wrapped choice skills now expose a clearer route back to the specialist selection router;
+- reciprocal routing between selection-family guidance and wrapped choice skills is more explicit;
+- the change stays narrowly scoped and does not introduce broader wording churn.
+
+Verification completed on 2026-03-26 by rereading the updated wrapped choice skills against `building-selection-inputs`, `using-form-fields`, and their direct counterparts.
+
+### 2026-03-26 follow-up: selection examples depth batch
+
+Follow-up audit against `building-selection-inputs/references/examples.md`, `using-radio-group/references/examples.md`, `using-checkbox-group/references/examples.md`, `using-form-radio-group/references/examples.md`, `using-form-checkbox-group/references/examples.md`, `using-form-autocomplete/references/examples.md`, and `using-form-fields/references/examples.md` found a shared documentation-depth gap:
+
+1. the examples were mostly thin “Typical fit” bullet lists with little or no minimal usable pattern, so they helped classification slightly but did not help an LLM translate the routing decision into a smallest correct shape.
+
+Applied update scope:
+
+- `building-selection-inputs/references/examples.md`
+- `using-radio-group/references/examples.md`
+- `using-checkbox-group/references/examples.md`
+- `using-form-radio-group/references/examples.md`
+- `using-form-checkbox-group/references/examples.md`
+- `using-form-autocomplete/references/examples.md`
+- `using-form-fields/references/examples.md`
+
+Expected verification outcome:
+
+- the router-level examples now show concrete minimal routes instead of only forwarding to sibling skills;
+- the direct and wrapped choice examples now include small usable patterns alongside scenario fit;
+- the family-level form examples now include a more concrete base-wrapper-versus-concrete-wrapper scenario;
+- example depth is improved without turning these reference files into prop dumps.
+
+Verification completed on 2026-03-26 by rereading the updated examples against their parent skills and checking that the changes stayed within the targeted examples files plus this review log.
+
+### 2026-03-26 follow-up: form examples depth batch
+
+Follow-up audit against `building-form-workflows/references/examples.md`, `using-form-item/references/examples.md`, `using-form-fields/references/examples.md`, `using-form-text/references/examples.md`, `using-form-number/references/examples.md`, and `using-form-select/references/examples.md` found a similar documentation-depth gap on the form side:
+
+1. the examples were mostly scenario labels and “Typical fit” bullets, with little or no minimal pattern to translate the routing decision into a smallest usable wrapped-form shape.
+
+Applied update scope:
+
+- `building-form-workflows/references/examples.md`
+- `using-form-item/references/examples.md`
+- `using-form-fields/references/examples.md`
+- `using-form-text/references/examples.md`
+- `using-form-number/references/examples.md`
+- `using-form-select/references/examples.md`
+
+Expected verification outcome:
+
+- the workflow-level examples now show concrete mixed-form routes instead of only naming the next skill;
+- the base-wrapper and wrapped-field examples now include small usable patterns;
+- form example depth is improved without turning these files into prop dumps.
+
+Verification completed on 2026-03-26 by rereading the updated form examples against their parent skills and checking that the changes stayed within the targeted examples files plus this review log.
+
+### 2026-03-26 follow-up: shell examples depth batch
+
+Follow-up audit against `using-data-table/references/examples.md`, `using-query-form/references/examples.md`, `using-modal/references/examples.md`, `using-drawer/references/examples.md`, `building-query-pages/references/examples.md`, and `building-modal-workflows/references/examples.md` found a similar documentation-depth gap on the shell side:
+
+1. the router-level shell examples were still thinner than the narrower shell skills, and several shell examples relied on scenario labels or recommended-pattern bullets without giving a smallest usable pattern.
+
+Applied update scope:
+
+- `building-query-pages/references/examples.md`
+- `building-modal-workflows/references/examples.md`
+- `using-data-table/references/examples.md`
+- `using-query-form/references/examples.md`
+- `using-modal/references/examples.md`
+- `using-drawer/references/examples.md`
+
+Expected verification outcome:
+
+- the query-page and overlay router examples now show concrete minimal routes instead of mostly forwarding to sibling skills;
+- the page-shell and overlay-shell examples now include minimal usable patterns alongside scenario fit;
+- shell example depth is improved without turning these files into prop dumps.
+
+Verification completed on 2026-03-26 by rereading the updated shell examples against their parent skills and checking that the changes stayed within the targeted examples files plus this review log.
+
+### 2026-03-26 follow-up: gotchas depth batch
+
+Follow-up audit against `building-selection-inputs/references/gotchas.md`, `using-radio-group/references/gotchas.md`, `using-checkbox-group/references/gotchas.md`, `using-form-radio-group/references/gotchas.md`, `using-form-checkbox-group/references/gotchas.md`, `using-form-autocomplete/references/gotchas.md`, `using-data-table/references/gotchas.md`, `using-query-form/references/gotchas.md`, `using-modal/references/gotchas.md`, `using-drawer/references/gotchas.md`, and `building-modal-workflows/references/gotchas.md` found a depth imbalance:
+
+1. the selection-oriented gotchas were mostly thin routing reminders rather than concrete misuse warnings;
+2. the overlay router gotchas were accurate but still missed two high-value decision traps already implied by the parent skill: choosing the shell by habit and confusing visibility control with action handling.
+
+Applied update scope:
+
+- `building-selection-inputs/references/gotchas.md`
+- `using-radio-group/references/gotchas.md`
+- `using-checkbox-group/references/gotchas.md`
+- `using-form-radio-group/references/gotchas.md`
+- `using-form-checkbox-group/references/gotchas.md`
+- `using-form-autocomplete/references/gotchas.md`
+- `building-modal-workflows/references/gotchas.md`
+
+Expected verification outcome:
+
+- the selection gotchas now warn about routing order, short-versus-long option visibility, and the most common misfit choices;
+- the wrapped choice gotchas now route more clearly back to the specialist selection router when the field family is still undecided;
+- the overlay gotchas now call out shell-by-habit and visibility-versus-action confusion more directly.
+
+Verification completed on 2026-03-26 by rereading the updated gotchas against their parent skills and checking that the changes stayed within the targeted gotchas files plus this review log.
+
+### 2026-03-26 follow-up: props/reference consistency batch
+
+Follow-up audit against `using-radio-group/references/props.md`, `using-checkbox-group/references/props.md`, `using-form-radio-group/references/props.md`, `using-form-checkbox-group/references/props.md`, `using-form-autocomplete/references/props.md`, `using-query-form/references/props.md`, `using-modal/references/props.md`, and `using-drawer/references/props.md` found a clear split:
+
+1. the higher-level shell references were already reasonably explicit about defaults and contract behavior;
+2. the choice-oriented props references were still closer to prop lists than to minimum-setup guides, and under-explained the real source-of-truth props and common value-shape interactions.
+
+Applied update scope:
+
+- `using-radio-group/references/props.md`
+- `using-checkbox-group/references/props.md`
+- `using-form-radio-group/references/props.md`
+- `using-form-checkbox-group/references/props.md`
+- `using-form-autocomplete/references/props.md`
+
+Expected verification outcome:
+
+- the direct and wrapped choice props references now start with a clearer minimum setup;
+- they explain the real source-of-truth props (`options`, `valueEnum`, `fetchSuggestions`) more directly;
+- they warn more clearly about value-shape alignment and premature slot customization.
+
+Verification completed on 2026-03-26 by rereading the updated props references against their parent skills and checking that the changes stayed within the targeted props files plus this review log.
+
+### 2026-03-26 follow-up: Batch A — wrapped scalar and date/time fields
+
+Follow-up audit against `using-form-switch`, `using-form-date-picker`, and `using-form-time-picker` found a familiar reference-depth gap rather than a router failure:
+
+1. the three `SKILL.md` files already had solid boundary guidance and clean family-level handoffs;
+2. the main weakness was in the references, especially thin `examples.md` files with scenario labels but no minimal code patterns;
+3. `using-form-time-picker/references/props.md` lagged behind the stronger date-picker reference by under-documenting `modelValue` and `valueFormat` as important field-shape props.
+
+Applied update scope:
+
+- `using-form-switch/references/props.md`
+- `using-form-switch/references/examples.md`
+- `using-form-date-picker/references/examples.md`
+- `using-form-time-picker/references/props.md`
+- `using-form-time-picker/references/examples.md`
+
+Expected verification outcome:
+
+- the switch/date/time wrapper examples now include minimal usable patterns instead of only scenario labels;
+- `FormTimePicker` props now explain the core value-shape props more clearly;
+- these three skills now sit closer to parity with the stronger wrapped-field references.
+
+Verification completed on 2026-03-26 by rereading the updated references against their parent skills and checking that the changes stayed within the targeted files plus this review log.
+
+### 2026-03-26 follow-up: Batch B — hierarchical and collection wrapped fields
+
+Follow-up audit against `using-form-tree-select`, `using-form-cascade-select`, and `using-form-tag-input` found that the main weakness was not routing failure but parity depth:
+
+1. the core `SKILL.md` files already had good boundary guidance, especially tree-versus-cascade and tag-input-versus-autocomplete/select distinctions;
+2. the main reference gap was thin `examples.md` files with no minimal code patterns;
+3. the wrapped hierarchical and collection skills also benefited from more explicit workflow-level related-skill links and one additional high-value gotcha each.
+
+Applied update scope:
+
+- `using-form-tree-select/SKILL.md`
+- `using-form-tree-select/references/examples.md`
+- `using-form-tree-select/references/gotchas.md`
+- `using-form-cascade-select/SKILL.md`
+- `using-form-cascade-select/references/examples.md`
+- `using-form-cascade-select/references/gotchas.md`
+- `using-form-tag-input/SKILL.md`
+- `using-form-tag-input/references/examples.md`
+- `using-form-tag-input/references/gotchas.md`
+
+Expected verification outcome:
+
+- the tree/cascade/tag wrappers now expose clearer links back to the business-form workflow router;
+- their examples now include minimal usable patterns instead of only scenario labels;
+- their gotchas now surface one more contract-level misuse warning each.
+
+Verification completed on 2026-03-26 by rereading the updated skills and references against their parent form-family skills and checking that the changes stayed within the targeted files plus this review log.
+
+### 2026-03-26 follow-up: Batch C — specialized scalar field
+
+Follow-up audit against `using-form-rate` found a smaller parity gap than the earlier batches:
+
+1. the core skill already had good boundary guidance against radio-style named choices and true numeric controls;
+2. the remaining weakness was reference depth, especially the examples file still using only scenario labels with no minimal code patterns;
+3. the skill also benefited from one explicit workflow-layer related-skill link and clearer selection-family/non-fit cross-links so it matches the newer wrapped-field pattern.
+
+Applied update scope:
+
+- `using-form-rate/SKILL.md`
+- `using-form-rate/references/props.md`
+- `using-form-rate/references/examples.md`
+- `using-form-rate/references/gotchas.md`
+
+Expected verification outcome:
+
+- `FormRate` now links back to the business-form workflow router more explicitly;
+- it now links more clearly to the selection-family router and nearby wrapper alternatives;
+- its examples now include minimal usable patterns instead of only scenario labels;
+- its props and gotchas now better explain score semantics versus radio/checkbox/number alternatives;
+- the skill now sits closer to parity with the stronger wrapped-field references.
+
+Verification completed on 2026-03-26 by rereading the updated skill and examples against the parent form-family skills and checking that the changes stayed within the targeted files plus this review log.
+
+### Change log
+
+- 2026-03-25: Created review log and initialized audit inventory.
+- 2026-03-25: Completed Round 1 first-pass audit for routers, shells/direct components, and form skills; recorded recommendations and set all current skills to `reviewed-awaiting-confirmation`.
+- 2026-03-25: Organized the current cleanup queue by priority inside this review log and recorded the follow-up `using-ellipsis-text` update scope and evidence.
+- 2026-03-25: Verified the `using-ellipsis-text` rewrite against `EllipsisText` source, tooltip props, and stories; status set to `verified`.
+- 2026-03-25: Updated `building-form-workflows/references/workflow.md` to add practical routing guidance, explicit field-grid handoff, and clearer boundary lines against query-page workflows.
+- 2026-03-25: Verified the `building-form-workflows` workflow-guide rewrite against adjacent router and wrapper skills; status set to `verified`.
+- 2026-03-25: Updated `building-query-pages/references/workflow.md` to add clearer page-shell routing, explicit query-field-grid handoff, and a narrower `ConfigProvider` decision path.
+- 2026-03-25: Verified the `building-query-pages` workflow-guide rewrite against adjacent shell and router skills; status set to `verified`.
+- 2026-03-25: Updated the duplicated selection guides so `choosing-components` stays top-level and `building-selection-inputs` owns the specialist routing details.
+- 2026-03-25: Verified the deduplicated selection guides against parent routers and adjacent selection-control skills; statuses set to `verified`.
+- 2026-03-25: Updated the duplicated field-selection guides so business-form routing stays canonical and query-page routing becomes an extension layer.
+- 2026-03-25: Verified the deduplicated field-selection guides against parent routers and adjacent field skills; statuses set to `verified`.
+- 2026-03-25: Updated `using-config-provider/SKILL.md` to clarify provider-vs-local-slot routing, downstream shell positioning, and the safest interpretation of package-facing capability signals.
+- 2026-03-25: Verified the `using-config-provider` skill rewrite against adjacent shell skills and its own references; status set to `verified`.
+- 2026-03-25: Updated `building-modal-workflows` references to strengthen overlay-content routing and close-handling guidance.
+- 2026-03-25: Verified the `building-modal-workflows` reference rewrite against adjacent overlay shell skills; status set to `verified`.
+- 2026-03-25: Updated `using-image/SKILL.md` to prefer stable reload-after-failure wording over mixed retry/refresh terminology.
+- 2026-03-25: Verified the `using-image` skill rewrite against its references and package-facing wording; status set to `verified`.
+- 2026-03-25: Expanded `choosing-components/references/examples.md` into a richer top-level entry scenario set with clearer downstream handoffs.
+- 2026-03-25: Verified the `choosing-components` examples rewrite against the current downstream router map; status set to `verified`.
+- 2026-03-25: Started a new selection parity batch and updated `using-data-select`, `building-selection-inputs`, and `using-select` to tighten direct-versus-wrapper routing guidance.
+- 2026-03-25: Verified the selection parity batch updates against adjacent selection skills; `using-select` and `using-data-select` statuses set to `verified`.
+- 2026-03-26: Started a new form foundation parity batch and updated `using-form-item`, `using-form-fields`, and `using-form-select` to tighten wrapper-family and workflow-layer routing guidance.
+- 2026-03-26: Verified the form foundation parity batch updates against adjacent wrapper skills; `using-form-item`, `using-form-fields`, `using-form-select`, and `using-query-form` statuses set to `verified`.
+- 2026-03-26: Started a new page-shell parity batch and updated `using-data-table`, `using-query-form`, `using-modal`, and `using-drawer` to tighten shell-level reciprocal handoffs.
+- 2026-03-26: Verified the page-shell parity batch updates against adjacent routers and workflow references; `using-data-table`, `using-query-form`, `using-modal`, and `using-drawer` statuses set to `verified`.
+- 2026-03-26: Started a remaining choice-skill consistency batch and updated `using-form-radio-group`, `using-form-checkbox-group`, and `using-form-autocomplete` to add clearer selection-router handoffs.
+- 2026-03-26: Verified the remaining choice-skill consistency batch against adjacent selection routers and wrapped-field skills; `using-form-radio-group`, `using-form-checkbox-group`, and `using-form-autocomplete` statuses set to `verified`.
+- 2026-03-26: Started a selection examples depth batch and expanded the thinnest selection-related examples files into minimal scenario-driven patterns.
+- 2026-03-26: Verified the selection examples depth batch against parent skills and target file scope.
+- 2026-03-26: Started a form examples depth batch and expanded the thinnest form-related examples files into minimal scenario-driven patterns.
+- 2026-03-26: Verified the form examples depth batch against parent skills and target file scope.
+- 2026-03-26: Started a shell examples depth batch and expanded the shell/router examples files into minimal scenario-driven patterns.
+- 2026-03-26: Verified the shell examples depth batch against parent skills and target file scope.
+- 2026-03-26: Started a gotchas depth batch and expanded the thinnest selection and overlay gotchas files into sharper misuse warnings.
+- 2026-03-26: Verified the gotchas depth batch against parent skills and target file scope.
+- 2026-03-26: Started a props/reference consistency batch and tightened the thinnest choice-oriented props references around minimum setup and source-of-truth props.
+- 2026-03-26: Verified the props/reference consistency batch against parent skills and target file scope.
+- 2026-03-26: Started Batch A from the next-wave plan and strengthened the thinnest switch/date/time wrapped-field references.
+- 2026-03-26: Verified Batch A against parent skills and target file scope; `using-form-switch`, `using-form-date-picker`, and `using-form-time-picker` statuses set to `verified`.
+- 2026-03-26: Started Batch B from the next-wave plan and strengthened the thinnest tree/cascade/tag wrapped-field references.
+- 2026-03-26: Verified Batch B against parent skills and target file scope; `using-form-tree-select`, `using-form-cascade-select`, and `using-form-tag-input` statuses set to `verified`.
+- 2026-03-26: Started Batch C from the next-wave plan and strengthened the remaining wrapped rating-field references.
+- 2026-03-26: Verified Batch C against parent skills and target file scope; `using-form-rate` status set to `verified`.