started prompt mechanics

docs/skills/new-skill/SKILL.md

@@ -27,6 +27,20 @@ Use this skill to bootstrap a new skill in the docs-first architecture. Try to u
 2. One-sentence capability statement (what it does and when to use it)
 3. Optional list of references to include under `references/`
 
+## Progressive Discovery Requirement
+
+Every new skill created from this template should be optimized for progressive discovery, so agents load only the most relevant references in the right order.
+
+Required sections for new skills:
+
+1. `When to Use` with concrete trigger conditions.
+2. `How To Use This Skill` with a short intent-first flow.
+3. `Intent Router` mapping common task intents to specific reference files.
+4. `Load Order` and `Load Budget` defaults (for example, start with one baseline reference, then one stack-specific reference).
+5. `Output Contract` requiring the references consulted and the discovery path used.
+
+If the domain includes naming or hierarchy conventions, include a dedicated naming trigger section that is consulted before structure recommendations.
+
 ## Source of Truth and Required References
 
 1. Use this file as the baseline template for new skill authoring.
@@ -47,6 +61,7 @@ docs/
     <skill-id>/
       SKILL.md
       references/
+        index.md (recommended reference router)
         ... (optional markdown files, nested folders allowed)
 ```
 
@@ -56,6 +71,7 @@ Rules:
 2. All skill-specific supporting docs live under `references/`.
 3. Skill directories are ownership boundaries; no cross-skill writes.
 4. `skill-id` is lowercase kebab-case and should remain stable.
+5. Include a progressive discovery section in `SKILL.md` that makes selective reference loading explicit.
 
 ### Framing
 
@@ -148,6 +164,9 @@ Compatibility rule:
 5. Include resource://skills/<skill-id>/document in capabilities.
 6. For each top-level `references/<name>.md`, expect `resource://skills/<skill-id>/references/<name>` (normalized to lowercase kebab-case).
 7. Add explicit `x-personal-mcp.references` entries only for nested paths or metadata overrides.
+8. Add `When to Use`, `How To Use This Skill`, `Intent Router`, `Load Order`, and `Load Budget` sections in the skill body.
+9. Ensure the `Output Contract` requires reporting consulted references and the decision path.
+10. If naming conventions are part of the domain, include a naming trigger section and place naming guidance early in the flow.
 
 ## Required Outcomes
 
@@ -156,6 +175,7 @@ Compatibility rule:
 3. Ensure frontmatter follows repository contract, including `x-personal-mcp` fields and canonical capabilities.
 4. Keep URI and reference mapping consistent with repository conventions.
 5. Reconcile all updates with repository implementation and avoid introducing parallel metadata systems.
+6. Ensure the skill body is structured for progressive discovery and selective reference loading.
 
 ## Validation
 

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.