Move skills to .agents/skills

2026-05-05 07:16:54 +01:00
parent 41f4f08831
commit bcbfe2be75
19 changed files with 39 additions and 36 deletions
@@ -0,0 +1,76 @@
+---
+name: query-reporter
+description: Capture Ecto SQL queries to a log file for analysis. Use this skill when the user asks to trace, capture, log, or inspect database queries, or mentions "SQL log", "query trace", "query capture", "what queries does this page run". Also use proactively when investigating slow pages, debugging N+1 queries, analyzing database performance, or when you need to understand what SQL a LiveView or action produces. Requires a running Phoenix server with Tidewave MCP.
+---
+
+# Query Reporter
+
+Captures all Ecto queries executed by the main Repo to a log file as executable
+SQL with interpolated parameters and source location comments.
+
+## Before You Start
+
+This skill requires the Tidewave MCP tools. Before proceeding, check whether
+`mcp__tidewave__project_eval` is available in your tool list.
+
+If Tidewave is not available, stop and tell the user:
+"The query reporter requires a running Phoenix server with Tidewave. Please start
+the server with `mise run dev:console` and ensure Tidewave is loaded, then try again."
+
+## Workflow
+
+### 1. Start capturing
+
+Pick a file path (use `/tmp/` to avoid cluttering the project):
+
+```elixir
+mcp__tidewave__project_eval(code: ~s[MusicLibrary.QueryReporter.start("/tmp/queries.sql")])
+```
+
+This truncates the file if it exists. Calling `start/1` again restarts with a fresh file.
+
+### 2. Trigger the queries you want to capture
+
+Navigate to a page, click a button, run a context function — whatever action you want
+to trace. Use Chrome DevTools MCP tools to visit pages if needed.
+
+### 3. Stop capturing
+
+```elixir
+mcp__tidewave__project_eval(code: ~s[MusicLibrary.QueryReporter.stop()])
+```
+
+### 4. Read the log
+
+Read the file you specified in step 1 to see all captured queries.
+
+## Output Format
+
+Each query in the log file looks like:
+
+```sql
+-- MusicLibrary.Collection.list_records/2, at: lib/music_library/collection.ex:42
+-- total=2.6ms db=2.6ms queue=0.0ms decode=0.0ms
+SELECT r0."id", r0."title" FROM "records" AS r0 WHERE (r0."purchased_at" IS NOT NULL) LIMIT 20;
+```
+
+- The first comment shows the Elixir function and file:line that originated the query
+- The second comment shows timing: total, db (query execution), queue (connection wait), decode
+- Parameters are fully interpolated (no `?` placeholders)
+- Each query ends with `;` and is separated by a blank line
+- Queries are executable — you can paste them into `sqlite3` or `mcp__tidewave__execute_sql_query`
+
+## What Gets Captured
+
+- All queries through `MusicLibrary.Repo` (the main application database)
+- Includes SELECT, INSERT, UPDATE, DELETE, and transaction statements (BEGIN/COMMIT)
+- Does **not** capture BackgroundRepo (Oban) or TelemetryRepo queries
+
+## Tips
+
+- The reporter adds minimal overhead (one file append per query), but remember to
+  stop it when you're done to avoid filling the log with unrelated queries
+- LiveView pages fire queries twice on initial load (once for the static mount,
+  once for the connected mount) — this is normal Phoenix behaviour
+- To capture queries from a specific action, start the reporter, perform only that
+  action, then stop immediately