started prompt mechanics

docs/skills/pytest-scaffolding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pytest-scaffolding
-description: "Reference hub for pytest suite structure, naming, markers, and stack-specific testing patterns. Use when you need best-practice guidance and source links for core pytest, FastAPI testing, and SQLAlchemy testing."
+description: "Reference hub for pytest suite structure, naming, markers, and stack-specific testing patterns. Optimized for progressive discovery so naming and hierarchy guidance are loaded first when shaping or reorganizing tests."
 argument-hint: "Target scope plus stack details (pure Python, FastAPI, SQLAlchemy sync, SQLAlchemy async, or mixed)"
 x-personal-mcp:
   id: pytest-scaffolding
@@ -29,24 +29,50 @@ Repository defaults:
 - pytest settings live in `pyproject.toml` under `[tool.pytest.ini_options]`.
 - strict marker checking is expected (`--strict-markers`).
 
-## Reference Map
+## Progressive Discovery Start
 
-Use this map to open only the reference that matches your immediate need.
+Use this load order by default so guidance stays targeted and naming conventions are pulled in early:
 
-- Core pytest practices and command patterns: [pytest-docs.md](./references/pytest-docs.md)
-- Naming conventions and hierarchy organization: [naming-and-organization.md](./references/naming-and-organization.md)
-- FastAPI-specific testing patterns: [fastapi-testing.md](./references/fastapi-testing.md)
-- SQLAlchemy-specific testing patterns: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)
+1. Classify intent first: naming and organization, baseline pytest mechanics, FastAPI testing, SQLAlchemy testing, or mixed.
+2. For create/restructure/rename tasks, load [naming-and-organization.md](./references/naming-and-organization.md) first.
+3. Load [pytest-docs.md](./references/pytest-docs.md) next for fixture and marker defaults.
+4. Load at most one stack-specific reference unless the request is explicitly mixed stack.
+5. If confidence is low after two references, ask one clarifying question before loading more.
+
+Load budget defaults:
+
+1. Single-stack task: 1 to 2 references.
+2. Mixed-stack task: up to 3 references.
+3. Avoid loading all references unless the user explicitly asks for a broad audit.
+
+## Intent Router
+
+Open only the reference that matches the immediate task.
+
+1. Naming, file layout, discovery prefixes, class/function naming: [naming-and-organization.md](./references/naming-and-organization.md)
+2. Fixture layering, marker policy, collect-only and fast-path commands: [pytest-docs.md](./references/pytest-docs.md)
+3. Route tests, dependency overrides, lifespan handling: [fastapi-testing.md](./references/fastapi-testing.md)
+4. Session and transaction fixtures, async ORM behavior: [sqlalchemy-testing.md](./references/sqlalchemy-testing.md)
+
+## Naming Pull-In Triggers
+
+Always consult [naming-and-organization.md](./references/naming-and-organization.md) before recommending structure when any of these are true:
+
+1. New tests are being added.
+2. Existing tests are being reorganized or renamed.
+3. The request mentions conventions, readability, hierarchy, or discoverability.
+4. The task introduces parametrization where case naming affects failure readability.
 
 ## Baseline Best Practices
 
 These are stable defaults regardless of stack:
 
-1. Mirror `src/` into `tests/` so ownership and coverage are obvious.
-2. Keep fixtures explicit and layered (`tests/conftest.py` globally, subtree `conftest.py` for domain-specific fixtures).
-3. Register markers up front (`unit`, `integration`, `smoke`, `slow`, `external`) and keep strict marker checks enabled.
-4. Separate fast feedback (`-m unit`) from broader integration/external lanes.
-5. Validate structure early with collection checks before expanding assertions.
+1. Apply pytest naming and hierarchy conventions first so discovery and ownership stay predictable; see [naming-and-organization.md](./references/naming-and-organization.md).
+2. Mirror `src/` into `tests/` so ownership and coverage are obvious.
+3. Keep fixtures explicit and layered (`tests/conftest.py` globally, subtree `conftest.py` for domain-specific fixtures).
+4. Register markers up front (`unit`, `integration`, `smoke`, `slow`, `external`) and keep strict marker checks enabled.
+5. Separate fast feedback (`-m unit`) from broader integration/external lanes.
+6. Validate structure early with collection checks before expanding assertions.
 
 ## Stack-Specific Guidance
 
@@ -76,7 +102,9 @@ Use these commands to check structure and execution lanes:
 ## Output Contract
 When this skill is applied, return:
 1. Which references were consulted.
-2. Recommended structure, naming, fixture, and marker decisions.
-3. Exact validation commands.
-4. Relevant source-doc links for any non-trivial recommendation.
-5. Risks, assumptions, or open questions.
+2. The discovery path used (intent classification, load order, and why).
+3. Recommended structure, naming, fixture, and marker decisions.
+4. Concrete naming outcomes: file/module naming pattern, class usage decision, and any parametrization `ids` conventions.
+5. Exact validation commands.
+6. Relevant source-doc links for any non-trivial recommendation.
+7. Risks, assumptions, or open questions.