@robot-inventor/agent-skills 0.0.0 → 0.7.1

package/skills/identify-search-maintenance/references/selection-rubric.md

@@ -1,45 +1,45 @@
-# Rank-led candidate selection rubric
-
-## Normalize the export
-
-Create a CSV with this exact header before using the script:
-
-```csv
-url,current_clicks,previous_clicks,current_impressions,previous_impressions,current_position,previous_position
-```
-
-`current_*` is the recent period and `previous_*` is its comparison period. Preserve the original Search Console exports as evidence. Do not combine GA4 and Search Console counts in the same columns. The normalized page CSV is only a ranking-loss screen; it cannot establish search demand.
-
-For annual comparison, make a second normalized CSV where `previous_*` is the equivalent period one year earlier. Run the screen on both CSVs, union their candidates, and show which comparison surfaced each URL. If that page did not exist then or the data is unavailable, report `N/A`.
-
-## Default first-pass thresholds
-
-The bundled script selects a page only if all conditions hold:
-
-| Signal                                  |                       Default | Reason                                   |
-| --------------------------------------- | ----------------------------: | ---------------------------------------- |
-| Previous-period clicks                  |                  at least 100 | Avoid low-volume noise                   |
-| Click change                            |                 -20% or worse | Requires a material loss                 |
-| Impression change                       |                   within ±25% | Excludes most demand-led losses          |
-| Position change                         |                 +0.5 or worse | Requires a measurable rank deterioration |
-| Click decline beyond impression decline | at least 10 percentage points | Requires loss beyond demand movement     |
-
-These are screening defaults, not proof. A page can be excluded despite passing them when an independent demand proxy shows demand loss, a one-off event occurred, a competing URL gained the query, or the task is obsolete. A page can be included with explained threshold adjustments only when the report documents why.
-
-## Interpret the metrics
-
-- Position delta is `current_position - previous_position`; a positive number is worse.
-- Page-level impressions are not demand: a lower rank can itself lower the page's impressions. Property-wide query impressions can also fall when the whole site loses visibility. Use Google Trends, Keyword Planner, or another documented independent source to assess demand. Compare property-wide (unfiltered-by-page) query impressions only as a corroborating visibility signal, then compare the target URL's rank/clicks separately.
-- A stable page-level impression total can hide query-mix movement. Verify individual declined queries before calling the loss rank-led, and inspect pages that gained the query for cannibalization.
-- A stable position with a falling CTR is a CTR/SERP case, not a rank-led case.
-- A fall in impressions paired with a similar fall in clicks is normally demand-led or obsolescence-led until evidence proves otherwise.
-- Search Console average position is an aggregate. Use live Google searches only as a point-in-time confirmation and label locale, device, signed-in state, and date.
-
-## Completion checklist
-
-- [ ] Recent and year-over-year comparisons were both attempted.
-- [ ] Every final candidate has page-level metrics, at least three declined historic queries, and property-wide visibility checks for those queries.
-- [ ] Every final candidate has independent demand evidence, a URL Inspection/index/canonical/availability health check, and no confirmed cannibalization.
-- [ ] Google SERP checks list query, target visibility, competitors, and material SERP features.
-- [ ] The report explicitly separates rank-led candidates from demand-led, CTR-only, technical, and insufficient-evidence cases.
-- [ ] The report contains diagnoses and maintenance priorities, but no article edits.
+# Rank-led candidate selection rubric
+
+## Normalize the export
+
+Create a CSV with this exact header before using the script:
+
+```csv
+url,current_clicks,previous_clicks,current_impressions,previous_impressions,current_position,previous_position
+```
+
+`current_*` is the recent period and `previous_*` is its comparison period. Preserve the original Search Console exports as evidence. Do not combine GA4 and Search Console counts in the same columns. The normalized page CSV is only a ranking-loss screen; it cannot establish search demand.
+
+For annual comparison, make a second normalized CSV where `previous_*` is the equivalent period one year earlier. Run the screen on both CSVs, union their candidates, and show which comparison surfaced each URL. If that page did not exist then or the data is unavailable, report `N/A`.
+
+## Default first-pass thresholds
+
+The bundled script selects a page only if all conditions hold:
+
+| Signal                                  |                       Default | Reason                                   |
+| --------------------------------------- | ----------------------------: | ---------------------------------------- |
+| Previous-period clicks                  |                  at least 100 | Avoid low-volume noise                   |
+| Click change                            |                 -20% or worse | Requires a material loss                 |
+| Impression change                       |                   within ±25% | Excludes most demand-led losses          |
+| Position change                         |                 +0.5 or worse | Requires a measurable rank deterioration |
+| Click decline beyond impression decline | at least 10 percentage points | Requires loss beyond demand movement     |
+
+These are screening defaults, not proof. A page can be excluded despite passing them when an independent demand proxy shows demand loss, a one-off event occurred, a competing URL gained the query, or the task is obsolete. A page can be included with explained threshold adjustments only when the report documents why.
+
+## Interpret the metrics
+
+- Position delta is `current_position - previous_position`; a positive number is worse.
+- Page-level impressions are not demand: a lower rank can itself lower the page's impressions. Property-wide query impressions can also fall when the whole site loses visibility. Use Google Trends, Keyword Planner, or another documented independent source to assess demand. Compare property-wide (unfiltered-by-page) query impressions only as a corroborating visibility signal, then compare the target URL's rank/clicks separately.
+- A stable page-level impression total can hide query-mix movement. Verify individual declined queries before calling the loss rank-led, and inspect pages that gained the query for cannibalization.
+- A stable position with a falling CTR is a CTR/SERP case, not a rank-led case.
+- A fall in impressions paired with a similar fall in clicks is normally demand-led or obsolescence-led until evidence proves otherwise.
+- Search Console average position is an aggregate. Use live Google searches only as a point-in-time confirmation and label locale, device, signed-in state, and date.
+
+## Completion checklist
+
+- [ ] Recent and year-over-year comparisons were both attempted.
+- [ ] Every final candidate has page-level metrics, at least three declined historic queries, and property-wide visibility checks for those queries.
+- [ ] Every final candidate has independent demand evidence, a URL Inspection/index/canonical/availability health check, and no confirmed cannibalization.
+- [ ] Google SERP checks list query, target visibility, competitors, and material SERP features.
+- [ ] The report explicitly separates rank-led candidates from demand-led, CTR-only, technical, and insufficient-evidence cases.
+- [ ] The report contains diagnoses and maintenance priorities, but no article edits.

package/skills/identify-search-maintenance/scripts/select_rank_led_candidates.py

@@ -1,212 +1,212 @@
-#!/usr/bin/env python3
-"""Screen normalized Search Console page data for rank-led traffic-loss candidates."""
-
-from __future__ import annotations
-
-import argparse
-import csv
-import math
-import sys
-from pathlib import Path
-from typing import Iterable, TextIO
-
-REQUIRED_COLUMNS = (
-    "url",
-    "current_clicks",
-    "previous_clicks",
-    "current_impressions",
-    "previous_impressions",
-    "current_position",
-    "previous_position",
-)
-
-
-def parse_number(value: str, column: str, row_number: int) -> float:
-    try:
-        number = float(value.replace(",", "").strip())
-    except (AttributeError, ValueError) as error:
-        raise ValueError(
-            f"Row {row_number}: {column} must be numeric, got {value!r}."
-        ) from error
-    if not math.isfinite(number):
-        raise ValueError(f"Row {row_number}: {column} must be finite, got {value!r}.")
-    if (column.endswith("clicks") or column.endswith("impressions")) and number < 0:
-        raise ValueError(
-            f"Row {row_number}: {column} cannot be negative, got {value!r}."
-        )
-    if column.endswith("position") and number <= 0:
-        raise ValueError(
-            f"Row {row_number}: {column} must be greater than zero, got {value!r}."
-        )
-    return number
-
-
-def percentage_change(current: float, previous: float) -> float:
-    return (current - previous) / previous
-
-
-def read_rows(stream: TextIO) -> Iterable[dict[str, str]]:
-    reader = csv.DictReader(stream)
-    if reader.fieldnames is None:
-        raise ValueError("Input CSV has no header row.")
-
-    reader.fieldnames[0] = reader.fieldnames[0].lstrip("\ufeff")
-    missing = [column for column in REQUIRED_COLUMNS if column not in reader.fieldnames]
-    if missing:
-        raise ValueError(
-            f"Input CSV is missing required columns: {', '.join(missing)}."
-        )
-
-    return reader
-
-
-def select_candidates(
-    rows: Iterable[dict[str, str]],
-    min_previous_clicks: float,
-    max_click_change: float,
-    max_absolute_impression_change: float,
-    min_position_worsening: float,
-    min_click_gap_vs_impressions: float,
-) -> list[dict[str, float | str]]:
-    candidates: list[dict[str, float | str]] = []
-    seen_urls: set[str] = set()
-    for row_number, row in enumerate(rows, start=2):
-        url = row["url"].strip()
-        if not url:
-            raise ValueError(f"Row {row_number}: url cannot be empty.")
-        if url in seen_urls:
-            raise ValueError(
-                f"Row {row_number}: duplicate url {url!r}; aggregate the export first."
-            )
-        seen_urls.add(url)
-        values = {
-            column: parse_number(row[column], column, row_number)
-            for column in REQUIRED_COLUMNS[1:]
-        }
-        previous_clicks = values["previous_clicks"]
-        previous_impressions = values["previous_impressions"]
-        if previous_clicks <= 0 or previous_impressions <= 0:
-            continue
-
-        click_change = percentage_change(values["current_clicks"], previous_clicks)
-        impression_change = percentage_change(
-            values["current_impressions"], previous_impressions
-        )
-        position_worsening = values["current_position"] - values["previous_position"]
-        click_gap_vs_impressions = impression_change - click_change
-
-        if (
-            previous_clicks >= min_previous_clicks
-            and click_change <= max_click_change
-            and abs(impression_change) <= max_absolute_impression_change
-            and position_worsening >= min_position_worsening
-            and click_gap_vs_impressions >= min_click_gap_vs_impressions
-        ):
-            candidates.append(
-                {
-                    "url": url,
-                    "current_clicks": values["current_clicks"],
-                    "previous_clicks": previous_clicks,
-                    "click_change": click_change,
-                    "current_impressions": values["current_impressions"],
-                    "previous_impressions": previous_impressions,
-                    "impression_change": impression_change,
-                    "current_position": values["current_position"],
-                    "previous_position": values["previous_position"],
-                    "position_worsening": position_worsening,
-                    "click_gap_vs_impressions": click_gap_vs_impressions,
-                }
-            )
-
-    return sorted(
-        candidates,
-        key=lambda candidate: (
-            float(candidate["previous_clicks"]) - float(candidate["current_clicks"])
-        ),
-        reverse=True,
-    )
-
-
-def percentage(value: float) -> str:
-    return f"{value * 100:.1f}%"
-
-
-def markdown(candidates: Iterable[dict[str, float | str]]) -> str:
-    lines = [
-        "| URL | Clicks (current / previous) | Click change | Impressions change | Position worsening |",
-        "| --- | ---: | ---: | ---: | ---: |",
-    ]
-    for candidate in candidates:
-        lines.append(
-            "| {url} | {current_clicks:.0f} / {previous_clicks:.0f} | {click_change} | {impression_change} | {position_worsening:+.1f} |".format(
-                url=candidate["url"],
-                current_clicks=float(candidate["current_clicks"]),
-                previous_clicks=float(candidate["previous_clicks"]),
-                click_change=percentage(float(candidate["click_change"])),
-                impression_change=percentage(float(candidate["impression_change"])),
-                position_worsening=float(candidate["position_worsening"]),
-            )
-        )
-    return "\n".join(lines)
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
-        "input", help="Normalized CSV path, or - to read CSV from standard input."
-    )
-    parser.add_argument("--min-previous-clicks", type=float, default=100)
-    parser.add_argument("--max-click-change", type=float, default=-0.20)
-    parser.add_argument("--max-absolute-impression-change", type=float, default=0.25)
-    parser.add_argument("--min-position-worsening", type=float, default=0.5)
-    parser.add_argument("--min-click-gap-vs-impressions", type=float, default=0.10)
-    parser.add_argument("--format", choices=("markdown", "csv"), default="markdown")
-    arguments = parser.parse_args()
-
-    try:
-        if arguments.input == "-":
-            candidates = select_candidates(
-                read_rows(sys.stdin),
-                arguments.min_previous_clicks,
-                arguments.max_click_change,
-                arguments.max_absolute_impression_change,
-                arguments.min_position_worsening,
-                arguments.min_click_gap_vs_impressions,
-            )
-        else:
-            with Path(arguments.input).open(
-                encoding="utf-8-sig", newline=""
-            ) as input_file:
-                candidates = select_candidates(
-                    read_rows(input_file),
-                    arguments.min_previous_clicks,
-                    arguments.max_click_change,
-                    arguments.max_absolute_impression_change,
-                    arguments.min_position_worsening,
-                    arguments.min_click_gap_vs_impressions,
-                )
-    except (OSError, ValueError, csv.Error) as error:
-        parser.error(str(error))
-
-    if arguments.format == "markdown":
-        print(markdown(candidates))
-        return 0
-
-    writer = csv.DictWriter(
-        sys.stdout,
-        fieldnames=(
-            "url",
-            *REQUIRED_COLUMNS[1:],
-            "click_change",
-            "impression_change",
-            "position_worsening",
-            "click_gap_vs_impressions",
-        ),
-    )
-    writer.writeheader()
-    writer.writerows(candidates)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+#!/usr/bin/env python3
+"""Screen normalized Search Console page data for rank-led traffic-loss candidates."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import math
+import sys
+from pathlib import Path
+from typing import Iterable, TextIO
+
+REQUIRED_COLUMNS = (
+    "url",
+    "current_clicks",
+    "previous_clicks",
+    "current_impressions",
+    "previous_impressions",
+    "current_position",
+    "previous_position",
+)
+
+
+def parse_number(value: str, column: str, row_number: int) -> float:
+    try:
+        number = float(value.replace(",", "").strip())
+    except (AttributeError, ValueError) as error:
+        raise ValueError(
+            f"Row {row_number}: {column} must be numeric, got {value!r}."
+        ) from error
+    if not math.isfinite(number):
+        raise ValueError(f"Row {row_number}: {column} must be finite, got {value!r}.")
+    if (column.endswith("clicks") or column.endswith("impressions")) and number < 0:
+        raise ValueError(
+            f"Row {row_number}: {column} cannot be negative, got {value!r}."
+        )
+    if column.endswith("position") and number <= 0:
+        raise ValueError(
+            f"Row {row_number}: {column} must be greater than zero, got {value!r}."
+        )
+    return number
+
+
+def percentage_change(current: float, previous: float) -> float:
+    return (current - previous) / previous
+
+
+def read_rows(stream: TextIO) -> Iterable[dict[str, str]]:
+    reader = csv.DictReader(stream)
+    if reader.fieldnames is None:
+        raise ValueError("Input CSV has no header row.")
+
+    reader.fieldnames[0] = reader.fieldnames[0].lstrip("\ufeff")
+    missing = [column for column in REQUIRED_COLUMNS if column not in reader.fieldnames]
+    if missing:
+        raise ValueError(
+            f"Input CSV is missing required columns: {', '.join(missing)}."
+        )
+
+    return reader
+
+
+def select_candidates(
+    rows: Iterable[dict[str, str]],
+    min_previous_clicks: float,
+    max_click_change: float,
+    max_absolute_impression_change: float,
+    min_position_worsening: float,
+    min_click_gap_vs_impressions: float,
+) -> list[dict[str, float | str]]:
+    candidates: list[dict[str, float | str]] = []
+    seen_urls: set[str] = set()
+    for row_number, row in enumerate(rows, start=2):
+        url = row["url"].strip()
+        if not url:
+            raise ValueError(f"Row {row_number}: url cannot be empty.")
+        if url in seen_urls:
+            raise ValueError(
+                f"Row {row_number}: duplicate url {url!r}; aggregate the export first."
+            )
+        seen_urls.add(url)
+        values = {
+            column: parse_number(row[column], column, row_number)
+            for column in REQUIRED_COLUMNS[1:]
+        }
+        previous_clicks = values["previous_clicks"]
+        previous_impressions = values["previous_impressions"]
+        if previous_clicks <= 0 or previous_impressions <= 0:
+            continue
+
+        click_change = percentage_change(values["current_clicks"], previous_clicks)
+        impression_change = percentage_change(
+            values["current_impressions"], previous_impressions
+        )
+        position_worsening = values["current_position"] - values["previous_position"]
+        click_gap_vs_impressions = impression_change - click_change
+
+        if (
+            previous_clicks >= min_previous_clicks
+            and click_change <= max_click_change
+            and abs(impression_change) <= max_absolute_impression_change
+            and position_worsening >= min_position_worsening
+            and click_gap_vs_impressions >= min_click_gap_vs_impressions
+        ):
+            candidates.append(
+                {
+                    "url": url,
+                    "current_clicks": values["current_clicks"],
+                    "previous_clicks": previous_clicks,
+                    "click_change": click_change,
+                    "current_impressions": values["current_impressions"],
+                    "previous_impressions": previous_impressions,
+                    "impression_change": impression_change,
+                    "current_position": values["current_position"],
+                    "previous_position": values["previous_position"],
+                    "position_worsening": position_worsening,
+                    "click_gap_vs_impressions": click_gap_vs_impressions,
+                }
+            )
+
+    return sorted(
+        candidates,
+        key=lambda candidate: (
+            float(candidate["previous_clicks"]) - float(candidate["current_clicks"])
+        ),
+        reverse=True,
+    )
+
+
+def percentage(value: float) -> str:
+    return f"{value * 100:.1f}%"
+
+
+def markdown(candidates: Iterable[dict[str, float | str]]) -> str:
+    lines = [
+        "| URL | Clicks (current / previous) | Click change | Impressions change | Position worsening |",
+        "| --- | ---: | ---: | ---: | ---: |",
+    ]
+    for candidate in candidates:
+        lines.append(
+            "| {url} | {current_clicks:.0f} / {previous_clicks:.0f} | {click_change} | {impression_change} | {position_worsening:+.1f} |".format(
+                url=candidate["url"],
+                current_clicks=float(candidate["current_clicks"]),
+                previous_clicks=float(candidate["previous_clicks"]),
+                click_change=percentage(float(candidate["click_change"])),
+                impression_change=percentage(float(candidate["impression_change"])),
+                position_worsening=float(candidate["position_worsening"]),
+            )
+        )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "input", help="Normalized CSV path, or - to read CSV from standard input."
+    )
+    parser.add_argument("--min-previous-clicks", type=float, default=100)
+    parser.add_argument("--max-click-change", type=float, default=-0.20)
+    parser.add_argument("--max-absolute-impression-change", type=float, default=0.25)
+    parser.add_argument("--min-position-worsening", type=float, default=0.5)
+    parser.add_argument("--min-click-gap-vs-impressions", type=float, default=0.10)
+    parser.add_argument("--format", choices=("markdown", "csv"), default="markdown")
+    arguments = parser.parse_args()
+
+    try:
+        if arguments.input == "-":
+            candidates = select_candidates(
+                read_rows(sys.stdin),
+                arguments.min_previous_clicks,
+                arguments.max_click_change,
+                arguments.max_absolute_impression_change,
+                arguments.min_position_worsening,
+                arguments.min_click_gap_vs_impressions,
+            )
+        else:
+            with Path(arguments.input).open(
+                encoding="utf-8-sig", newline=""
+            ) as input_file:
+                candidates = select_candidates(
+                    read_rows(input_file),
+                    arguments.min_previous_clicks,
+                    arguments.max_click_change,
+                    arguments.max_absolute_impression_change,
+                    arguments.min_position_worsening,
+                    arguments.min_click_gap_vs_impressions,
+                )
+    except (OSError, ValueError, csv.Error) as error:
+        parser.error(str(error))
+
+    if arguments.format == "markdown":
+        print(markdown(candidates))
+        return 0
+
+    writer = csv.DictWriter(
+        sys.stdout,
+        fieldnames=(
+            "url",
+            *REQUIRED_COLUMNS[1:],
+            "click_change",
+            "impression_change",
+            "position_worsening",
+            "click_gap_vs_impressions",
+        ),
+    )
+    writer.writeheader()
+    writer.writerows(candidates)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/prove-it-diagnostics/SKILL.md

@@ -1,60 +1,60 @@
----
-name: prove-it-diagnostics
-description: Prove it for debugging, performance investigation, bottleneck analysis, profiling, and optimization work. When reading code does not prove the cause, run a minimal reproduction, add temporary traces, measure bottlenecks, and verify the fix or improvement.
-license: MIT
-metadata:
-  author: Robot-Inventor
----
-
-# Prove It Diagnostics
-
-Use this skill to pinpoint the causes of bugs and performance bottlenecks and fix them. Reading code alone may not reveal the source of a bug or bottleneck. Do not claim that a speculative code change fixed a bug or improved performance. Run the code, gather evidence, identify the cause, and verify the fix.
-
-## Steps
-
-The following is the core of this skill; please follow the specified steps.
-
-## 1. Establish a performance baseline for optimization tasks
-
-For performance optimization tasks, create and run a benchmark before making changes. Run the benchmark as many times as practical. Use averages, percentiles, and other relevant statistics to establish a stable baseline instead of relying on a single run.
-
-## 2. Read the code
-
-Read the code related to the bug or performance issue. For debugging tasks, you may fix the issue and skip the remaining steps when you find a clear cause, such as an incorrect operator or an obvious contradiction in the logic.
-
-Continue with the remaining steps when you cannot identify the cause with confidence or when you find suspicious code but lack enough evidence to blame it.
-
-### 3. Verify the cause
-
-Do not rely on code inspection alone. Run experiments to identify the source of the bug or bottleneck.
-
-For debugging tasks:
-
-1. Create a reproduction in a temporary file or REPL and run it to confirm the bug. If the reproduction does not fail, add relevant behavior from the target code until it reproduces the bug.
-2. Remove or revert each part of the reproduction to find the smallest program that still triggers the bug. A minimal reproduction narrows the list of possible causes.
-3. Investigate the minimal reproduction, identify the cause, and fix it. Address the root cause instead of applying a superficial workaround, as described in the Rules section.
-4. Confirm that the fix prevents the bug in the minimal reproduction.
-5. Apply the fix to the production code and confirm that it resolves the original bug. If the bug remains, return to the reproduction step and repeat the process.
-
-For performance optimization tasks:
-
-1. Use benchmarks, profilers, timing logs, or similar tools to identify the slow operation.
-2. Fix the bottleneck, then use the same measurements to confirm that performance improved.
-3. Apply the fix to the production code and confirm the improvement there. If performance does not improve, return to bottleneck analysis and repeat the process.
-
-### 4. Clean up
-
-Remove temporary logs, reproduction code, generated files, and log data created during verification.
-
-## Rules
-
-If a user reports that your fix did not resolve the bug or improve performance, treat your previous diagnosis as unverified and restart the investigation.
-
-Surface-level and stop-gap fixes are shameful; identify and fix the root cause. For example, when an error triggers a bug, find and fix the source of the error instead of adding a fallback for the failure. Keep asking yourself, “Is this the root cause?”
-
-When evidence points to a bug in a dependency, do not patch the dependency. Tell the user that the dependency appears to contain a bug, describe the evidence, and propose changes they can make in their project without modifying the dependency.
-
-When you get stuck, try these approaches:
-
-- Add temporary logs across the affected path. Use them to find the boundary between correct and incorrect behavior, or between fast and slow execution.
-- When behavior contradicts the code’s logic or you cannot make progress, search the relevant library’s GitHub issues and pull requests, Stack Overflow, and community articles for reports of the same problem and possible solutions.
+---
+name: prove-it-diagnostics
+description: Prove it for debugging, performance investigation, bottleneck analysis, profiling, and optimization work. When reading code does not prove the cause, run a minimal reproduction, add temporary traces, measure bottlenecks, and verify the fix or improvement.
+license: MIT
+metadata:
+  author: Robot-Inventor
+---
+
+# Prove It Diagnostics
+
+Use this skill to pinpoint the causes of bugs and performance bottlenecks and fix them. Reading code alone may not reveal the source of a bug or bottleneck. Do not claim that a speculative code change fixed a bug or improved performance. Run the code, gather evidence, identify the cause, and verify the fix.
+
+## Steps
+
+The following is the core of this skill; please follow the specified steps.
+
+## 1. Establish a performance baseline for optimization tasks
+
+For performance optimization tasks, create and run a benchmark before making changes. Run the benchmark as many times as practical. Use averages, percentiles, and other relevant statistics to establish a stable baseline instead of relying on a single run.
+
+## 2. Read the code
+
+Read the code related to the bug or performance issue. For debugging tasks, you may fix the issue and skip the remaining steps when you find a clear cause, such as an incorrect operator or an obvious contradiction in the logic.
+
+Continue with the remaining steps when you cannot identify the cause with confidence or when you find suspicious code but lack enough evidence to blame it.
+
+### 3. Verify the cause
+
+Do not rely on code inspection alone. Run experiments to identify the source of the bug or bottleneck.
+
+For debugging tasks:
+
+1. Create a reproduction in a temporary file or REPL and run it to confirm the bug. If the reproduction does not fail, add relevant behavior from the target code until it reproduces the bug.
+2. Remove or revert each part of the reproduction to find the smallest program that still triggers the bug. A minimal reproduction narrows the list of possible causes.
+3. Investigate the minimal reproduction, identify the cause, and fix it. Address the root cause instead of applying a superficial workaround, as described in the Rules section.
+4. Confirm that the fix prevents the bug in the minimal reproduction.
+5. Apply the fix to the production code and confirm that it resolves the original bug. If the bug remains, return to the reproduction step and repeat the process.
+
+For performance optimization tasks:
+
+1. Use benchmarks, profilers, timing logs, or similar tools to identify the slow operation.
+2. Fix the bottleneck, then use the same measurements to confirm that performance improved.
+3. Apply the fix to the production code and confirm the improvement there. If performance does not improve, return to bottleneck analysis and repeat the process.
+
+### 4. Clean up
+
+Remove temporary logs, reproduction code, generated files, and log data created during verification.
+
+## Rules
+
+If a user reports that your fix did not resolve the bug or improve performance, treat your previous diagnosis as unverified and restart the investigation.
+
+Surface-level and stop-gap fixes are shameful; identify and fix the root cause. For example, when an error triggers a bug, find and fix the source of the error instead of adding a fallback for the failure. Keep asking yourself, “Is this the root cause?”
+
+When evidence points to a bug in a dependency, do not patch the dependency. Tell the user that the dependency appears to contain a bug, describe the evidence, and propose changes they can make in their project without modifying the dependency.
+
+When you get stuck, try these approaches:
+
+- Add temporary logs across the affected path. Use them to find the boundary between correct and incorrect behavior, or between fast and slow execution.
+- When behavior contradicts the code’s logic or you cannot make progress, search the relevant library’s GitHub issues and pull requests, Stack Overflow, and community articles for reports of the same problem and possible solutions.