opencode-skills-collection 4.0.0 → 4.0.1

package/bundled-skills/test-guard/references/jest.md

@@ -0,0 +1,50 @@
+# Test Guard — JavaScript / TypeScript / Jest / Vitest Patterns
+
+Concrete applications of the nine rules for JS/TS projects. Read this when reviewing or writing Jest or Vitest tests.
+
+## Rule 2: Mock boundaries in JS/TS
+
+Justified mock targets:
+
+- Network: prefer `msw` (Mock Service Worker) over `jest.mock`-ing your own fetch wrapper — it mocks at the true boundary
+- LLM / third-party SDK clients (`openai`, `@anthropic-ai/sdk`, Stripe, etc.)
+- Timers and randomness: `vi.useFakeTimers()` / `jest.useFakeTimers()`, seeded RNG
+- Filesystem and process env in Node code
+
+Unjustified mocks:
+
+- `jest.mock('../utils/helpers')` — mocking your own internal module to isolate a "unit" (Rule 2)
+- Mocking a class's private method via prototype patching (Rule 1)
+- Hand-built object literals pretending to be domain entities when a real constructor or factory exists (Rule 8)
+
+## Rule 3: test.each
+
+```ts
+// Violation: three near-identical it() blocks
+// Fix:
+test.each([
+  ['Hello World', 'hello-world'],
+  ['  padded  ', 'padded'],
+  ['Café Menu', 'cafe-menu'],
+])('slugify(%s) → %s', (raw, expected) => {
+  expect(slugify(raw)).toBe(expected);
+});
+```
+
+## Snapshot discipline
+
+Snapshot tests are implementation tests in disguise unless the snapshot *is* the contract (e.g., a public JSON output, a CLI's help text). Avoid snapshots of:
+
+- Full component trees that change on every styling tweak (Rule 1 — brittle, asserts implementation)
+- Large objects nobody reviews — an unread snapshot approves itself (Rule 4)
+
+Prefer targeted assertions: `expect(screen.getByRole('button')).toHaveTextContent('Save')`.
+
+## UI component tests
+
+- Test what the user sees and does (Testing Library queries by role/label), not component internals or state hooks (Rule 1).
+- Don't test that React renders, routes resolve, or props propagate — framework guarantees (Rule 7).
+
+## Rule 9: Real persistence
+
+For data-layer logic (Prisma/Drizzle/Knex queries), run against a real test database — `testcontainers`, a Dockerized Postgres, or SQLite where compatible. Mocking the query builder to test the query builder tests nothing.

package/bundled-skills/test-guard/references/llm-app-testing.md

@@ -0,0 +1,40 @@
+# Test Guard — LLM Application Rules
+
+Three additional rules for projects that call LLM APIs, use agent/workflow frameworks (LangGraph, CrewAI, custom state machines), or wire up observability/telemetry (Langfuse, LangSmith, OpenTelemetry). Apply these on top of the nine core rules.
+
+## Rule 10: Prompt tests — test the contract, not the content
+
+Prompt text changes constantly; tests pinned to wording rot within a week. Don't assert specific phrasing.
+
+Do test:
+
+- The prompt template exists and loads without error (smoke test)
+- Template variables are substituted correctly — no leftover `{placeholder}` markers
+- The prompt contains required structural markers *if the caller parses them* (e.g., a JSON schema block, a delimiter the parser splits on)
+
+## Rule 11: Observability is infrastructure
+
+Don't unit-test telemetry wiring. The violation pattern is asserting a tracing/analytics mock's call arguments:
+
+```python
+# Violation — tests wiring, not behavior
+mock_tracer.assert_called_once_with(session_id=..., tags=[...])
+```
+
+Mocking observability calls to *prevent side effects* during tests is fine and often necessary. Just don't assert on the mock's call args. If telemetry breaks, dashboards show it; a unit test asserting wiring only breaks refactors.
+
+## Rule 12: Agent and flow tests test transitions
+
+For agent frameworks and state machines: test that given a state plus an event, the flow reaches the correct next state with the correct fields set. Mock the LLM calls to return controlled responses.
+
+Test: state in → state out.
+
+Don't test: the exact prompt string passed to the LLM, the number of LLM calls made, or internal retry logic — those are implementation details (Rule 1) that change with every model upgrade.
+
+A useful pattern is a table of transition cases (data-driven, Rule 3): starting state, mocked LLM response, expected resulting state.
+
+## Severity
+
+- **Must fix:** Rule 12 violations that assert prompt strings or call counts — they break on every model/prompt change
+- **Should fix:** Rule 10 wording assertions
+- **Worth noting:** Rule 11 — flag it, but don't block a small change on it

package/bundled-skills/test-guard/references/phpunit.md

@@ -0,0 +1,56 @@
+# Test Guard — PHP / PHPUnit / Pest Patterns
+
+Concrete applications of the nine rules for PHP projects, including WordPress and WooCommerce. Read this when reviewing or writing PHP tests.
+
+## Rule 2: Mock boundaries in PHP
+
+Justified mock targets:
+
+- HTTP: Guzzle handlers/middleware, `pre_http_request` filter in WordPress
+- External SDKs: payment gateways, mail providers, LLM API clients
+- Clock: inject a clock (`psr/clock`) instead of calling `time()` directly
+- Filesystem on external paths (prefer `vfsStream` or temp dirs over mocking)
+
+Unjustified mocks:
+
+- Mockery/Prophecy doubles for the project's own value objects, DTOs, or entities — construct real instances (Rule 8)
+- Mocking internal services just to isolate a class — if wiring is painful, fix the constructor, don't fake the collaborator
+- Partial mocks of the class under test — you are no longer testing the class
+
+## Rule 3: Data providers
+
+```php
+/**
+ * @see Rule 3 — variants of one scenario belong in a data provider.
+ */
+#[DataProvider('provideSlugCases')]
+public function test_slugify_normalizes_input( string $raw, string $expected ): void {
+    $this->assertSame( $expected, slugify( $raw ) );
+}
+
+public static function provideSlugCases(): array {
+    return array(
+        'lowercases'     => array( 'Hello World', 'hello-world' ),
+        'strips padding' => array( '  padded  ', 'padded' ),
+        'transliterates' => array( 'Café Menu', 'cafe-menu' ),
+    );
+}
+```
+
+Pest equivalent: `it('normalizes slug', ...)->with([...])`.
+
+## WordPress-specific boundaries
+
+- **Integration tests** (`WP_UnitTestCase` / `wp-env` / `wp-cli scaffold`): use the real WordPress test framework with factories — `self::factory()->post->create()`, `self::factory()->user->create()`. Don't mock `WP_Post` or `WP_User`; the factories exist precisely so you don't have to (Rule 8).
+- **Unit tests without WordPress loaded** (Brain Monkey / WP_Mock): mocking WordPress functions like `get_option()` or `apply_filters()` is a boundary mock and justified. But assert what *your code does* with the values, not that `get_option` was called with specific args (Rule 1).
+- Mock outbound HTTP with the `pre_http_request` filter rather than patching `wp_remote_get` internals.
+- Don't test that WordPress sanitizes, escapes, or that hooks fire — that's core's guarantee (Rule 7). Test your callback's behavior given an input.
+
+## WooCommerce notes
+
+- Build real `WC_Product` / `WC_Order` objects via `WC_Helper_Product` and `WC_Helper_Order` in integration tests — never `MagicMock`-style doubles of them (Rule 8).
+- Cart and checkout logic is stateful: prefer integration tests over heavily mocked unit tests; mocked carts hide hook-ordering bugs.
+
+## Rule 9: Real database
+
+`WP_UnitTestCase` already wraps each test in a transaction against a real schema — use it for query, meta, and persistence logic instead of mocking `$wpdb`. Mocking `$wpdb->prepare` or `$wpdb->get_results` to test a query builder tests nothing.

package/bundled-skills/test-guard/references/pytest.md

@@ -0,0 +1,65 @@
+# Test Guard — Python / pytest Patterns
+
+Concrete applications of the nine rules for pytest projects. Read this when reviewing or writing Python tests.
+
+## Rule 2: Mock boundaries in Python
+
+Justified mock targets:
+
+- HTTP clients: `httpx`, `requests`, `aiohttp` (or use `respx` / `responses` instead of raw mocks)
+- LLM SDK calls: `openai`, `anthropic`, `litellm.completion` and friends
+- Database sessions, when the database is not the subject (see Rule 9)
+- Filesystem I/O on external paths (`tmp_path` fixture is often better than mocking)
+- Clock and randomness: `time.time`, `datetime.now`, `random` (prefer `freezegun` or injected clocks)
+
+Unjustified mocks (common agent-generated violations):
+
+- `MagicMock()` standing in for a Pydantic model or dataclass — construct the real thing
+- Mocking internal utility functions to isolate a "unit"
+- Mocking `json.loads` / `json.dumps` or other stdlib pure functions
+
+## Rule 3: Parametrize
+
+```python
+# Violation: three copy-pasted tests differing by one value
+def test_slug_lowercase(): ...
+def test_slug_strips_spaces(): ...
+def test_slug_handles_unicode(): ...
+
+# Fix
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        ("Hello World", "hello-world"),
+        ("  padded  ", "padded"),
+        ("Café Menu", "cafe-menu"),
+    ],
+)
+def test_slugify_normalizes_input(raw, expected):
+    assert slugify(raw) == expected
+```
+
+## Rule 8: Real Pydantic/dataclass instances
+
+```python
+# Wrong — hides field typos and validation errors
+state = MagicMock()
+state.user_id = "123"
+state.status = "ACTIVE"
+
+# Right — Pydantic validates the construction itself
+state = UserState(user_id="123", status="ACTIVE")
+```
+
+If a model needs many fields, add a factory fixture or use `factory_boy` — don't fall back to `MagicMock`.
+
+## Rule 9: Real database via fixtures
+
+Use a fixture that applies real migrations (e.g., a session-scoped test database with `alembic upgrade head`), and function-scoped transactions rolled back per test. `pytest-postgresql`, `testcontainers`, or an SQLite-compatible fallback all work; the point is real schema, not a mocked session, whenever query or persistence logic is the subject.
+
+## pytest-specific smells
+
+- `assert mock.call_count == N` on anything internal — Rule 1 violation
+- `@patch` stacks three or more deep — the test is coupled to implementation; restructure
+- Asserting log output via `caplog` for messages no caller parses — Rule 4 violation
+- Fixtures that build mocks of project classes — Rule 8 violation, make the fixture build real objects

package/bundled-skills/trading-ledger/SKILL.md

@@ -28,9 +28,15 @@ A journaling skill in the tradition of the *Market Wizards* interviews: a writte
 
 ## How It Works
 
-### Step 1: Find the database (zero-config)
+### Step 1: Confirm the database (first use per session)
 
-On the first write of a session, use Notion `search` to find the **database** (type `database`, not a page) whose title contains **"trading-ledger"**. Read its `data_source_id` (`collection://...` UUID) and use it as the parent for `create-pages` / `query` for the session. More than one match → ask which.
+Use Notion `search` to find candidate **databases** (type `database`, not pages) whose title
+contains **"trading-ledger"**. Before any `query` or `create-pages` call, show the user the
+candidate title and `data_source_id` (`collection://...` UUID) and ask them to confirm the exact
+database for this session. A single title match is not sufficient confirmation. If the connector
+returns owner or schema metadata, show it as an additional identity check. Use only the
+user-confirmed ID for the remainder of the session; do not re-run fuzzy selection after a
+confirmation.
 
 The companion Notion template (free, linked in the source repo) ships this schema — select values are a controlled enum, copy them exactly:
 
@@ -101,7 +107,9 @@ Agent: 3 closed since last review:
 
 ## Security & Safety Notes
 
-- **Mutation scope**: writes and updates rows only in the single user-granted Notion database via the official Notion connector (MCP) — no shell commands, no network fetches, no market-data lookups, no credentials.
+- **Mutation scope**: writes and updates rows only in the exact Notion database ID confirmed by
+  the user for the current session via the official Notion connector (MCP) — no shell commands,
+  no network fetches, no market-data lookups, no credentials.
 - **This skill must never produce trading signals, price data, or buy/sell recommendations.** It records and mirrors the user's own decisions; the review asks questions, it does not advise. Nothing it writes is financial advice, and it should say so if asked for a recommendation.
 - On claude.ai, Notion's write tools default to *needs approval* — the first write pops an approval prompt; expected, not a hang.
 

package/bundled-skills/uizze-ui-research/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: uizze-ui-research
+description: "Use when building or reviewing web and iOS product UI and you need real UI references, structured design contracts, or implementation validation through UIZZE MCP."
+category: design
+risk: safe
+source: https://github.com/aislon/uizze-mcp/tree/main/skills/uizze-ui-research
+source_repo: aislon/uizze-mcp
+source_type: official
+date_added: "2026-07-12"
+author: samuelbushi
+tags: [ui-design, ui-research, mcp, design-contracts, agent-workflows]
+tools: [claude, cursor, codex, copilot, antigravity, lovable]
+---
+
+# UIZZE UI Research
+
+## Overview
+
+Use UIZZE to give coding agents real product-UI context before implementation rather than relying on a generic styling prompt. The public catalog is free to browse; the hosted MCP workflow requires full access and a configured UIZZE agent token.
+
+This skill turns UI research into an explicit workflow: retrieve relevant references, translate transferable patterns into a design contract, implement within the current project's system, and run the available validation or critique gates.
+
+## When to Use This Skill
+
+- You are designing a new product screen, flow, or component for web or iOS.
+- You need real interface references before implementing an AI-generated UI.
+- You are reviewing an implementation against explicit design constraints.
+- You need to reduce generic or repetitive UI by grounding work in observed product patterns.
+
+## How It Works
+
+### Step 1: Confirm access and scope
+
+Confirm that the UIZZE MCP connection is already configured with a valid agent token before invoking hosted workflows. If it is unavailable, use the free public catalog for research or ask the user to configure access; do not attempt to bypass access controls or expose credentials.
+
+### Step 2: Retrieve relevant visual context
+
+Use the available UIZZE tools to find screens, flows, components, or elements that match the product task. Focus on transferable patterns such as hierarchy, navigation, interaction states, spacing, density, and responsive behavior.
+
+### Step 3: Make constraints explicit
+
+Create or use a structured design contract when the task needs explicit acceptance criteria. Adapt patterns to the existing project design system instead of treating any reference as a visual template.
+
+### Step 4: Validate before completion
+
+Use the available UIZZE validation, audit, or critique workflow when the implementation is ready for review. Resolve the findings in the project and run normal project tests before calling the work complete.
+
+## Examples
+
+### Research an iOS onboarding flow
+
+```text
+Use UIZZE to research real iOS onboarding flows for a subscription product. Identify transferable patterns for progressive disclosure and permission timing, turn them into a concise design contract, then propose an implementation that fits this app's existing design system.
+```
+
+### Review a web settings screen
+
+```text
+Use UIZZE to inspect relevant real product settings screens, audit this implementation against a design contract for hierarchy, form states, and navigation, then list the concrete changes needed before release.
+```
+
+## Best Practices
+
+- ✅ Start with the smallest relevant set of references rather than collecting a broad gallery.
+- ✅ Separate observed patterns from the current project's brand and component rules.
+- ✅ Use validation findings as implementation feedback, not as permission to copy an interface.
+- ❌ Do not reproduce another product's brand, proprietary copy, assets, or exact layout.
+- ❌ Do not commit agent tokens, include them in prompts, or place them in client-side code.
+
+## Security & Safety Notes
+
+- Keep the UIZZE agent token in local agent configuration or an environment variable only.
+- Hosted MCP workflows require authorized access; the free catalog does not grant permission to use paid workflows.
+- Treat returned references as research context, not reusable visual assets.
+
+## Common Pitfalls
+
+- **Problem:** Treating a reference as a design to clone.
+  **Solution:** Extract the interaction or hierarchy pattern, then implement it using the target project's own design system and content.
+- **Problem:** Starting implementation before the agent has relevant UI context.
+  **Solution:** Search for the smallest useful set of matching screens or flows first, then define constraints before coding.
+- **Problem:** Exposing an agent token in a repository or chat transcript.
+  **Solution:** Store credentials only in supported local configuration or environment variables and rotate a token if it is exposed.
+
+## Related Skills
+
+- `@stitch-ui-design` - Use when generating or iterating UI concepts in Google Stitch.
+
+## Limitations
+
+- This skill does not replace product-specific user research, accessibility review, project tests, or human design judgment.
+- It cannot make a hosted UIZZE MCP workflow available without a valid authorized connection.
+- Stop and ask for clarification if the product goal, existing design system, or access boundaries are missing.

package/bundled-skills/vibe-code-auditor/SKILL.md

@@ -57,7 +57,7 @@ Use these heuristics to accelerate detection:
 
 | Pattern | Likely Issue | Quick Check |
 |---------|-------------|-------------|
-| `eval()`, `exec()`, `os.system()` | Security critical | Search for these strings |
+| `eval()`, `exec()`, `os.system()` | Security critical | Search for these strings | <!-- security-allowlist: defensive audit table -->
 | `except:` or `except Exception:` | Silent failures | Grep for bare excepts |
 | `password`, `secret`, `key`, `token` in code | Hardcoded credentials | Search + check if literal string |
 | `if DEBUG`, `debug=True` | Insecure defaults | Check config blocks |

package/bundled-skills/vibecode-production-qa-validator/SKILL.md

@@ -239,7 +239,7 @@ qa:heavyload() {
 qa:vulns() {
   npm audit 2>/dev/null | grep -E "critical|high" | grep . && echo "  ✗ Vulnerabilities!" || echo "  ✓ No critical/high vulns"
   npm outdated 2>/dev/null | head -5 | grep . || echo "  ✓ All up to date"
-  local D=$(grep -rn "eval(\|new Function(\|document.write(" app/ src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -5)
+  local D=$(grep -rn "eval(\|new Function(\|document.write(" app/ src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -5) # security-allowlist: defensive source scan
   [ -n "$D" ] && echo "  ⚠ Dangerous patterns:" && echo "$D" || echo "  ✓ No dangerous patterns"
 }
 qa:cleanup() {

package/bundled-skills/videodb/scripts/ws_listener.py

@@ -35,17 +35,9 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 
-def safe_user_path(path_value, base_dir="."):
-    """Resolve a CLI path under the current workspace."""
-    if base_dir != ".":
-        raise ValueError("Custom base directories are not supported for CLI paths")
-    base_path = Path.cwd().resolve()
-    resolved_path = Path(path_value).expanduser().resolve()
-    try:
-        resolved_path.relative_to(base_path)
-    except ValueError as exc:
-        raise ValueError(f"Path escapes allowed directory: {path_value}") from exc
-    return resolved_path
+def normalize_output_dir(path_value):
+    """Normalize the user-selected state directory without resolving symlinks."""
+    return Path(os.path.abspath(os.path.expanduser(str(path_value))))
 
 from dotenv import load_dotenv
 load_dotenv()
@@ -77,7 +69,7 @@ def parse_args():
         state_root = Path(os.environ.get("XDG_STATE_HOME", Path.home() / ".local" / "state"))
         output_dir = str(state_root / "videodb-events")
     
-    return clear, safe_user_path(output_dir)
+    return clear, normalize_output_dir(output_dir)
 
 CLEAR_EVENTS, OUTPUT_DIR = parse_args()
 EVENTS_FILE = OUTPUT_DIR / "videodb_events.jsonl"
@@ -106,6 +98,28 @@ def ensure_output_dir():
     OUTPUT_DIR.mkdir(parents=True, mode=DIR_MODE, exist_ok=True)
 
 
+def safe_output_path(path_value):
+    """Resolve a generated output file under the configured output directory."""
+    candidate = Path(path_value)
+    if not candidate.is_absolute():
+        candidate = OUTPUT_DIR / candidate
+    candidate = Path(os.path.abspath(candidate))
+    try:
+        candidate.relative_to(OUTPUT_DIR)
+    except ValueError as exc:
+        raise ValueError(f"Path escapes output directory: {path_value}") from exc
+    if candidate.is_symlink():
+        raise OSError(f"Refusing to use symlinked output file: {candidate}")
+
+    output_root = OUTPUT_DIR.resolve()
+    resolved_path = candidate.resolve(strict=False)
+    try:
+        resolved_path.relative_to(output_root)
+    except ValueError as exc:
+        raise ValueError(f"Path escapes output directory: {path_value}") from exc
+    return resolved_path
+
+
 def secure_open(path: Path, *, append: bool):
     """Open a regular file without following symlinks."""
     ensure_output_dir()
@@ -113,7 +127,7 @@ def secure_open(path: Path, *, append: bool):
     flags |= os.O_APPEND if append else os.O_TRUNC
     flags |= getattr(os, "O_NOFOLLOW", 0)
 
-    fd = os.open(safe_user_path(path), flags, FILE_MODE)
+    fd = os.open(safe_output_path(path), flags, FILE_MODE)
     try:
         file_stat = os.fstat(fd)
         if not stat.S_ISREG(file_stat.st_mode):
@@ -128,14 +142,14 @@ def secure_open(path: Path, *, append: bool):
 
 def secure_write_text(path: Path, content: str):
     """Write text to a regular file with private permissions."""
-    fd = secure_open(safe_user_path(path), append=False)
+    fd = secure_open(path, append=False)
     with os.fdopen(fd, "w", encoding="utf-8") as handle:
         handle.write(content)
 
 
 def secure_append_text(path: Path, content: str):
     """Append text to a regular file with private permissions."""
-    fd = secure_open(safe_user_path(path), append=True)
+    fd = secure_open(path, append=True)
     with os.fdopen(fd, "a", encoding="utf-8") as handle:
         handle.write(content)
 

package/bundled-skills/voice-ai-engine-development/README.md

@@ -150,7 +150,7 @@ See `references/common_pitfalls.md` for detailed solutions to:
 
 ## Contributing
 
-This skill is part of the Antigravity Awesome Skills repository. Contributions are welcome!
+This skill is part of the Agentic Awesome Skills repository. Contributions are welcome!
 
 ## Related Skills
 

package/bundled-skills/vulnerability-scanner/SKILL.md

@@ -204,7 +204,7 @@ Is it actively exploited (EPSS >0.5)?
 | Pattern | Risk | Look For |
 |---------|------|----------|
 | **String concat in queries** | Injection | `"SELECT * FROM " + user_input` |
-| **Dynamic code execution** | RCE | `eval()`, `exec()`, `Function()` |
+| **Dynamic code execution** | RCE | `eval()`, `exec()`, `Function()` | <!-- security-allowlist: defensive vulnerability taxonomy -->
 | **Unsafe deserialization** | RCE | `pickle.loads()`, `unserialize()` |
 | **Path manipulation** | Traversal | User input in file paths |
 | **Disabled security** | Various | `verify=False`, `--insecure` |

package/bundled-skills/warehouse/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: warehouse
+description: "Plan and review read-only data warehouse analysis with explicit scope, privacy, provenance, and validation checks."
+category: data
+risk: critical
+source: self
+source_type: self
+date_added: "2026-07-12"
+author: Rudra-G-23
+tags: [analytics, data-warehouse, sql, data-quality]
+tools: [claude, cursor, gemini]
+---
+
+# Warehouse Analysis
+
+## Overview
+
+Use this skill to turn a business question into a careful, reproducible warehouse-analysis plan. It is vendor-neutral and assumes no particular schema, semantic layer, connector, or command-line tool.
+
+The skill defaults to read-only work. It helps identify the data needed, review a proposed query, and communicate results without overstating what the evidence supports.
+
+## When to Use
+
+- The user wants to answer a business question using an authorized data warehouse.
+- A proposed SQL query needs a review for grain, joins, filters, privacy, or interpretation risks.
+- An analysis needs a clear record of scope, freshness, assumptions, and source tables.
+
+Do not use this skill for warehouse administration, pipeline repair, access escalation, schema mutation, or production data changes.
+
+## Required Inputs
+
+Before proposing a query, establish:
+
+1. The decision or question the analysis should inform.
+2. The population, metric, dimensions, and time window.
+3. The authorized warehouse or query interface available to the user.
+4. The relevant schema documentation or table metadata.
+5. Any privacy, retention, regional, or minimum-group-size constraints.
+
+If a required input is missing, ask a focused question. Never invent table names, column names, business definitions, credentials, or query results.
+
+## Workflow
+
+### 1. Define the analytical contract
+
+Restate the request as:
+
+- **Question:** what is being measured or compared.
+- **Population:** which entities are included and excluded.
+- **Metric:** numerator, denominator, aggregation, and unit.
+- **Window:** dates, timezone, and whether the period is complete.
+- **Decision:** how the result will be used.
+
+Call out ambiguous terms such as “active,” “customer,” “revenue,” or “last month.” Resolve ambiguity before querying.
+
+### 2. Find governed sources
+
+Prefer documented metrics, curated models, and governed tables over raw event streams. Use only schema information supplied by the user or available through an authorized interface.
+
+For each proposed source, record:
+
+- table or model name;
+- expected grain and primary key;
+- freshness or maximum available date;
+- owner or documentation reference;
+- known exclusions and quality warnings.
+
+If the source cannot be verified, label the plan as provisional and stop before presenting numerical conclusions.
+
+### 3. Draft a read-only query
+
+Create a query only when the real schema is known. The query should:
+
+- select only the columns needed for the stated question;
+- filter the requested time window explicitly;
+- use qualified column names and deterministic joins;
+- guard division by zero and null-sensitive calculations;
+- avoid row-level personal data when an aggregate answers the question;
+- include a conservative row limit for exploratory output when appropriate.
+
+Do not emit guessed SQL with fictional identifiers. If no authorized execution tool is available, provide the reviewed query for the user to run rather than claiming it was executed.
+
+### 4. Review before execution
+
+Check the proposed query against this list:
+
+- Does every join preserve the intended grain?
+- Can a one-to-many join duplicate the numerator or denominator?
+- Are test, deleted, internal, or incomplete records handled deliberately?
+- Are timezone boundaries and partial periods explicit?
+- Does the query expose identifiers or small groups unnecessarily?
+- Would a simpler aggregate answer reduce data access?
+- Are metric definitions consistent with the documented source?
+
+Revise any failed check before execution. For sensitive or high-impact decisions, ask for review by the data owner or another qualified analyst.
+
+### 5. Execute only with authorization
+
+Run a query only through a user-authorized, read-only interface. Do not request credentials in chat, bypass access controls, broaden permissions, or turn a read-only task into a write operation.
+
+Stop if the interface is unavailable, the scope exceeds the user's authorization, or the result would reveal restricted personal or confidential data.
+
+### 6. Validate the result
+
+Before interpreting output:
+
+- compare row counts and totals with a trusted reference when one exists;
+- inspect null rates, duplicates, and unexpected categories;
+- test whether conclusions change under reasonable window or filter choices;
+- separate observed values from hypotheses about their causes.
+
+Do not infer causality from a descriptive query. Do not hide contradictory or incomplete evidence.
+
+### 7. Report with provenance
+
+Use a compact result structure:
+
+```text
+Finding: [what the data shows]
+Scope: [population and period]
+Method: [metric and source summary]
+Confidence: [high, medium, or low, with reason]
+Caveats: [freshness, exclusions, quality, or privacy limits]
+Next step: [optional validation or decision input]
+```
+
+Include the query or a reproducible query summary when disclosure is appropriate. Redact secrets, credentials, and unnecessary row-level data.
+
+## Example
+
+**Request:** “Did weekly activated accounts improve after the onboarding change?”
+
+**Safe response plan:**
+
+1. Clarify the activation definition, rollout date, eligible population, timezone, and comparison window.
+2. Locate the governed activation metric and account cohort source.
+3. Aggregate weekly counts or rates without selecting account-level identifiers.
+4. Review cohort overlap, partial weeks, seasonality, and join duplication.
+5. Report the observed change as an association, with confidence and caveats, not as proof of causation.
+
+## Security & Safety Notes
+
+- Treat warehouse contents and schema metadata as confidential unless the user establishes otherwise.
+- Use least privilege and read-only access; never modify tables, permissions, pipelines, or production configuration.
+- Minimize personal data and aggregate results whenever possible.
+- Never place credentials, tokens, connection strings, or raw sensitive records in prompts or reports.
+- Stop and escalate to the data owner when policy, authorization, or disclosure boundaries are unclear.
+
+## Limitations
+
+- This skill cannot discover an undocumented schema or verify a result without an authorized data source.
+- It does not replace organization-specific metric definitions, privacy policy, or expert review.
+- It does not diagnose pipelines, administer warehouses, or make product and business decisions.
+- Conclusions remain limited by source quality, freshness, sampling, and the analytical design.