@vextlabs/theron-cli 0.3.0 → 0.4.0

package/skills/seo-brief.md

@@ -0,0 +1,201 @@
+---
+name: seo-brief
+description: Research and structure an SEO content brief — map search intent, SERP features, entity clusters, E-E-A-T signals, secondary queries, title/meta/H1, recommended layout, and draft the featured-snippet opening to maximize organic reach for a target keyword.
+allowed-tools: WebSearch, WebFetch, Read, Write
+---
+
+## ═══ HARD RULES (read before starting any phase) ═══
+
+- **Never copy a featured snippet.** A verbatim or near-verbatim opening earns a duplicate-content flag. Find a fresher angle from PAA or the entity map; if none exists, defer snippet-targeting to a post-publish revision.
+- **Entity mentions must be accurate.** Verify every product feature, benchmark number, and competitor claim against the actual source page or press release — not from memory, not from a summary. If you cannot verify, say so explicitly in the brief.
+- **Wordcount is a ceiling and a floor from SERP evidence, not a padded target.** If the best answer is 1800 words, do not inflate to 2500. If the SERP average demands 3200, do not cut at the cost of depth.
+- **Secondary queries are research inputs, not a coverage mandate.** Include only secondaries that share the same intent as the primary or resolve a genuine blocker to understanding it.
+- **PAA questions must be addressed even when inconvenient.** Omitting a top PAA question signals shallow research to both readers and crawlers.
+- **Internal links must point to existing, high-relevance pages.** Do not invent links; each one must improve a reader's ability to understand the target query.
+- **Structure is a hypothesis.** The brief sets a baseline; drafters may refactor section order if the writing reveals a better architecture.
+- **Keyword ambiguity must be resolved before any research begins.** If the target keyword has multiple distinct meanings (e.g., "python" = programming language or snake; "crane" = bird, machine, or surname), identify the correct meaning explicitly and lock it before step 1.
+
+---
+
+## ═══ PHASE A — KEYWORD DISAMBIGUATION & INTENT ANALYSIS ═══
+
+1. **Resolve ambiguity first.** State the exact target keyword and confirm which meaning or vertical it refers to. If the keyword is unambiguous, say so and continue. Do not proceed past step 1 with an unresolved ambiguity.
+
+2. **Classify intent** using operator tokens:
+   - Brand-name query (e.g., "[ProductName] review"): note the vertical and whether the brand owns the SERP or third parties dominate.
+   - "Best X" / "Top X" / "X vs Y": commercial-investigation intent — expect listicle and comparison pages to dominate.
+   - "How to X" / "X tutorial": informational/educational — expect step-by-step guides and video results.
+   - Question form ("Why does X…" / "What is X"): PAA and featured-snippet territory; paragraph snippet likely.
+   - Transactional ("buy X", "X pricing", "X free trial"): bottom-of-funnel — product and pricing pages dominate; brief should skew toward conversion copy not education.
+
+3. **Fetch keyword volume and difficulty estimates** using WebSearch (Google Keyword Planner public data, Ahrefs free tools, or Semrush free tier if accessible). Record:
+   - Monthly search volume range (even a rough band: <1K / 1K–10K / 10K–100K / 100K+).
+   - Keyword difficulty score if available (0–100 scale).
+   - Search volume trend (growing, stable, declining) — flag seasonal spikes.
+   - If estimates are unavailable, note the gap explicitly; do not fabricate numbers.
+
+4. **Search the exact target keyword and record SERP features present:**
+   - Featured snippet: format (paragraph, numbered list, bulleted list, table)? Source URL? Approximate word count of snippet text?
+   - People Also Ask (PAA): list the top 4 questions verbatim.
+   - Knowledge panel: what fields does Google display (description, founding date, social links)?
+   - Video carousel: present? How many results?
+   - Image pack: present?
+   - Ad count above organic results (0, 1–2, 3+): high ad count signals high commercial intent and competitive CPCs.
+   - Local pack / map pack: present? (Signals local intent — content strategy shifts significantly.)
+
+5. **Record the top-10 organic results** by URL and title. Identify:
+   - Domain authority pattern: how many results are from established authority domains (Gartner, Capterra, G2, Forbes, ArXiv, PubMed, .gov, .edu)? If 6+, this is a high-authority SERP — your content needs strong E-E-A-T signals (author credentials, original data, cited sources).
+   - Content type breakdown: product pages, third-party comparisons, editorial guides, forums (Reddit/Quora)?
+   - Publish and "last updated" dates of top-3 results: freshness signal — if top results are <6 months old, Google rewards recency and your publish date matters.
+
+6. **Fetch and read the top-3 organic results.** For each, note:
+   - Approximate word count (estimate from page length).
+   - H2 section headers (these reveal the topic map Google considers complete for this query).
+   - Whether they cite primary sources (studies, original data, official documentation).
+   - One unique angle or data point each result provides that the others do not.
+   - Compute the **baseline wordcount**: average of the three word counts. This is your target range ±15%.
+
+7. **Document the current featured snippet verbatim** (first 2–3 sentences or all list items). This is the minimum bar your opening must exceed.
+
+---
+
+## ═══ PHASE B — E-E-A-T & AUTHORITY SIGNALS ═══
+
+8. **Assess the E-E-A-T requirements for this query.** Google's Quality Rater Guidelines weight Experience, Expertise, Authoritativeness, and Trustworthiness differently by query type:
+   - **YMYL queries** (Your Money or Your Life: finance, health, legal, safety): require documented author credentials, citations to primary sources, and a clear "last reviewed" date. Brief must include an author-bio recommendation and a source-citation mandate.
+   - **Commercial/SaaS queries** ("best AI agent platform"): require real user evidence (reviews, case studies, benchmark data) and transparent methodology for any rankings.
+   - **Informational/educational queries**: require cited sources for any factual claim; first-hand experience signals (screenshots, tested examples) outperform generic prose.
+   - **Brand queries** ("[ProductName] review"): require acknowledgment of weaknesses alongside strengths; one-sided briefs lose trust signals.
+   - Document which E-E-A-T tier applies and list 3 specific signals the published piece must include (e.g., "cite benchmark study," "include author bio with domain credentials," "add last-reviewed date in ISO 8601 format").
+
+9. **Identify the content gap from a trust perspective:**
+   - Do the top-3 results cite primary sources, or do they rely on secondary aggregation? If they aggregate, original primary research is a differentiator.
+   - Do they include first-hand experience (screenshots, tested workflows, personal data)? If not, first-hand content will outrank them.
+   - Is there a "last updated" date visible on the top results? If not and your content will be updated, adding a visible date is an easy trust signal win.
+
+---
+
+## ═══ PHASE C — ENTITY & TOPIC MAP ═══
+
+10. **Identify all entities the searcher must understand** to evaluate your angle:
+    - Core products/services named in the top-3 SERP results (use actual names from the pages, not from memory).
+    - Capability clusters relevant to this vertical (e.g., for an AI-tool query: reasoning quality, latency, cost-per-token, data privacy, integrations; for a SaaS tool query: pricing tiers, onboarding, support, integrations, compliance certifications).
+    - Use cases and verticals (who uses this, in what workflow, at what scale).
+    - Common objections and pain points surfaced in PAA questions and the top-3 results.
+    - Competing solutions named in the SERP (include them; omitting named competitors signals incompleteness).
+
+11. **Map the topic hierarchy** (outline structure, not final copy):
+    - H1: the target query itself or a direct semantic variation (not a marketing headline).
+    - H2 clusters: 4–6 major subtopics derived from the entity map and the H2 patterns observed in step 6 (not invented from scratch).
+    - H3 sub-points: entity-specific details, trade-offs, evidence items — one H3 per distinct subtopic, not per paragraph.
+    - Verify the H2 list covers all top-3 unique angles noted in step 6 AND all top-4 PAA questions from step 4.
+
+12. **Note mandatory mentions** for credibility in this vertical:
+    - Specific benchmark results or performance data (cite the source; do not paraphrase without attribution).
+    - Differentiator claims (must be verifiable; flag any claim you cannot verify with "(NEEDS VERIFICATION)" in the brief).
+    - Alternative solutions, with one factual statement about each (even unfavorable comparisons; credibility requires intellectual honesty).
+
+---
+
+## ═══ PHASE D — SECONDARY QUERY RESEARCH ═══
+
+13. **Generate 3–5 secondary queries** that ladder from the main intent. Use Google Suggest (type the keyword and note auto-completes) and "searches related to" at the bottom of the SERP. Common secondary patterns:
+    - "[keyword] + cost" / "[keyword] + pricing": commercial qualifier.
+    - "[keyword] + accuracy" / "[keyword] + benchmark" / "[keyword] + review": quality qualifier.
+    - "[keyword] vs [Competitor]": competitive positioning.
+    - "[keyword] + [specific vertical or use case]": domain segmentation.
+    - "[keyword] + tutorial" / "[keyword] + how to get started": onboarding/educational.
+
+14. **For each secondary query, fetch the top-3 results and determine:**
+    - Does the SERP overlap significantly with the primary keyword SERP? If not, it is a long-tail opportunity (low volume, low competition, easy to rank with a dedicated H3 or callout).
+    - If yes, extract one unique angle (data point, subtopic, specific feature) from that SERP that your primary brief should thread.
+    - Which secondary queries, if added as H3 subsections, would increase topical coverage without diluting intent?
+
+---
+
+## ═══ PHASE E — STRUCTURE & CONTENT STRATEGY ═══
+
+15. **Design the content structure** (H2 sections in recommended order, derived from SERP evidence — not from a template):
+    - **Opening / Intro** (H1 + 40–60-word paragraph for featured-snippet contention): answer the query immediately. No preamble, no "In this article we will…" sentences.
+    - **[Definition / Context H2]** (informational intent): establish the baseline concept before evaluating solutions. Skip if the query is purely transactional or comparative.
+    - **[Core entity H2 clusters]**: one H2 per major capability or use-case cluster from the entity map (step 10). Alternate between "what it does," "how to use it," and "when to choose it" framing.
+    - **[Proof / Evidence H2]**: benchmarks, independent reviews, third-party data, original test results. This section earns the E-E-A-T signals mandated in phase B.
+    - **[Comparison H2]** (commercial / competitive intent): direct vs. competitors. Include a trade-off table if the top-3 results do not — tables frequently earn featured-snippet placement for comparison queries.
+    - **[Use Cases / Verticals H2]**: make the solution concrete — name the specific workflow, role, and outcome, not abstract benefits.
+    - **[FAQ / PAA H2]**: address all 4 PAA questions verbatim as H3s with direct-answer opening sentences. This section directly targets PAA placement.
+    - **[Call to action / Next steps H2]**: one clear action (free trial, guide, tool, resource). No vague "learn more."
+
+16. **Recommend word count range** based on SERP baseline (step 6):
+    - If top-3 average 2500–3500 words: target 2800–3200.
+    - If top-3 average under 2000 words: target 1800–2400 (shorter content frequently wins informational queries; do not over-engineer).
+    - If PAA box exists: add 300–500 words to cover PAA questions as H3s.
+    - If content includes a data table or comparison matrix: subtract 200 words per table (tables convey information at higher density than prose).
+    - Heuristic formula (rough check, not a mandate): (number of H2 sections × 450) + (number of H3 sections × 150) + 300-word opening. If this diverges more than 20% from your SERP baseline, revisit section count.
+
+17. **Title tag and meta description** (distinct from H1 and the featured-snippet opening):
+    - **Title tag**: 50–60 characters (Google truncates beyond ~580px / ~60 chars). Must include the exact target keyword, ideally within the first 30 characters. Format: "[Target Keyword] — [Differentiator or Year]" (e.g., "Best AI Agent Platforms 2026 — Compared & Ranked").
+    - **Meta description**: 140–160 characters. Not a ranking factor but directly affects click-through rate. Include the target keyword, one concrete benefit, and a soft CTA. Write it as a standalone sentence someone would read out of context.
+    - **H1**: may differ slightly from the title tag (can be longer, more conversational) but must contain the target keyword or a direct semantic equivalent. One H1 per page.
+
+18. **Internal linking strategy** (if part of a larger site):
+    - Identify 4–6 related existing pages (sibling pages, category pages, product deep-dives).
+    - Anchor text: use the target keyword of the destination page, not "click here," "this article," or generic phrases.
+    - Placement: link to the "parent" topic in the first paragraph; place all other internal links in the section where they are contextually relevant, not grouped at the bottom.
+
+19. **Freshness strategy:**
+    - If the target query has a freshness signal (top results are <6 months old, or the topic is tied to a year, version, or event): include a visible "Last updated: [date]" field in the published page and schedule a review cadence (quarterly for fast-moving topics, annually for stable ones).
+    - If the query is evergreen: freshness is lower priority; focus on depth and entity coverage.
+
+---
+
+## ═══ PHASE F — FEATURED-SNIPPET & OPENING ═══
+
+20. **Analyze the current featured snippet format** (if one exists):
+    - **Paragraph snippet**: count sentences in the snippet box. Match or beat it at 2–3 tight sentences (40–60 words). Every sentence must deliver information, not setup.
+    - **Numbered list snippet**: count items. Match or exceed by 1–2 items if your data supports it. Do not add padding items to hit a number.
+    - **Table snippet**: record columns and rows. Add one additional column (e.g., cost, speed, compliance tier) that the existing snippet does not include — that differentiation is what earns the displacement.
+    - **Bulleted list snippet**: same rules as numbered list; assess whether your bullets can be more specific (named entities, concrete numbers) than the current snippet's bullets.
+
+21. **Draft the featured-snippet opening paragraph** (40–60 words, no external links, no brand promotion language):
+    - **Sentence 1**: define the target query directly. Format: "[Subject] is/are [concise definition that includes the most important distinguishing characteristic]."
+    - **Sentence 2–3**: deliver the most actionable part of the answer. For "how to" queries: state the first concrete step or the key decision criterion. For "what is" queries: add one defining use case or measurable outcome. For "best X" queries: state the primary evaluation criterion a buyer should apply.
+    - **Editing rule**: read aloud after drafting. Remove every hedge word ("arguably," "tends to," "may," "could," "often"). Remove every setup clause ("In order to understand X, it helps to first consider Y"). If a word does not carry information, delete it.
+
+22. **Validate the opening against the current featured snippet:**
+    - If your opening is a direct rewrite of the existing snippet: do not use it. Return to the PAA research and entity map to find a different angle.
+    - If your opening answers the query more completely or more specifically than the existing snippet: document why (e.g., "adds specific benchmark number the current snippet omits"; "replaces vague 'AI tool' with named category 'agentic reasoning platform'").
+
+---
+
+## ═══ PHASE G — VERIFICATION & FINAL BRIEF ═══
+
+23. **Cross-check the brief against SERP evidence:**
+    - Does your H1 match the target keyword or a direct semantic variation? If you re-framed it, confirm the re-framing still contains the keyword string.
+    - Does your H2 structure cover every unique angle from the top-3 results (step 6)? List any gaps.
+    - Are entity mentions specific and verifiable? Replace any generic placeholder (e.g., "leading competitors," "industry benchmarks") with the actual named entity or source.
+    - Are all 4 PAA questions addressed in the brief (as H3s, callouts, or FAQ sections)?
+
+24. **Validate entity coverage:**
+    - Count distinct named entities (products, services, standards, tools, organizations, people) in your outline. Target range: 8–15. Fewer than 8 = shallow; more than 15 = scattered and likely off-intent.
+    - Confirm each entity is named correctly (exact product name, not a paraphrase) and appears in the correct section context.
+
+25. **Output the final brief** as a single markdown-formatted document containing:
+    - **Target keyword** (exact string, confirmed disambiguation).
+    - **Intent classification** (informational / commercial / transactional / navigational).
+    - **Search volume estimate** (band) and keyword difficulty (if available).
+    - **SERP feature inventory** (snapshot from step 4).
+    - **E-E-A-T tier** and 3 mandatory trust signals for this query (from phase B).
+    - **Baseline wordcount** (top-3 average) and **recommended range**.
+    - **Title tag** (≤60 chars), **meta description** (≤160 chars), **H1**.
+    - **Content outline**: H1 → H2 sections with 2–3 bullet-point notes each (what to cover, what specific entities/data to include — not generic topic labels).
+    - **Featured-snippet opening** (verbatim draft, 40–60 words).
+    - **Secondary queries** (3–5, each with one unique angle to thread).
+    - **Internal linking targets** (source anchor text → destination page name).
+    - **Freshness strategy** (evergreen vs. date-stamped; review cadence).
+    - **One-line ranking rationale**: why this structure will rank over the current top results (e.g., "Covers all 4 PAA questions as dedicated H3s + adds a comparison table with cost column that no current top-3 result includes + cites the only published independent benchmark for this category").
+
+---
+
+## ═══ KEY PRINCIPLE ═══
+
+A brief is operationally useless until it has been checked against three independent SERP sources: (1) the top-3 organic results for the primary keyword — every H2 in the brief must either improve on a topic those results cover or fill a gap that PAA surfaces; (2) the top-4 PAA questions — every question must appear in the outline as a named H3 or callout; (3) the top-3 results for the strongest secondary query — at least one unique angle from that SERP must be threaded into the primary brief. If any of these three checks fail, the brief is incomplete. Completeness is the prerequisite for competitive ranking; everything else (writing quality, internal links, freshness signals) compounds on top of it.

package/skills/sql-query.md

@@ -0,0 +1,161 @@
+---
+name: sql-query
+description: Write, review, or optimize a SQL query against a real schema — confirm table grain + column names first, produce a correct readable query, verify row-count expectations, then measure and apply structural optimizations (indexes, predicate pushdown, window functions, N+1 elimination).
+allowed-tools: Read, Bash, Grep, Write
+---
+
+═══ HARD RULES ═══
+
+1. NEVER guess a column name, table name, or data type — inspect schema before writing a single line of SQL.
+2. NEVER assume grain — a table named `orders` may be one row per order LINE, not per order; confirm with a COUNT DISTINCT check.
+3. NEVER optimize before the query is correct — a fast wrong answer is worse than a slow right one.
+4. NEVER benchmark without a reproducible baseline — capture EXPLAIN ANALYZE (or equivalent) output BEFORE touching indexes or query structure.
+5. NEVER add an index without checking whether one already exists (pg: `\d tablename`; mysql: `SHOW INDEX FROM tablename`).
+6. NEVER use `SELECT *` in a delivered query — project only the columns the consumer needs.
+7. NEVER fabricate row counts, timing numbers, or index cardinality — measure them or say they are unknown.
+8. ALWAYS wrap destructive schema changes (DDL, DROP, ALTER) in a transaction with an explicit ROLLBACK path.
+9. ALWAYS state the target SQL dialect (PostgreSQL, BigQuery, Snowflake, SQLite, MySQL, DuckDB) — syntax differs materially.
+
+═══ PHASE A — SCHEMA RECON ═══
+
+A1. Identify the dialect. Ask or infer from the connection string / migration files / ORM config.
+
+A2. List relevant tables and their columns with types.
+    - PostgreSQL: `SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = '<t>' ORDER BY ordinal_position;`
+    - BigQuery/Snowflake: `SELECT column_name, data_type FROM <dataset>.INFORMATION_SCHEMA.COLUMNS WHERE table_name = '<t>';`
+    - SQLite: `.schema <table>` or `PRAGMA table_info(<table>);`
+    - DuckDB: `DESCRIBE <table>;`
+
+A3. Confirm grain (the unit one row represents).
+    ```sql
+    -- Example: is orders one row per order or per line item?
+    SELECT COUNT(*) AS total_rows, COUNT(DISTINCT order_id) AS distinct_orders FROM orders;
+    ```
+    If total_rows ≠ distinct_orders, the table is not order-grain — adjust joins and aggregations accordingly.
+
+A4. Inspect foreign keys and join columns — check nullable-ness; a NULL FK silently drops rows in INNER JOIN.
+    ```sql
+    SELECT COUNT(*) FROM a LEFT JOIN b ON a.b_id = b.id WHERE b.id IS NULL;
+    -- Non-zero = orphaned rows; decide INNER vs LEFT deliberately.
+    ```
+
+A5. Sample five representative rows to understand value distributions, nulls, and format conventions.
+    ```sql
+    SELECT * FROM <table> TABLESAMPLE SYSTEM(0.01) LIMIT 5;  -- PostgreSQL
+    SELECT * FROM <table> LIMIT 5;                            -- most dialects
+    ```
+
+A6. Check column statistics / cardinality for columns you plan to filter or join on.
+    ```sql
+    SELECT COUNT(DISTINCT status) AS cardinality, COUNT(*) FILTER (WHERE status IS NULL) AS nulls
+    FROM orders;
+    ```
+
+═══ PHASE B — WRITE THE CORRECT QUERY ═══
+
+B1. Restate the question in plain English before writing SQL. If the question is ambiguous, resolve it now (e.g., "revenue" = gross or net? date filter = created_at or updated_at?).
+
+B2. Sketch the logical pipeline: which tables, which join type, which filter predicates, which aggregation, which output columns. Write this as a comment block above the SQL.
+
+B3. Write the query top-down: CTEs for complex sub-steps, main SELECT last. Name CTEs descriptively (`active_users`, `daily_revenue`) not generically (`cte1`).
+
+B4. Apply filter predicates as early as possible (inside CTEs, not in an outer WHERE on a full join). Place the most selective filter first.
+
+B5. For aggregations, always verify the GROUP BY matches the desired grain:
+    - If you GROUP BY user_id but also SELECT order_date without aggregating it, you will get a dialect error or non-deterministic result.
+
+B6. Handle NULLs explicitly: `COALESCE`, `NULLIF`, `IS NOT DISTINCT FROM` where appropriate. Document every COALESCE with a comment explaining the default.
+
+B7. Use window functions over self-joins for running totals, rankings, and lag/lead patterns:
+    ```sql
+    -- PREFER
+    SUM(revenue) OVER (PARTITION BY user_id ORDER BY event_date ROWS UNBOUNDED PRECEDING) AS running_revenue
+    -- AVOID: correlated subquery or self-join for the same result
+    ```
+
+B8. Avoid correlated subqueries in SELECT lists — they execute once per row (N+1). Rewrite as a lateral join or CTE.
+
+B9. Document implicit business rules in SQL comments — specifically: (a) the meaning of any status/type enum value used as a literal (e.g., `-- 'P' = pending; see payments.type_enum`), (b) any column whose name diverges from its actual semantic (e.g., `amount` stored in cents), and (c) any CAST that compensates for a schema type mismatch between tables.
+
+═══ PHASE C — VERIFY CORRECTNESS ═══
+
+C1. State the expected row count and top-line metric BEFORE running. Derive the expectation from domain knowledge or a simpler control query, not from the query under test.
+
+C2. Run a control query to produce the ground-truth number independently:
+    ```sql
+    -- Control: total distinct users with at least one paid invoice in Q1 2026
+    SELECT COUNT(DISTINCT user_id) FROM invoices
+    WHERE status = 'paid' AND created_at >= '2026-01-01' AND created_at < '2026-04-01';
+    ```
+
+C3. Run the authored query. Compare output row count and key metric to the control. Discrepancy > 0 = investigate before proceeding.
+
+C4. Validate boundary conditions: empty partitions, NULL foreign keys, zero-amount transactions, time-zone edge cases at midnight UTC.
+
+C5. Check for fan-out: if a JOIN multiplies rows unexpectedly, `COUNT(*)` will be inflated. Detect with:
+    ```sql
+    SELECT order_id, COUNT(*) AS c FROM orders JOIN order_items USING (order_id)
+    GROUP BY order_id HAVING COUNT(*) > 1 LIMIT 5;
+    ```
+
+C6. For date/time predicates, confirm timezone handling. In PostgreSQL, `TIMESTAMPTZ` comparisons respect the session timezone; `TIMESTAMP` does not. Make the cast explicit.
+
+═══ PHASE D — OPTIMIZE ═══
+
+D1. Capture the baseline execution plan BEFORE any change.
+    ```sql
+    EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) <query>;   -- PostgreSQL
+    EXPLAIN ANALYZE <query>;                            -- MySQL 8+
+    -- BigQuery/Snowflake: use the Query Profile / Execution Details UI
+    ```
+    Record: total elapsed time, rows scanned, seq scan vs index scan, hash joins vs nested loops, sort spills.
+
+D2. Identify the top bottleneck (largest actual time node in EXPLAIN ANALYZE) — fix only that first.
+
+D3. Index candidates — add only if:
+    - The column appears in WHERE, JOIN ON, or ORDER BY.
+    - Table has > ~10k rows (small tables benefit from seq scans).
+    - The column has high cardinality (index on a boolean with 50/50 split rarely helps).
+    - No existing covering index already serves the predicate.
+    ```sql
+    CREATE INDEX CONCURRENTLY idx_invoices_user_created
+      ON invoices (user_id, created_at DESC)
+      WHERE status = 'paid';    -- partial index if status is always filtered
+    ```
+
+D4. Predicate pushdown: move filters inside CTEs or subqueries so the engine scans fewer rows before joining.
+
+D5. Avoid functions on indexed columns in WHERE (they defeat index use):
+    ```sql
+    -- BAD  (disables index on created_at)
+    WHERE DATE_TRUNC('day', created_at) = '2026-01-15'
+    -- GOOD (range predicate, index usable)
+    WHERE created_at >= '2026-01-15' AND created_at < '2026-01-16'
+    ```
+
+D6. Materialize expensive CTEs only when re-used more than once or when the planner makes a bad cardinality estimate. In PostgreSQL 12+, CTEs are inlined by default; use `WITH cte AS MATERIALIZED (...)` to force materialization.
+
+D7. For large aggregations in analytical databases (BigQuery, Snowflake, Redshift), cluster/partition tables on the most common filter column and ensure the query's WHERE predicate aligns with the partition key.
+
+D8. Re-run EXPLAIN ANALYZE after each change. Record before/after timings. Do not claim improvement without measured numbers.
+
+D9. Identify and flag any join or subquery pattern that will degrade super-linearly as data grows. Specifically: nested-loop joins on unindexed columns (O(N·M)), correlated subqueries in SELECT lists (re-executes per row), and CROSS JOIN or CARTESIAN products with no ON clause. If unavoidable, state the expected row count at which the plan will flip to a worse join strategy and recommend a LIMIT or materialization guard.
+
+═══ PHASE E — DELIVER ═══
+
+E1. Produce the final query with a header comment block:
+    ```sql
+    -- Purpose  : <one-sentence business question this answers>
+    -- Dialect  : PostgreSQL 16
+    -- Grain    : one row per user per calendar month
+    -- Verified : 2026-06-27 — 48 211 rows, matches control COUNT 48 211
+    -- Author   : <name or agent>
+    ```
+
+E2. Include the EXPLAIN ANALYZE summary (or timing) as a comment if optimization was performed.
+
+E3. If indexes were created, list them and the ALTER/CREATE statements so they are reproducible.
+
+E4. State any assumptions made during Phase A/B that the consumer should validate (e.g., "assumed revenue excludes refunds; refunds table not inspected").
+
+KEY PRINCIPLE: A SQL query is only as trustworthy as the schema inspection and row-count verification that preceded it — correctness first, speed second, never the reverse.

package/skills/story-craft.md

@@ -0,0 +1,163 @@
+---
+name: story-craft
+description: Craft short literary fiction — character desire + obstacle, scene-level cause-effect, sensory show-not-tell, escalating conflict to a turn, distinctive voice, no clichés — when user asks to write, revise, or critique a short story or flash fiction piece.
+allowed-tools: Read, Write
+---
+
+═══ HARD RULES ═══
+
+1. DESIRE IS NON-NEGOTIABLE. Every story must have a POV character who wants a concrete thing badly enough to act. State it in ten words or fewer before writing sentence one. If the want is a mood, a feeling, or an abstraction, it is not a want yet — restate until it is something that could be withheld or handed over.
+2. OBSTACLE MUST COST SOMETHING. The blocking force must threaten something the character cannot afford to lose. Stakes without credible loss-potential are decorative. The obstacle is not the weather, not bad luck — it is the force most precisely opposed to what the character wants.
+3. ONE SCENE = ONE CAUSAL CHANGE. Each scene-unit must end in a different world than it started: something is learned, broken, decided, or revealed that makes the next beat necessary. If the character ends the scene in the same relationship to their want as they began it, the scene is not a scene — it is a description.
+4. NO CLICHÉS — ABSOLUTE. "Heart pounding," "world crumbled," "she didn't know how long she stood there," "little did he know," "a single tear," "silence hung heavy." All banned. Every phrase that has appeared on a Hallmark card or in an airport thriller must be replaced with the specific, observed, true-to-this-character detail. The test: could this phrase appear in any other story? If yes, cut it.
+5. NO PURPLE PROSE. Emotion is conveyed through concrete action, sensation, and dialogue subtext — never adjective-stacking or direct emotional announcement ("she felt devastated," "he was overcome"). The reader feels what the character feels by seeing what the character does.
+6. EARN THE ENDING. The final image or beat must be made inevitable by what preceded it, not imported. Test: cover the last paragraph; if any other ending would fit equally well, the ending is not yet earned — trace back to the turn and rebuild from there.
+7. VOICE IS A CONSTRAINT, NOT A GARNISH. Decide the narrator's register, syntax rhythm, and vocabulary range before drafting. A voice that can shift without intention is not a voice. Hold it sentence by sentence. Drift is a craft failure.
+8. SENSORY SPECIFICITY OVER GENERIC ATMOSPHERE. "The kitchen smelled like old grease and burnt coffee" beats "the run-down diner felt sad." Name the brand, the texture, the specific sound. Generality kills atmosphere; specificity creates it.
+9. SHOW THE BODY, NOT THE EMOTION. Characters clench receipts, speak half-sentences, leave without eating — they do not feel things at the reader. The body is the instrument; let it perform.
+10. DO NOT MORALIZE. The story's meaning emerges from the specific. The moment you write the lesson, you have deleted the story. Trust the image to carry the weight.
+11. HOLD POV DISCIPLINE. Choose one psychic distance and hold it. Close-third and first-person: the narrator's knowledge ends at the POV character's skin. Omniscient: earn every head-hop with a clear tonal signal and never bounce between two characters in the same paragraph. Head-hopping without intention is a POV violation, not a style choice.
+12. GOVERN TIME DELIBERATELY. Scene (real time, dramatized) and summary (compressed time, reported) are different instruments. Do not use summary to avoid dramatizing difficult scenes. Do not use scene to justify chronological rambling. White space between sections signals a time jump — use it, then anchor the new moment with a grounding sensory detail within the first two lines.
+
+═══ PHASE A — EXCAVATION (before one sentence of prose) ═══
+
+A1. STATE THE ENGINE. Write three lines before drafting:
+    — WANT: [character] wants [concrete thing] because [irreplaceable reason].
+    — OBSTACLE: [what blocks them] threatens [what they cannot lose].
+    — TURN: the moment everything shifts is [specific action or revelation].
+    If any line contains an abstraction ("happiness," "love," "closure," "success"), restate until every slot is a physical, verifiable thing or event.
+
+A2. LOCATE THE COMPRESSION POINT. Short fiction must start as late as possible.
+    The story does not begin when the character woke up. It begins at the last moment
+    before the want and the obstacle collide. Find that moment. Start there.
+    For flash fiction (under 1,000 words): you have one scene, possibly two; start mid-collision.
+    For short story (1,000–7,500 words): you have room for a before-beat, but earn it in four sentences or cut it.
+    For sudden fiction (under 500 words): the story IS the turn; start inside it.
+
+A3. CHOOSE THE GOVERNING SENSORY FIELD. Pick the dominant sense for this world:
+    sound-world (a deafening factory, a silent waiting room), texture-world (clay, wet wool, grit under fingernails),
+    smell-world (bleach, garlic, river mud, the specific brand of cigarette).
+    Every scene returns to this field to anchor tone and create the felt continuity of a world.
+
+A4. DRAFT ONE LINE OF VOICE. Write one sentence in the narrator's exact register before drafting anything else.
+    Test: read it aloud. If it could be lifted into any other story without friction, the voice
+    is not specific enough. Revise until the syntax, diction, and rhythm could only belong here.
+
+A5. SET POV AND PSYCHIC DISTANCE. Decide:
+    — Person and tense (first/past, third/present, etc.) — then do not change them.
+    — Psychic distance: deep interior (we hear every micro-thought) vs. cinematic (we see behavior only) vs. godlike (we know more than any character). Each is legitimate; inconsistency is not.
+    — What the narrator does NOT know. The limits of the POV are as important as its access.
+
+═══ PHASE B — SCENE ARCHITECTURE ═══
+
+B1. MAP THE CAUSAL SPINE. For each scene-unit, write the connective:
+    "[Event X] therefore [Event Y], but [Complication Z]."
+    "Therefore" and "but" are mandatory connectives. "And then" signals no causation — only chronology.
+    If you cannot write the "therefore/but" chain for your story, you have a sequence, not a plot.
+
+B2. OPEN IN MOTION. The first sentence must contain a verb of action or perception, not
+    a description of setting, not a character introduction, not a rhetorical question.
+    Setting earns its place only when filtered through a character doing or noticing something that matters to the want.
+
+B3. CALIBRATE SCENE VS. SUMMARY. Ask for each unit of time in the story:
+    — Is the reader inside a scene (real time, dialogue, sensation)? If so, the scene must justify its duration by raising or shifting the stakes within it.
+    — Is the reader in summary? If so, keep it to one or two sentences. Never use summary to skip over what is actually the story.
+
+B4. ESCALATE THROUGH SPECIFICITY, NOT VOLUME. Conflict intensifies not through louder action
+    but through more precise revelation of what is actually at stake. Each beat should narrow
+    the character's options or deepen the cost of acting. The turn arrives when the last option closes or a new one opens at a terrible price.
+
+B5. WRITE THE TURN AS A MICRO-BEAT. The turn — the moment the story pivots — is usually
+    one sentence or one gesture. It is not a speech. It is the receipt left on the table,
+    the door that does not open, the name that is not said. Write it small, then leave
+    white space around it. Do not explain it. Do not follow it with a paragraph of processing.
+
+B6. CALIBRATE PACING BY SENTENCE LENGTH. High-tension beats: short declarative sentences,
+    fragments, line breaks. Digression, memory, or interiority: longer syntax with embedded subordinate clauses.
+    Never let rhythm run on autopilot for more than two consecutive paragraphs without a conscious decision.
+
+═══ PHASE C — DRAFT EXECUTION ═══
+
+C1. WRITE COLD. Draft without line-level editing until the ending is on the page.
+    Stopping to polish kills narrative momentum and biases you toward the first idea for every subsequent choice.
+    Get to the end. Then revise.
+
+C2. DIALOGUE AS PRESSURE, NOT INFORMATION. Characters do not explain the plot to each other.
+    Every spoken line either advances the want, reveals the obstacle, or performs subtext —
+    saying one thing while meaning another. If a line could be cut without the scene losing tension or revelation, cut it.
+    Attribution beats ("he said sadly") are almost always wrong; the line should carry its own affect.
+
+C3. INTERIORITY IS A BLADE, NOT A CUSHION. Interior thought is allowed only when it
+    recontextualizes what just happened or launches the next action. One or two sentences of interiority
+    maximum per page of prose. Never use it to cushion an underdramatized scene — dramatize the scene instead.
+
+C4. TIME JUMPS REQUIRE ANCHORING. After any white-space break that signals an elapsed time,
+    the new section must open with a specific sensory or situational detail that orients the reader
+    in the new moment within the first two lines. "Three weeks later" followed by abstract setup is not an anchor.
+
+C5. THE LAST IMAGE MUST ECHO THE FIRST. Not forced symmetry — the final sensory detail should
+    rhyme with or invert the opening sensory detail, creating the felt sense of a complete arc
+    without announcing that an arc has completed. The reader should feel it before they think it.
+
+═══ PHASE D — REVISION PROTOCOL ═══
+
+D1. CUT THE FIRST PARAGRAPH. In most first drafts, the real beginning is paragraph two.
+    Delete paragraph one and read from paragraph two. If nothing essential is lost, the cut is correct.
+    If something is lost, compress it into one sentence and embed it in paragraph two.
+
+D2. THE CLICHÉ SWEEP. Read every sentence and mark any phrase that has more than ten years of
+    continuous use in fiction. Replace each with an image or action drawn specifically from this story's world.
+
+D3. EMOTION-ANNOUNCEMENT AUDIT. Search for: "she felt," "he realized," "it hit her,"
+    "she knew then," "he understood," "she was devastated," "he was elated."
+    Replace each with the physical behavior or dialogue that would be visible to a camera placed outside the character.
+
+D4. POV AUDIT. Read for any sentence where the narrator knows something the POV character could not
+    know from their position in space, time, and consciousness. Flag each as a POV violation.
+    Either cut it, move it to a character who could know it, or deliberately shift to an omniscient register with a tonal signal.
+
+D5. THE SCENE REDUNDANCY TEST. At every scene break, ask: is the character in a different relationship
+    to what they want than they were when the scene opened? If the answer is "essentially the same,"
+    the scene has not earned its pages. Cut it or replace it with a scene that turns the screw.
+
+D6. THE SUMMARY AUDIT. Every block of summary: ask whether the events it describes would be more
+    powerful if dramatized. If yes, dramatize. If the events are genuinely transitional and carry
+    no emotional weight, keep the summary short and move on.
+
+D7. READ ALOUD FINAL. The ear catches what the eye skips: rhythm breaks, unintended internal rhyme,
+    repeated sentence structure that flattens tension, a voice drift from paragraph 3 onward.
+    Mark every moment you stumble and revise at that exact point.
+
+D8. THE ENDING CHECK. Cover the last paragraph. Ask: could any other ending serve equally well?
+    If yes, the ending is not yet structurally earned. Trace back to the turn and ensure the turn
+    makes this specific ending necessary, not just possible.
+
+═══ PHASE E — CRITIQUE MODE (when reviewing another writer's work) ═══
+
+E1. LEAD WITH THE SPECIFIC THING THAT WORKS. Name the exact sentence, beat, or structural choice —
+    not the general vibe. "The turn in paragraph six, where she puts the key in her pocket instead of the lock, is doing real work" is useful. "Good tension" is not.
+
+E2. DIAGNOSE WITH FICTION-SPECIFIC CATEGORIES, NOT GENERAL FEEDBACK.
+    The correct diagnosis framework for short fiction:
+    — DESIRE PROBLEM: want is unclear, abstract, or absent.
+    — OBSTACLE PROBLEM: stakes are decorative; blocking force does not threaten what the character cannot lose.
+    — CAUSATION PROBLEM: scenes connect by chronology not consequence; "and then" structure.
+    — POV PROBLEM: narrator knows things the POV character cannot; psychic distance is inconsistent.
+    — VOICE PROBLEM: register shifts without intention; diction does not belong to this narrator.
+    — TIME PROBLEM: summary is used to avoid dramatization; time jumps are unanchored.
+    — TURN PROBLEM: the pivot is either absent, over-explained, or not made inevitable by what preceded it.
+    — ENDING PROBLEM: ending is imported rather than earned; the last image does not rhyme with or invert the first.
+    Name the category, then the specific instance.
+
+E3. PRESCRIBE ONE OPTION, NOT THE FIX. Identify the structural or craft problem. Offer one
+    concrete possible approach — not the only correct solution, and not a rewritten version of the writer's own sentences.
+    If you must demonstrate a technique, use a neutral invented example, not the writer's material.
+    The writer's voice and the choices that produced it are not yours to replace.
+
+E4. CALIBRATE DEPTH TO DRAFT STAGE.
+    — First draft: structural notes only (desire, obstacle, causation, turn, ending). No line edits.
+    — Second draft: scene-level notes (POV, time, pacing, dialogue). No line edits.
+    — Near-final: line-level notes (cliché, voice drift, emotion-announcement, rhythm). Structural comments at this stage are noise.
+    Delivering the wrong level of intervention signals that you did not read the work carefully.
+
+KEY PRINCIPLE: The story's engine is not what happens — it is what the character cannot bring themselves to do, or cannot stop themselves from doing, and every scene is the cost of that pressure made visible. The writer's job is not to resolve that pressure but to make the reader feel its weight.

package/skills/tdd.md

@@ -0,0 +1,59 @@
+---
+name: tdd
+description: Test-driven development — red/green/refactor with the real test framework; write the failing test first, see it fail, minimal code to green, refactor, full-suite before done.
+allowed-tools: Read, Edit, MultiEdit, Write, Bash, Grep, Glob
+---
+
+## Phase 0 — Orient (do this before writing a single line of code or test)
+
+1. Read the spec or ticket in full. Extract: what behaviour is required, what the inputs/outputs are, what the acceptance criteria are, and every edge case you can identify (empty input, boundary values, invalid types, concurrent access, error paths).
+2. Ask clarifying questions and resolve ambiguity NOW. A test written against a misunderstood spec is wasted work.
+3. Find the test framework: `grep -r "\"test\":\|\"vitest\|\"jest\|\"mocha\|\"bun test" package.json` across the repo. Read one existing test file to learn import style, assertion library, setup/teardown conventions, and where test files live.
+4. Find the test runner command: look for `scripts.test` in `package.json`, or a `vitest.config.*` / `jest.config.*`. Run it once on the existing suite to confirm it passes before you touch anything: `npm test` (or `npx vitest run`, `npx jest`, etc.).
+5. List every discrete behaviour you must implement. Each behaviour = one RED→GREEN→REFACTOR cycle. Do not batch them.
+
+## Phase 1 — RED: write the smallest failing test
+
+6. Create or open the test file co-located with the module under test (e.g. `src/foo.test.ts` next to `src/foo.ts`).
+7. Write exactly ONE test that captures ONE behaviour from your list. Keep the test body to 5-10 lines. Name it precisely: `it("returns empty array when input list is empty", ...)`.
+8. Import the function/class under test. If the module does not exist yet, import from its future path — the test will fail to compile, which is the first RED.
+9. Run only that test file: `npx vitest run src/foo.test.ts` (or equivalent). You MUST see a failure. Read the failure message. Confirm it fails for the right reason — not a typo, not a missing import, not a wrong assertion.
+10. If the test passes immediately, it is testing nothing. Delete it and write a better one.
+
+## Phase 2 — GREEN: minimum code to pass
+
+11. Write the minimum production code that makes this one test pass. No extra logic, no handling of cases not yet tested, no premature abstraction.
+12. Run the same test file again. See green. If it is still red, fix only the production code — never weaken or delete the test.
+13. Run the FULL suite: `npm test`. Confirm you have not broken anything else. Fix any regressions before proceeding.
+
+## Phase 3 — REFACTOR: clean with tests green
+
+14. With all tests green, refactor production code and test code for clarity, duplication removal, and correct abstractions. Rename variables, extract helpers, remove dead code.
+15. After every refactor step, re-run the full suite. If anything turns red, revert the specific change — do not continue refactoring on red.
+16. Do not add behaviour during refactor. Behaviour changes belong in a new RED→GREEN cycle.
+
+## Phase 4 — Repeat per behaviour
+
+17. Return to your behaviour list. Pick the next item. Go to Phase 1.
+18. Grow the test file incrementally: happy path first, then edge cases, then error paths, then boundary values.
+
+## Test quality rules (non-negotiable)
+
+19. Test behaviour, not implementation. Assert what the function returns or what side-effect it produces — not which internal method it calls or what its internal state looks like. Avoid spying on private methods.
+20. No real network, clock, filesystem, or randomness in unit tests. Inject a fake adapter, stub `Date.now`, mock `Math.random`, use in-memory stores. Tests must be deterministic every run.
+21. Each test is independent. No shared mutable state between tests. Use `beforeEach` to reset, not `before` that runs once.
+22. Tests must be fast. If a test takes > 200 ms, you are doing I/O or startup work that belongs in a fixture or integration test.
+23. Never delete or comment out a failing test to make the suite green. Either fix the production code, fix a wrong assumption in the test, or mark it `todo`/`skip` with a dated comment explaining why.
+24. Cover: (a) the happy path, (b) each boundary value (off-by-one, zero, max), (c) invalid/malformed input, (d) error and exception paths, (e) async rejection paths if applicable.
+25. One assertion cluster per test (logically related assertions are fine; testing two unrelated behaviours in one `it` is not).
+
+## Commit discipline
+
+26. Commit after each GREEN + passing full suite. Small, typed commits: `test: add failing test for empty-list case` → `feat: return empty array for empty input` → `refactor: extract normalise helper`. Never commit on red.
+27. Before declaring the feature done, run the full suite one final time from a clean state: `npm test` (or `npx vitest run --reporter=verbose`). All tests green. No skipped tests without a dated justification comment.
+
+## Hard stops
+
+- If you find yourself writing production code before seeing a red test — stop. Delete the production code. Write the test first.
+- If the full suite is red and you do not know which change broke it — `git stash`, run suite, confirm green, then re-apply changes one at a time.
+- If a test is flaky (sometimes red, sometimes green) — stop and fix it before writing more code. Flaky tests are trust-destroyers.