From e053fd0eb7b2845adf2931506e5c69fa188f3ac7 Mon Sep 17 00:00:00 2001
From: GuppyTheCat <46162723+GuppyTheCat@users.noreply.github.com>
Date: Sun, 25 Jan 2026 17:31:51 +0300
Subject: [PATCH] fix: Tighten css selector verification rules

---
 .../SKILL.md                                  | 54 +++++++++++--------
 .../references/analysis-workflow.md           | 34 ++++++++----
 2 files changed, 55 insertions(+), 33 deletions(-)

diff --git a/skills/obsidian-clipper-template-creator/SKILL.md b/skills/obsidian-clipper-template-creator/SKILL.md
index e96b6866..95851f52 100644
--- a/skills/obsidian-clipper-template-creator/SKILL.md
+++ b/skills/obsidian-clipper-template-creator/SKILL.md
@@ -9,20 +9,29 @@ This skill helps you create importable JSON templates for the Obsidian Web Clipp
 
 ## Workflow
 
-1.  **Identify User Intent:** specific site (YouTube), specific type (Recipe), or general clipping?
-2.  **Check Existing Bases:** The user likely has a "Base" schema defined in `Templates/Bases/`.
-    *   **Action:** Read `Templates/Bases/*.base` to find a matching category (e.g., `Recipes.base`).
-    *   **Action:** Use the properties defined in the Base to structure the Clipper template properties.
-    *   See [references/bases-workflow.md](references/bases-workflow.md) for details.
-3.  **Fetch & Analyze Reference URL:** Validate variables against a real page.
-    *   **Action:** Ask the user for a sample URL of the content they want to clip (if not provided).
-    *   **Action:** Use `WebFetch` to retrieve the page HTML.
-    *   **Action:** Analyze the HTML for Schema.org JSON, Meta tags, and CSS selectors.
-    *   See [references/analysis-workflow.md](references/analysis-workflow.md) for analysis techniques.
-4.  **Draft the JSON:** Create a valid JSON object following the schema.
-    *   See [references/json-schema.md](references/json-schema.md).
-5.  **Verify Variables:** Ensure the chosen variables (Preset, Schema, Selector) exist in your analysis.
-    *   See [references/variables.md](references/variables.md).
+1. **Identify User Intent:** specific site (YouTube), specific type (Recipe), or general clipping?
+2. **Check Existing Bases:** The user likely has a "Base" schema defined in `Templates/Bases/`.
+    - **Action:** Read `Templates/Bases/*.base` to find a matching category (e.g., `Recipes.base`).
+    - **Action:** Use the properties defined in the Base to structure the Clipper template properties.
+    - See [references/bases-workflow.md](references/bases-workflow.md) for details.
+3. **Fetch & Analyze Reference URL:** Validate variables against a real page.
+    - **Action:** Ask the user for a sample URL of the content they want to clip (if not provided).
+    - **Action (REQUIRED):** Use `WebFetch` or a browser DOM snapshot to retrieve page content before choosing any selector.
+    - **Action:** Analyze the HTML for Schema.org JSON, Meta tags, and CSS selectors.
+    - **Action (REQUIRED):** Verify each selector against the fetched content. Do not guess selectors.
+    - See [references/analysis-workflow.md](references/analysis-workflow.md) for analysis techniques.
+4. **Draft the JSON:** Create a valid JSON object following the schema.
+    - See [references/json-schema.md](references/json-schema.md).
+5. **Verify Variables:** Ensure the chosen variables (Preset, Schema, Selector) exist in your analysis.
+    - **Action (REQUIRED):** If a selector cannot be verified from the fetched content, state that explicitly and ask for another URL.
+    - See [references/variables.md](references/variables.md).
+
+## Selector Verification Rules
+
+- **Always verify selectors** against live page content before responding.
+- **Never guess selectors.** If the DOM cannot be accessed or the element is missing, ask for another URL or a screenshot.
+- **Prefer stable selectors** (data attributes, semantic roles, unique IDs) over fragile class chains.
+- **Document the target element** in your reasoning (e.g., "About sidebar paragraph") to reduce mismatch.
 
 ## Output Format
 
@@ -38,16 +47,17 @@ This skill helps you create importable JSON templates for the Obsidian Web Clipp
 
 ## Resources
 
-*   [references/variables.md](references/variables.md) - Available data variables.
-*   [references/filters.md](references/filters.md) - Formatting filters.
-*   [references/json-schema.md](references/json-schema.md) - JSON structure documentation.
-*   [references/bases-workflow.md](references/bases-workflow.md) - How to map Bases to Templates.
-*   [references/analysis-workflow.md](references/analysis-workflow.md) - How to validate page data.
+- [references/variables.md](references/variables.md) - Available data variables.
+- [references/filters.md](references/filters.md) - Formatting filters.
+- [references/json-schema.md](references/json-schema.md) - JSON structure documentation.
+- [references/bases-workflow.md](references/bases-workflow.md) - How to map Bases to Templates.
+- [references/analysis-workflow.md](references/analysis-workflow.md) - How to validate page data.
 
 ### Official Documentation
-*   [Variables](https://help.obsidian.md/web-clipper/variables)
-*   [Filters](https://help.obsidian.md/web-clipper/filters)
-*   [Templates](https://help.obsidian.md/web-clipper/templates)
+
+- [Variables](https://help.obsidian.md/web-clipper/variables)
+- [Filters](https://help.obsidian.md/web-clipper/filters)
+- [Templates](https://help.obsidian.md/web-clipper/templates)
 
 ## Examples
 
diff --git a/skills/obsidian-clipper-template-creator/references/analysis-workflow.md b/skills/obsidian-clipper-template-creator/references/analysis-workflow.md
index 175f5a12..e426cb14 100644
--- a/skills/obsidian-clipper-template-creator/references/analysis-workflow.md
+++ b/skills/obsidian-clipper-template-creator/references/analysis-workflow.md
@@ -3,18 +3,21 @@
 To ensure your template works correctly, you must validate that the target page actually contains the data you want to extract.
 
 ## 1. Fetch the Page
-Use the `WebFetch` tool to retrieve the content of a representative URL provided by the user.
 
-```
+Use the `WebFetch` tool or a browser DOM snapshot to retrieve the content of a representative URL provided by the user.
+
+```text
 WebFetch(url="https://example.com/recipe/chocolate-cake")
 ```
 
 ## 2. Analyze the Output
 
 ### Check for Schema.org (Recommended)
+
 Look for `<script type="application/ld+json">`. This contains structured data which is the most reliable way to extract info.
 
 **Example Found in HTML:**
+
 ```html
 <script type="application/ld+json">
 {
@@ -29,27 +32,34 @@ Look for `<script type="application/ld+json">`. This contains structured data wh
 ```
 
 **Conclusion:**
-*   `{{schema:Recipe:name}}` is valid.
-*   `{{schema:Recipe:author.name}}` is valid.
-*   **Tip:** You can use `schema:Recipe` in the `triggers` array to automatically select this template for any page with this schema.
+
+- `{{schema:Recipe:name}}` is valid.
+- `{{schema:Recipe:author.name}}` is valid.
+- **Tip:** You can use `schema:Recipe` in the `triggers` array to automatically select this template for any page with this schema.
 
 ### Check for Meta Tags
+
 Look for `<meta>` tags in the `<head>` section.
 
 **Example Found in HTML:**
+
 ```html
 <meta property="og:title" content="The Best Chocolate Cake" />
 <meta name="description" content="A rich, moist chocolate cake recipe." />
 ```
 
 **Conclusion:**
-*   `{{meta:og:title}}` is valid.
-*   `{{meta:description}}` is valid.
 
-### Check for CSS Selectors (Fallback)
+- `{{meta:og:title}}` is valid.
+- `{{meta:description}}` is valid.
+
+### Check for CSS Selectors (Verified)
+
 If Schema and Meta tags are missing, look for HTML structure (classes and IDs) to use with `{{selector:...}}`.
+Selectors must be verified against the fetched HTML or DOM snapshot. Do not guess selectors.
 
 **Example Found in HTML:**
+
 ```html
 <div class="article-body">
   <h1 id="main-title">Chocolate Cake</h1>
@@ -58,10 +68,12 @@ If Schema and Meta tags are missing, look for HTML structure (classes and IDs) t
 ```
 
 **Conclusion:**
-*   `{{selector:h1#main-title}}` or `{{selector:h1}}` can extract the title.
-*   `{{selector:.author-name}}` can extract the author.
+
+- `{{selector:h1#main-title}}` or `{{selector:h1}}` can extract the title.
+- `{{selector:.author-name}}` can extract the author.
 
 ## 3. Verify Against Base
+
 Compare the available data from your analysis with the properties required by the user's Base (see `references/bases-workflow.md`).
 
-*   If the Base requires `ingredients` but the page has no Schema or clear list structure, warn the user that this field might need manual entry or a prompt variable.
+- If the Base requires `ingredients` but the page has no Schema or clear list structure, warn the user that this field might need manual entry or a prompt variable.