Savaity/search skill experiment

.github/skills/find-package-skill/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: find-package-skill
+description: '**UTILITY SKILL** — Must be consulted before making any changes to packages under sdk/. Provides package-specific domain knowledge that prevents common mistakes. WHEN: "add feature to package", "fix bug in package", "modify package code", "regenerate from typespec", "change client library".'
+---
+
+# Find Package Skill
+
+Before modifying any SDK package in this monorepo, check this registry to see
+if a package-specific skill exists. Package skills contain tribal knowledge
+(architecture, data flows, type mappings, pitfalls) that prevents common mistakes.
+
+Always check this registry before modifying any SDK package — even if you think
+you already know the package well.
+
+## How to Use
+
+1. Find the package you're modifying in the table below.
+2. Read the SKILL.md at the listed path using the Read tool. Then read all files under the `references/` directory next to it for additional context.
+3. If the package isn't listed, no package-specific skill exists yet — proceed normally.
+
+## Package Skills
+
+| Package                    | Path                                                                                              |
+| -------------------------- | ------------------------------------------------------------------------------------------------- |
+| `azure-search-documents`   | `sdk/search/azure-search-documents/.github/skills/Azure.Search.Documents/SKILL.md`                |

sdk/search/azure-search-documents/.github/skills/Azure.Search.Documents/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: search-documents
+description: 'Post-regeneration customization guide for azure-search-documents Java SDK. After running tsp-client update, consult this skill to re-apply search-specific customizations and produce a production-ready SDK. WHEN: regenerate search SDK; search tsp-client update; fix search customization errors; search API version update; search SDK release; update search service version.'
+---
+
+# azure-search-documents — Package Skill (Java)
+
+## When to Use This Skill
+
+Activate when user wants to:
+- Regenerate the search SDK from TypeSpec (`tsp-client update`)
+- Update to a new API spec version (new commit SHA)
+- Fix compilation errors after regeneration
+- Prepare a new GA or preview release of azure-search-documents
+- Understand the SDK architecture or customization patterns
+
+## Prerequisites
+
+- Read [references/architecture.md](references/architecture.md) — source layout, generated vs. custom split, package map, service version rules
+- Read [references/customizations.md](references/customizations.md) — JavaParser AST patterns, `SearchCustomizations.java`, backward-compat retention
+
+## Common Pitfalls
+
+- **Never hand-edit generated files.** Files with `// Code generated by Microsoft (R) TypeSpec Code Generator.` are overwritten on every `tsp-client update`. All modifications go through `SearchCustomizations.java`.
+- **Methods without `@Generated` in generated files are hand-written.** These are convenience wrappers that the generator preserves but does NOT update. After regeneration, you must manually update them to match any changed generated signatures.
+- **`SearchCustomizations.java` is the first place to look when generated files have errors.** The customizations run during generation and can produce broken output if the generated code structure changed.
+- **The `hideWithResponseBinaryDataApis` customization is the most fragile.** It rewires method bodies across packages and can create cross-package import mismatches after spec changes.
+- **`includeOldApiVersions` can create duplicate enum constants.** If the generator starts producing a version that was previously only in the customization list, you get a compilation error.
+
+## Steps
+
+### Phase 0 — Determine Scope
+
+Ask the user:
+1. New API version or re-generation of current spec?
+2. GA release or beta/preview release?
+3. Target release date (for changelog)?
+
+If new API version: get the new spec **commit SHA** and **API version string** (e.g., `2026-05-01-preview`).
+
+> **STOP** if the user cannot provide the commit SHA — do not guess or use HEAD.
+
+### Phase 1 — Update `tsp-location.yaml`
+
+*(Skip if commit SHA is not changing)*
+
+Set `commit` to the new SHA in `sdk/search/azure-search-documents/tsp-location.yaml`. Leave other fields unchanged.
+
+### Phase 2 — Generate SDK from TypeSpec
+
+```powershell
+tsp-client update
+```
+
+### Phase 3 — Build and Fix Errors
+
+1. Run `mvn clean compile -f sdk/search/azure-search-documents/pom.xml`
+2. If there are errors, categorize each one:
+
+| Error location | What it means | Where to fix |
+|---------------|---------------|--------------|
+| Generated file, `@Generated` method | Customization in `SearchCustomizations.java` produced broken output | **Fix `SearchCustomizations.java`** — update AST queries to match new generated code |
+| Generated file, method WITHOUT `@Generated` | Hand-written convenience wrapper references changed generated types | **Fix the hand-written method** — update it to match the new generated API (look at how `@Generated` methods in the same file were updated) |
+| Hand-written file (`SearchUtils.java`, `FieldBuilder.java`, batching, tests) | References removed/renamed generated types | **Fix the hand-written file** |
+
+3. **Check `SearchCustomizations.java` FIRST.** The most common post-regeneration errors come from:
+   - `hideWithResponseBinaryDataApis()` — rewires methods across packages, can create import mismatches
+   - `includeOldApiVersions()` — can duplicate enum constants the generator now produces
+   - `addSearchAudienceScopeHandling()` — may fail if builder structure changed
+4. Run `mvn clean compile` after every fix to check for remaining errors.
+
+**Gate:** Clean build — zero errors from `mvn clean compile`.
+
+### Phase 3.5 — Verify Service Version
+
+`SearchServiceVersion.java` is generated by TypeSpec but customized by `SearchCustomizations.java`.
+
+1. Check `SearchServiceVersion.java` — verify `getLatest()` returns the new version
+2. Check `includeOldApiVersions()` in `SearchCustomizations.java`:
+   - **Remove** any version from the list that the generator now produces (prevents duplicate enum constants)
+   - **Add** the previous latest version if it's NOT already produced by the generator
+3. Verify all expected old versions are present in the enum
+
+**Gate:** `SearchServiceVersion` enum contains all required versions with no duplicates.
+
+### Phase 3.6 — Detect Breaking Changes
+
+```powershell
+# List removed/renamed public types
+git diff --name-status HEAD -- sdk/search/azure-search-documents/src/main/java/ | Select-String "^D"
+
+# Check for renamed enum constants or changed method signatures
+git diff HEAD -- sdk/search/azure-search-documents/src/main/java/ | Select-String "^-.*public static final|^-.*public.*(" | Select-Object -First 30
+```
+
+Watch for:
+- **Removed types** — classes/enums deleted by the new spec
+- **Renamed constants** — need `@Deprecated` aliases for backward compat
+- **Changed property types** — e.g., `String` → enum type (source-breaking)
+- **Removed method overloads** — existing callers will break
+
+Document all breaking changes for the changelog.
+
+### Phase 3.7 — Clean Up Imports
+
+After fixing compilation errors, remove unused imports from hand-written files: `SearchUtils.java`, test files, sample files.
+
+### Phase 4 — Run Tests
+
+1. Run `mvn test -f sdk/search/azure-search-documents/pom.xml`
+2. If tests reference removed types/methods, update them.
+3. If test recordings are stale, update `assets.json` and re-record. Remove tests for removed features.
+4. Live tests only if provisioned service is available (requires environment variables).
+
+**Gate:** All non-live tests pass.
+
+### Phase 5 — Update Changelog
+
+Fill `CHANGELOG.md` under the current unreleased version:
+
+```markdown
+## X.Y.Z-beta.N (Unreleased)
+
+### Features Added
+- Added `NewModel` for ...
+
+### Breaking Changes
+- Removed `OldModel` (replaced by ...)
+- Renamed `OLD_CONSTANT` to `NEW_CONSTANT` on `SomeEnum`
+
+### Other Changes
+- Updated service API version to `2026-XX-XX`
+```
+
+### Phase 6 — Update Version
+
+```xml
+<version>12.0.0-beta.1</version> <!-- {x-version-update;com.azure:azure-search-documents;current} -->
+```
+
+### Phase 7 — Final Validation
+
+- [ ] `mvn clean compile` — zero errors
+- [ ] `mvn test` — all non-live tests pass
+- [ ] `CHANGELOG.md` complete with all breaking changes
+- [ ] No unused imports
+
+## Execution Order Summary
+
+| Phase | Action | Gate |
+|-------|--------|------|
+| 0 | Determine scope | User provides commit SHA |
+| 1 | Update `tsp-location.yaml` | — |
+| 2 | Generate (`tsp-client update`) | — |
+| 3 | Build, fix errors — **check `SearchCustomizations.java` first** | Zero errors |
+| 3.5 | Verify `SearchServiceVersion` — remove duplicates, add missing | No duplicate enum constants |
+| 3.6 | Detect breaking changes | Documented |
+| 3.7 | Clean up imports | — |
+| 4 | Run tests, update recordings | All non-live pass |
+| 5 | Update changelog | — |
+| 6 | Bump version | — |
+| 7 | Final validation | Clean build + tests |
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [references/architecture.md](references/architecture.md) | Source layout, generated vs. custom split, `@Generated` annotation meaning, key files |
+| [references/customizations.md](references/customizations.md) | JavaParser AST patterns, `SearchCustomizations.java` methods, per-customization update guidance |