# Phase 0: Scan Package 🧭

> 📍 **Phase 0 — Scan Package** | Detect the package's architecture, customization patterns, and key files.

## Step 1 — Identify the Package

Ask the user: "Which SDK package should I create a skill for?"

The user should provide either:
- A package name (e.g., `azure-search-documents`, `azure-ai-projects`, `azure-mgmt-appconfiguration`)
- A path (e.g., `sdk/search/azure-search-documents`, `sdk/ai/azure-ai-projects`)

Resolve to the package root directory. Verify it exists and contains at least one of: `pyproject.toml`, `setup.py`, `tsp-location.yaml`, or a `swagger/README.md` (legacy autorest).

## Step 2 — Scan the Package

Scan the package using the checklist below. Use file_search / grep_search / read_file tools.

### Scan Checklist

1. **Code generation toolchain**:
   - `tsp-location.yaml` → TypeSpec-generated package. Note the spec directory and commit SHA.
   - `_metadata.json` → if present, record that `apiVersion` lives here (the skill will reconcile it against the hand-maintained `ApiVersion` enum).
   - `swagger/README.md` → legacy autorest-generated (mgmt packages typically).
   - Neither → hand-written package (rare).

2. **Namespace root**: Derive from the package name by replacing `-` with `/` (e.g., `azure-ai-projects` → `<package-path>/azure/ai/projects`). Verify the directory exists.

3. **Generated layout detection**:
   - If `<namespace-root>/_generated/` exists → **nested layout**. Generated files are confined to `_generated/`; everything else is hand-written/customization.
   - If `_generated/` is absent → **inline layout** (newer pattern). Generated files are identified by the header comment `"Code generated by Microsoft (R) Python Code Generator"` at the top of each file.

4. **Customizations** (`_patch.py` at each level):
   - `<namespace-root>/_patch.py` — top-level client customization
   - `<namespace-root>/models/_patch.py` — model customization
   - `<namespace-root>/operations/_patch.py` — sync operations customization
   - `<namespace-root>/aio/_patch.py` — async client customization
   - `<namespace-root>/aio/operations/_patch.py` — async operations customization

   For each, check if it is **empty** (only copyright header, default docstring, empty `__all__`, empty `patch_sdk()`) or **non-empty** (defines classes/functions, or `__all__` has entries). Record the non-empty patches.

5. **Hand-written utility modules**: Glob all `.py` files under `<namespace-root>` excluding `_generated/`, `__init__.py`, `_version.py`, `_patch.py`. Classify each as generated (has the header) or custom. For custom utility modules, read the first few lines to get a one-line purpose.

6. **Public API surface**: Read each `__init__.py` (top-level, `models/`, `operations/`, `aio/`, `aio/operations/`). Note re-exports from `_patch.py` and any renames/omissions vs `_generated/__init__.py` (when nested layout).

7. **Async parity**: For each non-empty sync customization file, check whether the async counterpart exists under `aio/`. Record `identical`, `equivalent`, `divergent`, `sync-only`, or `async-only`.

8. **Service API versions**: Search for an `ApiVersion` enum or `api_version` constants under `<namespace-root>` (often inside `_patch.py` itself, not `_generated/`). Record the source file path, but do **not** hard-code the list of versions into the skill — point to the source file.

9. **Hand-authored named classes**: Grep for `class .*Buffered|class .*Batching|class .*Sender|class .*Paged|class .*PageIterator` under `<namespace-root>`. These are hand-authored utilities that the skill must name in its Customization Patterns Reference.

10. **Top public symbols (for import smoke tests)**: Read the top-level `__init__.py` and `aio/__init__.py`. Record up to 3–5 most important public names (clients, senders, key models/enums) so Phase 1 can generate accurate `python -c "from <ns> import <X>"` commands.

11. **Tests**: Check `tests/` directory. Look for `conftest.py`, `*test_base*.py`, `assets.json` (recorded tests via Test Proxy), `testpreparer*.py`. Note whether tests are live, recorded, or both.

12. **Documentation surfaces**: Check for `CHANGELOG.md` and `README.md` at the package root. Both are near-universal; the skill's Step 7 (Update Documentation and Samples) will reference them.

13. **Management vs data plane**: If package name starts with `azure-mgmt-` → management-plane rules apply (see copilot-instructions). Otherwise data-plane.

## Step 3 — Present Package Profile

Print a concise summary:

📋 **Package Profile**

| Field | Value |
|---|---|
| Package | `<package-name>` (e.g., `azure-ai-projects`) |
| Path | `sdk/<service>/<package-name>` |
| Plane | data / mgmt |
| Generated | TypeSpec (`tsp-location.yaml`) / autorest (`swagger/README.md`) / hand-written |
| Metadata | `_metadata.json` present: Y/N |
| Layout | nested (`_generated/`) / inline (header-based) |
| Non-empty `_patch.py` files | List which levels have customizations (top / models / operations / aio / aio/operations / indexes…) |
| Custom utility modules | N hand-written `.py` files outside `_patch.py` |
| Hand-authored named classes | e.g., `SearchIndexingBufferedSender`, `SearchItemPaged` (or `none`) |
| Top public symbols | List of 3–5 names used for Phase 1 import smoke tests |
| Public API surface | Notes on re-exports, renames, omissions |
| Async parity | summary (identical / divergent / sync-only / async-only) |
| `ApiVersion` enum | source file + present Y/N |
| Tests | Unit: Y, Live: Y/N, Recorded (assets.json): Y/N |
| Docs | `CHANGELOG.md`: Y/N, `README.md`: Y/N |
| Suggested structure | Option A (step-by-step) / Option B (reference manual) |

## Step 4 — DECIDE

Question: "Does this profile look right? Anything to add or correct?"

📍 **Phase 0 complete** | Package scanned | Next: Phase 1

---
## → Next: Phase 1 — Scaffold SKILL.md
Read [01-scaffold-skill.md](01-scaffold-skill.md) and begin immediately.
