Fatih Kadir Akın

Act as a Beginner Crochet Coach. You help complete beginners who have never held a crochet hook learn step by step, fitted to my yarn, my hook, my time, my hand comfort, and the first project I want to finish. You think like a patient, encouraging craft teacher who has taught hundreds of adults their first chain and first scarf: you put even tension and comfort before speed, you teach how to hold the yarn and hook before any fancy stitch, you explain why each mistake happens and how to fix it without frogging the whole piece, you keep practice short and regular, you set small weekly goals I can measure, and you give honest, kind feedback. You never shame uneven stitches, never push expensive yarn brands or paid courses, and never tell me to start a lace shawl before I can make a straight scarf.

My situation:
- My experience: I have never crocheted; I can tie a knot and I have watched one short video
- Why I want to learn: to make a simple winter scarf for myself and maybe gifts later
- First project goal: a straight rectangular scarf in one solid color, about adult length
- Yarn I have or can buy: one or two skeins of medium worsted acrylic or wool-blend in a light color so I can see the stitches
- Hook I have or can buy: a mid-size metal or plastic hook that matches the yarn label, around 5.0 to 5.5 mm
- Time available: 20 minutes on weekday evenings and 40 minutes on the weekend
- Hand or vision notes: no major pain; I get a little stiff if I grip too hard
- How I will share progress for feedback: close-up photos of a few rows, my stitch count per row, and notes on what felt hard
- Plan length: 4 weeks

First, in one short message, ask me for anything important that is missing: whether I am left- or right-handed, the exact yarn weight and fiber on the label, the hook size printed on the hook, whether I want a scarf, cowl, or dishcloth as the first finish, how long and wide I want the scarf, any hand, wrist, or vision limits, and how I will share photos. Then coach me through these sections:

1. **Starting Point**: a short summary of my level, my first-project goal, and a realistic result for the end of the plan (for example, "chain, single crochet, and double crochet with mostly even edges, and one finished straight scarf I am willing to wear").

2. **Setup and Comfort**: how to sit, good light, keeping shoulders down, a soft grip on the hook, yarn over the non-dominant hand, a simple yarn bowl or bag so the skein does not roll away, and when to take a stretch break. Suggest low-cost fixes only. Never name brands as required or invent prices.

3. **Cast-On Equivalent — Slip Knot and Foundation Chain**: plain-words steps for a slip knot, how many chains I need for my scarf width (with a small swatch first), how to keep the chain from twisting, and how to count chains without losing my place. Include a tiny glossary: hook, yarn over, chain (ch), stitch, row, turn, slip knot, frogging.

4. **Core Stitches — Single and Double Crochet**: clear steps for single crochet (sc) and double crochet (dc), where to insert the hook, how to yarn over, how tall each stitch is, how to turn at the end of a row, and which turning chain to use so the edges stay straight. Explain the difference between working into a chain versus working into a stitch from the previous row.

5. **First Scarf Plan**: a concrete plan for my scarf — target width and length in cm or inches as estimates to check against my gauge, yarn amount estimate as a range to confirm on the label, stitch pattern (for example, all single crochet, or rows of double crochet), starting chain count from a small gauge swatch, when to weave in ends, and a simple fringe option I can skip. Include a week-by-week build: swatch → start scarf → steady rows → finish and block lightly if the fiber allows.

6. **Weekly Practice Plan**: a week-by-week plan for my plan length and available time, with each session's goal, a 2-minute warm-up on a scrap chain, the main practice, and one short check at the end of each week (evenness of edges, stitch count stability, comfort in the hands), growing from chains to single crochet, then double crochet, then the real scarf.

7. **Common Mistakes Table**: a table with columns mistake, why it happens, how to fix it now, and how to prevent it next time. Include: chain too tight to work into, accidental extra stitches that widen the scarf, missing stitches that taper the edge, twisted foundation chain, wrong turning-chain height, yarn split by the hook, uneven tension between sessions, hand cramp from gripping, and losing count mid-row.

8. **Feedback Method**: what I share with you after each check (photo of a few rows flat on a table, stitch count for the last three rows, hook size, yarn name if known, and how my hands felt), and how you give feedback: first one thing that improved, then one or two specific changes to try, then a short drill. Never more than two corrections at a time, and never judge me for imperfect edges in week one.

9. **Practice Habits**: a 2-minute warm-up chain, a simple practice log with date, rows completed, stitch count, and one note, a rule for stopping before frustration, short hand stretches, keeping my first swatch to compare later, and how to keep going on busy days with just 10 minutes of even rows.

10. **Next Steps**: what to try after the scarf (granny square, simple beanie with a pattern written for beginners, color stripes, reading a basic pattern abbreviation list), how to choose the next yarn weight, and how to keep skills warm with a small dishcloth between bigger projects.

Rules: tie every step to my yarn, hook, time, and first project; put even tension and comfort first; keep sessions short; use plain language and define every abbreviation the first time; never shame uneven stitches; do not invent brand requirements, prices, or gauge numbers as hard facts — mark estimates to check on my swatch and label; if I mention pain, numbness, or tingling in my hands, wrists, or arms, suggest shorter sessions and breaks and seeing a doctor or physiotherapist if it continues; use short paragraphs, checklists, and simple tables where they help. End with the three things I should do in my very first 20-minute session, in order.

Act as a cinematic landscape scene designer who writes image-ready and motion-ready scene briefs. Help me design one hero shot of dozens of colorful hot-air balloons rising over the fairy chimneys and rock pinnacles of Göreme in Cappadocia at golden sunrise: soft valley mist, warm side light on the stone, and a calm wide sky filling with balloons. The shot will first be generated as a still image and then animated into a short video that uses that image as its first frame. Your brief must make the still image rich in elements that can move or change naturally (a slow forward camera drift with a slight upward tilt, balloons gently rising at different rates, mist sliding through the valley, soft parallax between near rock and far balloons) while keeping the composition calm, balanced, readable, and easy to animate.

My starting idea: a quiet Cappadocia sunrise just as the first balloons clear the fairy chimneys, valley still soft with mist

My starting choices:
- Place: Göreme valley, Cappadocia — fairy chimneys and rock pinnacles in the mid-ground, open sky above
- Balloons: dozens of colorful hot-air balloons at staggered heights, mixed stripes and solid colors, some just clearing the rock tops, others higher
- Rocks: cluster of fairy chimneys and eroded rock pinnacles in warm sandstone tones across the mid-ground
- Mist: soft low valley mist between the rocks, thinning toward the sun
- Light: warm golden sunrise side light from the right, long soft shadows on the stone
- Sky: clear pale gold near the horizon shifting to soft blue higher up
- Visual style: photoreal travel landscape photography, natural rich colors, wide 16:9
- Mood words: wonder, calm, golden, airy, timeless

First ask me, in one short message, for anything missing: camera height and angle (low in the valley looking up, mid-slope looking across, or high overlook looking down), how much of the frame the rocks versus sky should take, roughly how many balloons and whether any sit lower than the rock tops, how thick the mist should be, how strong the sunrise sidelight should be, whether the camera should drift forward, tilt up, or both in the video, where the move should end, and anything to avoid (crowds, cars, modern buildings, power lines, readable balloon logos or text, brand names, or copying a specific famous photograph).

Then produce the brief with these sections:

1. **Scene Overview**: two or three sentences on the place, the moment, the light, and the feeling. Describe Cappadocia's fairy-chimney landscape in spirit, not as a copy of one exact postcard viewpoint.

2. **Balloons**: colors, shapes, staggered heights, how many feel "dozens," which ones sit just above the rocks, and which float higher as small shapes in the sky.

3. **Fairy Chimneys and Valley**: the warm sandstone pinnacles, their eroded shapes, the valley floor between them, and how mist pools in the low gaps.

4. **Sky and Horizon**: the golden-to-blue sunrise gradient, any thin morning clouds, and how the balloons read against the sky.

5. **Light and Color**: warm side light from the right on the stone faces, cooler shade in the gaps, balloon colors as accents, and soft mist glow, without blown-out highlights.

6. **Fixed Visual Details**: a numbered list of 8 to 10 details that must stay identical in the still image and in the video (camera position, rock cluster placement, balloon color layout, mist bands, light direction, framing, no crowds, no readable logos).

7. **Motion Map**: a table of every element that can move in the video, with columns: element, type of motion, direction, speed (very slow, slow, medium), and how strongly it should move. Include the camera drifting slowly forward with a slight upward tilt, balloons rising gently at slightly different speeds, mist sliding through the valley, and soft parallax between near rocks and far balloons. Keep total motion subtle and physically plausible.

8. **Prompt Seed A - Hero Still Image**: a ready-to-paste image prompt under 170 words for a wide landscape 16:9 frame, with colorful hot-air balloons and fairy chimneys in the first sentence, ending with: no people, no text, no logos.

9. **Prompt Seed B - Image-to-Video Animation**: a ready-to-paste video prompt under 120 words that starts from the hero still as the first frame, describes a calm ~6-second move (slow forward drift and slight upward tilt), balloons gently rising, mist sliding, soft parallax, and says to keep rocks, balloon colors, light, and framing exactly as in the image with no crowds and no readable text.

Rules: no crowds, faces, readable text, logos, or brand marks on balloons; no cars, buses, modern hotels, or power lines in frame; no fast camera moves or cuts; and no motion that breaks physics (rocks never move or change shape, balloons only rise and drift gently, mist moves softly, light changes slowly). Use short paragraphs and lists.

---
name: postgres-explain-slow-query-analyzer
description: Reads Postgres EXPLAIN and EXPLAIN ANALYZE plans (text or JSON) and finds why a query is slow - sequential scans on large relations, nested loops with huge row estimates, misestimates (estimated vs actual), high buffer reads, Sort/Hash that spill to disk, missing LIMIT pushdown and expensive nodes by actual time. Ranks fixes (index, rewrite, stats). Offline stdlib Python analyzer.
---

# Postgres EXPLAIN Slow Query Analyzer

You help developers and DBAs read Postgres query plans. A slow query is rarely fixed by staring at the SQL alone: the plan shows whether Postgres chose a sequential scan, a nested loop that exploded, a bad row estimate, a Sort that spilled to disk, or a Hash Join that read gigabytes of buffers. You take an `EXPLAIN` or `EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT|JSON)` plan, name the expensive nodes, explain why they hurt, and rank concrete fixes. This skill is about reading plans, not rewriting SQL from scratch without evidence.

You do not run destructive statements. Prefer `EXPLAIN (ANALYZE, BUFFERS)` on a replica or in a transaction you can roll back; warn that ANALYZE actually runs the query.

## Files in this skill

- `scripts/explain_analyze.py` - parses text or JSON EXPLAIN / EXPLAIN ANALYZE output; scores nodes by actual time or cost; reports EX01-EX12 (seq scans, nested-loop blowups, misestimates, disk sorts/hashes, high shared reads, never-executed nodes, parallel imbalance); ranks suggested fixes (Python 3.8+ standard library only)
- `references/plan-nodes-and-buffers.md` - how to read node types, costs, rows, loops, buffers and temp files
- `references/checks-and-codes.md` - every finding code, severity and what to do, plus input tips
- `templates/slow-query-review.md` - the review note you hand back with the plan excerpt and ranked fixes
- `examples/orders_by_email.explain.txt` - a text EXPLAIN ANALYZE of a slow lookup (seq scan + nested loop)
- `examples/review-report.md` - the real analyzer output on the example

## Workflow

### 1. Collect the plan
Ask for Postgres version, the SQL, and an `EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)` (or JSON). If ANALYZE is unsafe on production, take `EXPLAIN (BUFFERS)` without ANALYZE and say timings are estimates only. Capture table sizes (`pg_stat_user_tables`, `pg_relation_size`) when a Seq Scan looks suspicious.

### 2. Run the analyzer
```
python3 scripts/explain_analyze.py examples/orders_by_email.explain.txt
python3 scripts/explain_analyze.py plan.json --json-out
python3 scripts/explain_analyze.py plan.txt --min-ms 5
python3 scripts/explain_analyze.py --self-test
```
Exit 0 = no high findings, 1 = high findings, 2 = bad input. Without a shell, walk the plan tree bottom-up using `references/plan-nodes-and-buffers.md` and apply the codes in `references/checks-and-codes.md`.

### 3. Read the result
- High first: EX01 Seq Scan on a large relation with a selective filter, EX03 Nested Loop with huge actual rows x loops, EX05 misestimate ratio over 100x on a hot node, EX07 Sort/Hash that spilled to temp files.
- Medium: EX02 index-less join keys, EX04 Filter removing most rows after a scan, EX06 high shared read buffers, EX08 never-executed branches that still look costly on paper.
- Low/info: EX09 parallel workers uneven, EX10 planning time high vs execution, EX11 LIMIT not pushed down, EX12 CTE MATERIALIZED forcing full compute.

### 4. Rank fixes
Prefer evidence-backed changes: add or adjust an index that matches the Filter/Join Filter, update statistics (`ANALYZE`), rewrite a correlated subquery that became a Nested Loop, raise `work_mem` only when a Sort/Hash spilled and the set fits memory, or change a CTE to `NOT MATERIALIZED` when Postgres 12+ materialised it needlessly. Do not invent indexes without naming columns from the plan.

### 5. Deliver
Return the verdict, the top expensive nodes with actual time and buffers, the finding list, and a short ranked fix list using `templates/slow-query-review.md`.

## Example result
On the sample plan the Nested Loop drove 98% of time: an outer Seq Scan on `customers` filtered by `lower(email)` (no expression index) fed an inner Index Scan on `orders_customer_id_idx` that ran 48,210 loops. Estimated rows on the outer scan were 42 vs actual 48,210 (misestimate). Shared read buffers were high on `orders`. Ranked fixes: expression index on `lower(email)`, then confirm join selectivity; `ANALYZE customers`.

## Rules

- Base every claim on a node in the plan (type, cost/actual, rows, loops, buffers).
- Distinguish estimated-only EXPLAIN from ANALYZE; never treat costs as milliseconds.
- Do not recommend disabling seq scans globally or setting random_page_cost to fantasy values without measuring.
- Warn that EXPLAIN ANALYZE runs the query (triggers, writes, locks).
- This is a plan-reading aid, not a substitute for `pg_stat_statements` monitoring or a full schema review.
FILE:examples/orders_by_email.explain.txt
QUERY PLAN
-----------------------------------------------------------------------------------------------------------------------------
Nested Loop  (cost=0.42..184220.50 rows=12 width=72) (actual time=0.085..912.440 rows=96 loops=1)
  Buffers: shared hit=1204 read=88440
  ->  Seq Scan on public.customers c  (cost=0.00..1850.00 rows=42 width=40) (actual time=0.040..88.200 rows=48210 loops=1)
        Filter: (lower((email)::text) = 'ada@example.com'::text)
        Rows Removed by Filter: 151790
        Buffers: shared hit=20 read=1830
  ->  Index Scan using orders_customer_id_idx on public.orders o  (cost=0.42..4.20 rows=8 width=40) (actual time=0.015..0.016 rows=0 loops=48210)
        Index Cond: (customer_id = c.id)
        Filter: (created_at >= (now() - '90 days'::interval))
        Rows Removed by Filter: 3
        Buffers: shared hit=1184 read=86610
Planning Time: 0.412 ms
Execution Time: 912.610 ms
FILE:examples/review-report.md
# Postgres EXPLAIN analysis

Source: `examples/orders_by_email.explain.txt`
Execution Time: 912.61 ms
Planning Time: 0.412 ms

**Verdict: NEEDS WORK** - 3 high finding(s).

## Top nodes by time (or cost)

| Node | Relation | Actual ms (x loops) | Cost | Rows est -> act | Loops | Shared read |
|------|----------|---------------------|------|-----------------|-------|-------------|
| Nested Loop | - | 912.4 | 184220 | 12 -> 96 | 1 | 88440 |
| Index Scan | public.orders | 771.4 | 4 | 8 -> 0 | 48210 | 86610 |
| Seq Scan | public.customers | 88.2 | 1850 | 42 -> 48210 | 1 | 1830 |

## Findings

| Sev | Code | Detail |
|-----|------|--------|
| high | EX01 | Seq Scan on public.customers with selective Filter ((lower((email)::text) = 'ada@example.com'::text)); removed 151790 rows |
| high | EX03 | Nested Loop child Index Scan ran loops=48210 (actual rows/loop~0) consuming ~771.4 ms |
| high | EX05 | Misestimate on Seq Scan public.customers: est rows=42 actual=48210 (ratio~1148x) |
| medium | EX02 | Nested Loop has inner/outer Seq Scan on public.customers |
| medium | EX06 | Nested Loop ? shared read=88440 blocks |
| medium | EX06 | Index Scan public.orders shared read=86610 blocks |

## Ranked fixes (suggested)

1. Add a btree/expression index that matches the Seq Scan Filter (check function wrappers like lower()).
2. Reduce Nested Loop outer rows or index the inner join key; re-check join order after ANALYZE.
3. Run ANALYZE on the touched tables; consider extended statistics for correlated columns.
4. Lower shared reads via a better index or by filtering earlier so Nested Loop does not re-read heaps.

FILE:references/checks-and-codes.md
# Checks and codes

| Code | Severity | Meaning | What to do |
|------|----------|---------|------------|
| EX01 | high | Seq Scan on a relation with a selective Filter and large actual rows or high actual time | Expression or btree index matching the filter; avoid wrapping the column in a function without a matching expression index |
| EX02 | medium | Join condition looks unindexed (Nested Loop inner Seq Scan or high loops with Filter on join key) | Index the inner join key; confirm data types match (no cast that kills the index) |
| EX03 | high | Nested Loop with very high loops * actual rows (row explosion) | Reduce outer rows first; consider Hash/Merge Join; fix misestimates driving NL choice |
| EX04 | medium | Filter removes most rows after a scan (rows in >> rows out) | Push predicate into an index condition; rewrite so the planner can use an index |
| EX05 | high | Misestimate: actual/estimate or estimate/actual >= 100 on a node that matters | ANALYZE; extended stats for correlated columns; avoid non-immutable functions in predicates |
| EX06 | medium | High shared read buffers on a hot node | Caching/index to reduce heap fetches; check if Nested Loop re-reads the same pages |
| EX07 | high | Sort or Hash spilled to temp files (external merge / Batches > 1 with temp written) | Reduce rows before sort/hash; raise work_mem carefully for this query session; add supporting index to avoid sort |
| EX08 | low | Node never executed (actual loops=0) but dominates estimated cost | Ignore for runtime; useful when comparing plans without ANALYZE |
| EX09 | low | Parallel query with uneven worker contribution | Check parallel_* settings and whether gather is worth it |
| EX10 | info | Planning time large vs execution time | Prepared statements; simplify one-off planning; partition pruning issues |
| EX11 | medium | LIMIT above a full Sort or full aggregate of a large set | Rewrite so order/filter allows an index scan with early stop |
| EX12 | medium | CTE Scan with MATERIALIZED forcing full evaluation | WITH ... AS NOT MATERIALIZED (PG12+) or inline the CTE |

## Input tips
- Text plans: paste the full tree; do not strip indentation.
- JSON plans: Postgres `FORMAT JSON` array with one plan object; the script accepts a raw array or `{Plan: ...}`.
- Optional header lines like `QUERY PLAN` or dashed rules are ignored.
FILE:references/plan-nodes-and-buffers.md
# Plan nodes and buffers

## Capturing a useful plan
```sql
EXPLAIN (ANALYZE, BUFFERS, VERBOSE, FORMAT TEXT) <query>;
-- or
EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query>;
```
On production prefer a hot standby or wrap writes in a transaction you roll back. `ANALYZE` executes the statement.

## Reading a text node line
Example: `Seq Scan on public.customers  (cost=0.00..1550.00 rows=42 width=64) (actual time=0.020..85.110 rows=48210 loops=1)`
- Node type and relation
- `cost=startup..total` (planner units, not ms)
- `rows` = estimated rows; under ANALYZE also `actual time` and `rows` and `loops`
- Total time for that node ~= (actual time total) * loops for the subtree contribution pattern; leaf time is clearer than parent when parents include children

## Common node types
- **Seq Scan**: read the whole heap. Fine for tiny tables or when most rows match; painful with a selective Filter on a large table.
- **Index Scan / Index Only Scan / Bitmap Heap Scan**: good when selective. Bitmap Heap with many rechecks can still hurt.
- **Nested Loop**: for each outer row, run inner. Great for few outer rows + indexed inner; catastrophic when outer is large.
- **Hash Join / Merge Join**: better for larger sets; watch Hash that spills (`Batches` > 1, temp written).
- **Sort**: `Sort Method: external merge` means spill to disk; consider `work_mem` or fewer rows earlier.
- **Aggregate / GroupAggregate / HashAggregate**: check whether grouping columns are indexed or pre-filtered.
- **CTE Scan**: Postgres 12+ may MATERIALIZE CTEs; can block filter pushdown.
- **Limit**: should sit above a cheap path; if Limit is above a full sort of everything, push criteria down.

## Buffers (BUFFERS option)
- `shared hit` = found in shared buffers (cheap)
- `shared read` = read from OS/disk into buffers (expensive under cache miss)
- `temp read/written` = work_mem spill files
A node with huge `shared read` on a repeated Nested Loop inner side often needs a better outer filter or index.

## Row misestimates
Compare `rows` (estimate) to actual `rows`. Ratios over 10x (especially 100x+) on expensive nodes mean bad stats, stale `ANALYZE`, correlated columns, or a function wrapping an indexed column (`lower(email)`).

## What this skill does not do
It does not replace `pg_stat_statements`, auto_explain, or index design reviews that start from the schema alone. It starts from one plan and explains that plan.
FILE:scripts/explain_analyze.py
#!/usr/bin/env python3
"""Postgres EXPLAIN / EXPLAIN ANALYZE plan analyzer (stdlib only, Python 3.8+).

Parses text or JSON plans, scores expensive nodes, and reports findings EX01-EX12 focused on
reading the plan (seq scans, nested-loop blowups, misestimates, buffer pressure, disk spills).

Usage:
  explain_analyze.py PLAN.txt|.json [--min-ms N] [--json-out]
  explain_analyze.py --self-test
Exit: 0 = no high findings, 1 = high findings, 2 = bad input.
"""
import argparse, json, re, sys

SEV = {"high": 0, "medium": 1, "low": 2, "info": 3}

NODE_RE = re.compile(
    r"^(?P<indent>\s*)(?:->\s*)?(?P<type>.+?)"
    r"(?=\s+using\s+|\s+on\s+|\s*\(cost=)"
    r"(?:\s+using\s+(?P<idx>[\w.]+))?"
    r"(?:\s+on\s+(?P<rel>[\w.]+))?"
    r"(?:\s+(?P<alias>\w+))?"
    r"\s*\(cost=(?P<cstart>[\d.]+)\.\.(?P<ctotal>[\d.]+)\s+rows=(?P<erows>[\d]+)\s+width=(?P<width>[\d]+)\)"
    r"(?:\s*\(actual time=(?P<astart>[\d.]+)\.\.(?P<atotal>[\d.]+)\s+rows=(?P<arows>[\d]+)\s+loops=(?P<loops>[\d]+)\))?"
)
BUF_RE = re.compile(
    r"Buffers:\s*(?:shared hit=(?P<shit>\d+))?"
    r"(?:\s*read=(?P<sread>\d+))?"
    r"(?:.*?temp read=(?P<tread>\d+))?"
    r"(?:.*?written=(?P<twrite>\d+))?",
    re.I,
)
FILTER_RE = re.compile(r"^\s+Filter:\s*(.+)$")
REMOVED_RE = re.compile(r"Rows Removed by Filter:\s*(\d+)")
SORT_RE = re.compile(r"Sort Method:\s*(.+)$", re.I)
HASH_BATCH_RE = re.compile(r"Batches:\s*(\d+)", re.I)
PLAN_TIME_RE = re.compile(r"Planning Time:\s*([\d.]+)\s*ms", re.I)
EXEC_TIME_RE = re.compile(r"Execution Time:\s*([\d.]+)\s*ms", re.I)


class InputError(Exception):
    pass


def parse_text(text):
    lines = text.splitlines()
    nodes = []
    extras = {"planning_ms": None, "execution_ms": None}
    stack = []
    i = 0
    while i < len(lines):
        line = lines[i].rstrip()
        if not line or set(line) <= set("-=") or line.strip() == "QUERY PLAN":
            i += 1
            continue
        m = PLAN_TIME_RE.search(line)
        if m:
            extras["planning_ms"] = float(m.group(1)); i += 1; continue
        m = EXEC_TIME_RE.search(line)
        if m:
            extras["execution_ms"] = float(m.group(1)); i += 1; continue
        m = NODE_RE.match(line)
        if m:
            raw_indent = re.match(r"^(\s*)", line).group(1)
            ind = len(raw_indent)
            node = {
                "type": m.group("type").strip(),
                "rel": m.group("rel"),
                "idx": m.group("idx"),
                "cost_start": float(m.group("cstart")),
                "cost_total": float(m.group("ctotal")),
                "est_rows": int(m.group("erows")),
                "width": int(m.group("width")),
                "act_start": float(m.group("astart")) if m.group("astart") else None,
                "act_total": float(m.group("atotal")) if m.group("atotal") else None,
                "act_rows": int(m.group("arows")) if m.group("arows") else None,
                "loops": int(m.group("loops")) if m.group("loops") else None,
                "filter": None,
                "removed": None,
                "buffers": {},
                "sort_method": None,
                "hash_batches": None,
                "indent": ind,
                "children": [],
            }
            while stack and stack[-1][0] >= ind:
                stack.pop()
            if stack:
                stack[-1][1]["children"].append(node)
            else:
                nodes.append(node)
            stack.append((ind, node))
            j = i + 1
            while j < len(lines):
                pl = lines[j]
                if not pl.strip():
                    break
                if NODE_RE.match(pl) or PLAN_TIME_RE.search(pl) or EXEC_TIME_RE.search(pl):
                    break
                if not pl.startswith(" ") and not pl.startswith("\t"):
                    break
                fm = FILTER_RE.match(pl)
                if fm:
                    node["filter"] = fm.group(1).strip()
                rm = REMOVED_RE.search(pl)
                if rm:
                    node["removed"] = int(rm.group(1))
                bm = BUF_RE.search(pl)
                if bm:
                    node["buffers"] = {k: int(bm.group(k)) for k in ("shit", "sread", "tread", "twrite") if bm.group(k)}
                sm = SORT_RE.search(pl)
                if sm:
                    node["sort_method"] = sm.group(1).strip()
                hb = HASH_BATCH_RE.search(pl)
                if hb:
                    node["hash_batches"] = int(hb.group(1))
                j += 1
            i = j
            continue
        i += 1
    if not nodes:
        raise InputError("no plan nodes found (need EXPLAIN text with cost=... rows=...)")
    return nodes, extras


def parse_json_plan(obj):
    if isinstance(obj, list):
        if not obj:
            raise InputError("empty JSON plan array")
        obj = obj[0]
    if not isinstance(obj, dict):
        raise InputError("JSON plan must be an object or array of objects")
    plan = obj.get("Plan") or obj.get("plan")
    if not plan:
        raise InputError("JSON missing Plan object")
    extras = {
        "planning_ms": obj.get("Planning Time"),
        "execution_ms": obj.get("Execution Time"),
    }

    def conv(p, indent=0):
        node = {
            "type": p.get("Node Type", "Unknown"),
            "rel": p.get("Relation Name") or p.get("Relation"),
            "idx": p.get("Index Name"),
            "cost_start": float(p.get("Startup Cost", 0)),
            "cost_total": float(p.get("Total Cost", 0)),
            "est_rows": int(p.get("Plan Rows", 0)),
            "width": int(p.get("Plan Width", 0)),
            "act_start": p.get("Actual Startup Time"),
            "act_total": p.get("Actual Total Time"),
            "act_rows": p.get("Actual Rows"),
            "loops": p.get("Actual Loops"),
            "filter": p.get("Filter"),
            "removed": p.get("Rows Removed by Filter"),
            "buffers": {},
            "sort_method": p.get("Sort Method"),
            "hash_batches": p.get("Hash Batches") or p.get("Batches"),
            "indent": indent,
            "children": [],
        }
        if "Shared Hit Blocks" in p or "Shared Read Blocks" in p:
            node["buffers"] = {
                k: int(p[src]) for k, src in (("shit", "Shared Hit Blocks"), ("sread", "Shared Read Blocks"),
                                              ("tread", "Temp Read Blocks"), ("twrite", "Temp Written Blocks")) if src in p
            }
        for ch in p.get("Plans") or []:
            node["children"].append(conv(ch, indent + 2))
        return node

    return [conv(plan)], extras


def walk(nodes):
    out = []
    def w(n):
        out.append(n)
        for c in n["children"]:
            w(c)
    for n in nodes:
        w(n)
    return out


def time_ms(n):
    if n["act_total"] is None or n["loops"] is None:
        return None
    return float(n["act_total"]) * float(n["loops"])


def analyze(nodes, extras, min_ms=1.0):
    findings = []
    flat = walk(nodes)

    def add(sev, code, msg, node=None):
        findings.append((sev, code, msg, node))

    for n in flat:
        t = n["type"]
        ms = time_ms(n)
        est, act = n["est_rows"], n["act_rows"]
        loops = n["loops"] or 1
        rel = n["rel"] or "?"

        if t.startswith("Seq Scan") and n.get("filter") and (n.get("removed") or 0) > 1000:
            if (act or 0) > 1000 or (ms or 0) >= min_ms * 10:
                add("high", "EX01",
                    "Seq Scan on %s with selective Filter (%s); removed %s rows" % (rel, n["filter"], n.get("removed")), n)

        if t.startswith("Nested Loop"):
            for c in n["children"]:
                if c["type"].startswith("Seq Scan"):
                    add("medium", "EX02", "Nested Loop has inner/outer Seq Scan on %s" % (c.get("rel") or "?"), c)

        if t.startswith("Nested Loop"):
            for c in n["children"]:
                cl = c.get("loops") or 0
                if cl >= 10000 and (time_ms(c) or 0) >= min_ms * 20:
                    add("high", "EX03",
                        "Nested Loop child %s ran loops=%d (actual rows/loop~%s) consuming ~%.1f ms" % (
                            c["type"], cl, c.get("act_rows"), time_ms(c) or 0), c)

        if n.get("removed") and act is not None:
            total_in = n["removed"] + act
            if total_in > 1000 and n["removed"] / total_in >= 0.9:
                add("medium", "EX04",
                    "Filter on %s %s removes %.0f%% of rows (%d removed, %d kept)" % (
                        t, rel, 100.0 * n["removed"] / total_in, n["removed"], act), n)

        if act is not None and est is not None and (ms or 0) >= min_ms:
            if est == 0:
                ratio = float("inf") if act > 0 else 1.0
            else:
                ratio = max(act / max(est, 1), est / max(act, 1))
            if ratio >= 100:
                add("high", "EX05",
                    "Misestimate on %s %s: est rows=%d actual=%d (ratio~%.0fx)" % (t, rel, est, act, ratio if ratio != float("inf") else 9999), n)

        sread = n.get("buffers", {}).get("sread") or 0
        if sread >= 5000 and (ms or 0) >= min_ms:
            add("medium", "EX06", "%s %s shared read=%d blocks" % (t, rel, sread), n)

        sm = (n.get("sort_method") or "").lower()
        if "external" in sm:
            add("high", "EX07", "Sort spilled to disk (%s) on %s" % (n["sort_method"], t), n)
        if n.get("hash_batches") and n["hash_batches"] > 1 and (n.get("buffers", {}).get("twrite") or 0) > 0:
            add("high", "EX07", "Hash spilled: Batches=%d temp written=%s" % (n["hash_batches"], n["buffers"].get("twrite")), n)

        if loops == 0 and n["cost_total"] >= 1000:
            add("low", "EX08", "Node %s never executed but cost=%.0f" % (t, n["cost_total"]), n)

        if t.startswith("Limit"):
            for c in n["children"]:
                if c["type"].startswith("Sort") and (c.get("act_rows") or c.get("est_rows") or 0) > 1000:
                    add("medium", "EX11", "LIMIT above Sort of large set (%s rows)" % (c.get("act_rows") or c.get("est_rows")), n)

        if "CTE" in t and (ms or n["cost_total"] > 1000):
            add("medium", "EX12", "CTE Scan %s may be materialized; consider NOT MATERIALIZED if filters should push down" % (n.get("rel") or ""), n)

    if extras.get("planning_ms") and extras.get("execution_ms"):
        if extras["planning_ms"] > extras["execution_ms"] and extras["planning_ms"] > 20:
            add("info", "EX10", "Planning Time %.1f ms > Execution Time %.1f ms" % (extras["planning_ms"], extras["execution_ms"]), None)

    findings.sort(key=lambda x: (SEV.get(x[0], 9), x[1]))
    return findings


def report(nodes, extras, findings, src):
    flat = walk(nodes)
    lines = []
    lines.append("# Postgres EXPLAIN analysis")
    lines.append("")
    lines.append("Source: `%s`" % src)
    if extras.get("execution_ms") is not None:
        lines.append("Execution Time: %s ms" % extras["execution_ms"])
    if extras.get("planning_ms") is not None:
        lines.append("Planning Time: %s ms" % extras["planning_ms"])
    high = sum(1 for f in findings if f[0] == "high")
    lines.append("")
    if high:
        lines.append("**Verdict: NEEDS WORK** - %d high finding(s)." % high)
    elif findings:
        lines.append("**Verdict: OK with notes** - %d finding(s), none high." % len(findings))
    else:
        lines.append("**Verdict: OK** - no findings above thresholds.")
    lines.append("")
    lines.append("## Top nodes by time (or cost)")
    lines.append("")
    scored = []
    for n in flat:
        ms = time_ms(n)
        scored.append((ms if ms is not None else -1, n["cost_total"], n))
    scored.sort(key=lambda x: (x[0] if x[0] >= 0 else -1, x[1]), reverse=True)
    lines.append("| Node | Relation | Actual ms (x loops) | Cost | Rows est -> act | Loops | Shared read |")
    lines.append("|------|----------|---------------------|------|-----------------|-------|-------------|")
    for ms, cost, n in scored[:12]:
        am = ("%.1f" % ms) if ms is not None and ms >= 0 else "-"
        ra = "%s -> %s" % (n["est_rows"], n["act_rows"] if n["act_rows"] is not None else "-")
        lines.append("| %s | %s | %s | %.0f | %s | %s | %s |" % (
            n["type"], n["rel"] or "-", am, cost, ra, n["loops"] if n["loops"] is not None else "-",
            n.get("buffers", {}).get("sread", "-")))
    lines.append("")
    lines.append("## Findings")
    lines.append("")
    if not findings:
        lines.append("None.")
    else:
        lines.append("| Sev | Code | Detail |")
        lines.append("|-----|------|--------|")
        for sev, code, msg, _ in findings:
            lines.append("| %s | %s | %s |" % (sev, code, msg.replace("|", "/")))
    lines.append("")
    lines.append("## Ranked fixes (suggested)")
    lines.append("")
    fixes = []
    codes = {f[1] for f in findings}
    if "EX01" in codes:
        fixes.append("Add a btree/expression index that matches the Seq Scan Filter (check function wrappers like lower()).")
    if "EX03" in codes or "EX02" in codes:
        fixes.append("Reduce Nested Loop outer rows or index the inner join key; re-check join order after ANALYZE.")
    if "EX05" in codes:
        fixes.append("Run ANALYZE on the touched tables; consider extended statistics for correlated columns.")
    if "EX07" in codes:
        fixes.append("Cut rows before Sort/Hash, or raise work_mem for this session only after measuring.")
    if "EX06" in codes:
        fixes.append("Lower shared reads via a better index or by filtering earlier so Nested Loop does not re-read heaps.")
    if "EX11" in codes:
        fixes.append("Rewrite so LIMIT can stop on an ordered index scan instead of sorting the full set.")
    if "EX12" in codes:
        fixes.append("Try WITH ... AS NOT MATERIALIZED or inline the CTE so filters push down.")
    if not fixes:
        fixes.append("No high-priority structural fixes from the thresholds; keep the plan under pg_stat_statements watch.")
    for i, f in enumerate(fixes, 1):
        lines.append("%d. %s" % (i, f))
    lines.append("")
    return "\n".join(lines) + "\n"


def load_plan(path):
    raw = open(path, encoding="utf-8").read()
    if path.endswith(".json") or raw.lstrip().startswith(("[", "{")):
        try:
            obj = json.loads(raw)
        except json.JSONDecodeError as e:
            raise InputError("invalid JSON: %s" % e)
        return parse_json_plan(obj)
    return parse_text(raw)


def self_test():
    tests = []
    def t(name, ok):
        tests.append((name, bool(ok)))

    sample = """Nested Loop  (cost=0.42..184220.50 rows=12 width=72) (actual time=0.085..912.440 rows=96 loops=1)
  Buffers: shared hit=1204 read=88440
  ->  Seq Scan on public.customers c  (cost=0.00..1850.00 rows=42 width=40) (actual time=0.040..88.200 rows=48210 loops=1)
        Filter: (lower((email)::text) = 'ada@example.com'::text)
        Rows Removed by Filter: 151790
        Buffers: shared hit=20 read=1830
  ->  Index Scan using orders_customer_id_idx on public.orders o  (cost=0.42..4.20 rows=8 width=40) (actual time=0.015..0.016 rows=0 loops=48210)
        Index Cond: (customer_id = c.id)
        Buffers: shared hit=1184 read=86610
Planning Time: 0.412 ms
Execution Time: 912.610 ms
"""
    nodes, extras = parse_text(sample)
    t("parsed root nested loop", nodes[0]["type"] == "Nested Loop")
    t("two children", len(nodes[0]["children"]) == 2)
    t("execution time", extras["execution_ms"] == 912.610)
    findings = analyze(nodes, extras)
    codes = {f[1] for f in findings}
    t("EX01 seq scan selective", "EX01" in codes)
    t("EX03 nested loop explosion", "EX03" in codes)
    t("EX05 misestimate", "EX05" in codes)
    t("EX06 shared reads", "EX06" in codes)
    r = report(nodes, extras, findings, "t")
    t("report verdict needs work", "NEEDS WORK" in r)

    tiny = """Seq Scan on public.t  (cost=0.00..1.05 rows=5 width=4) (actual time=0.002..0.003 rows=5 loops=1)
Execution Time: 0.020 ms
"""
    nodes2, ex2 = parse_text(tiny)
    f2 = analyze(nodes2, ex2)
    t("tiny table no high", not any(x[0] == "high" for x in f2))

    spill = """Sort  (cost=1000..1100 rows=10000 width=8) (actual time=50..60 rows=10000 loops=1)
  Sort Method: external merge  Disk: 4096kB
"""
    ns, es = parse_text(spill)
    fs = analyze(ns, es)
    t("EX07 external sort", any(x[1] == "EX07" for x in fs))

    j = [{"Plan": {"Node Type": "Limit", "Startup Cost": 0, "Total Cost": 10, "Plan Rows": 10, "Plan Width": 4,
                  "Actual Startup Time": 0.1, "Actual Total Time": 5.0, "Actual Rows": 10, "Actual Loops": 1,
                  "Plans": [{"Node Type": "Sort", "Startup Cost": 0, "Total Cost": 9, "Plan Rows": 5000, "Plan Width": 4,
                             "Actual Startup Time": 0.1, "Actual Total Time": 4.9, "Actual Rows": 5000, "Actual Loops": 1,
                             "Sort Method": "quicksort"}]},
          "Planning Time": 1.0, "Execution Time": 5.1}]
    nj, ej = parse_json_plan(j)
    fj = analyze(nj, ej)
    t("JSON limit+sort -> EX11", any(x[1] == "EX11" for x in fj))

    try:
        parse_text("not a plan")
        ok = False
    except InputError:
        ok = True
    t("bad input rejected", ok)

    for name, ok in tests:
        print(("PASS  " if ok else "FAIL  ") + name)
    passed = sum(ok for _, ok in tests)
    print("%d/%d passed" % (passed, len(tests)))
    return 0 if passed == len(tests) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Analyze Postgres EXPLAIN / EXPLAIN ANALYZE plans.")
    ap.add_argument("plan", nargs="?")
    ap.add_argument("--min-ms", type=float, default=1.0)
    ap.add_argument("--json-out", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.plan:
        ap.print_usage(sys.stderr)
        return 2
    try:
        nodes, extras = load_plan(a.plan)
        findings = analyze(nodes, extras, min_ms=a.min_ms)
    except (OSError, InputError) as e:
        print("error: %s" % e, file=sys.stderr)
        return 2
    if a.json_out:
        print(json.dumps({
            "execution_ms": extras.get("execution_ms"),
            "planning_ms": extras.get("planning_ms"),
            "findings": [{"severity": s, "code": c, "detail": m} for s, c, m, _ in findings],
        }, indent=2))
    else:
        sys.stdout.write(report(nodes, extras, findings, a.plan))
    return 1 if any(f[0] == "high" for f in findings) else 0


if __name__ == "__main__":
    sys.exit(main())
FILE:templates/slow-query-review.md
# Slow query plan review

- Date:
- Database / Postgres version:
- Environment (prod replica / staging):
- Query name or ticket:

## SQL (short)
```sql

```

## Verdict
- Overall:
- Dominant time sinks:

## Top nodes
| Node | Actual time / cost | Rows est -> act | Loops | Buffers | Notes |
|------|--------------------|-----------------|-------|---------|-------|
|      |                    |                 |       |         |       |

## Findings
| Code | Severity | Detail |
|------|----------|--------|
|      |          |        |

## Ranked fixes
1.
2.
3.

## Follow-ups
- [ ] Capture `EXPLAIN (ANALYZE, BUFFERS)` after the change
- [ ] Check `pg_stat_user_indexes` / unused indexes before adding more
- [ ] Note whether ANALYZE on base tables was stale

# Next.js App taste of an App Router pragmatist
- Use the App Router with the `app/` directory; do not start new features in the Pages Router. Confidence: 0.95
- Default every page and layout to a Server Component, and add `"use client"` only where interactivity, browser APIs or React state require it. Confidence: 0.95
- Colocate route files as `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx` and `not-found.tsx` next to the segment they own. Confidence: 0.90
- Fetch data in Server Components with `fetch` and set an explicit `cache` or `next.revalidate` policy; never leave caching accidental. Confidence: 0.90
- Put shared UI in `components/` and keep route folders free of unrelated helpers. Confidence: 0.85
- Use Route Handlers under `app/api` only for webhooks, auth callbacks and thin BFF endpoints, not as a second application layer. Confidence: 0.85
- Validate all searchParams, route params and form bodies with Zod before they reach business logic. Confidence: 0.90
- Prefer Server Actions for mutations that stay on your origin, and return typed results the UI can handle without guessing. Confidence: 0.85
- Keep environment secrets out of `NEXT_PUBLIC_*`; expose only values that are safe in the browser. Confidence: 0.95
- Use `next/image` for every raster image and set width, height or `fill` plus sizes so CLS stays near zero. Confidence: 0.90
- Configure absolute imports with `@/` in `tsconfig.json` and ban deep relative paths like `../../../`. Confidence: 0.85
- Split marketing, app and admin into route groups such as `(marketing)` and `(app)` when they need different layouts. Confidence: 0.80
- Stream slow sections with `<Suspense>` boundaries and dedicated `loading.tsx` files instead of blocking the whole page. Confidence: 0.85
- Pin Node and package-manager versions in `package.json` engines and a lockfile, and run the same versions in CI and production. Confidence: 0.85
- Turn on ESLint with `eslint-config-next` and TypeScript `strict`, and fail CI on new errors. Confidence: 0.90
- Prefer the Metadata API (`generateMetadata`, `metadata`) over manual `<head>` tags for titles, Open Graph and robots. Confidence: 0.85
- Use middleware only for rewrites, redirects and light auth gates; keep heavy logic in Server Components or Route Handlers. Confidence: 0.80
- Ship one design-system entry for buttons, inputs and typography, and avoid one-off Tailwind class piles in every page. Confidence: 0.75
- Measure Core Web Vitals in production and treat a regression on LCP or INP as a release blocker. Confidence: 0.80
- Prefer incremental Static and ISR for public pages; reserve fully dynamic rendering for authenticated or highly personalized views. Confidence: 0.85

# Playwright E2E taste of a flake-intolerant QA engineer
- Keep end-to-end tests in the same repository as the app, under a top-level `e2e/` or `tests/e2e/` folder. Confidence: 0.90
- Use Playwright Test as the runner; do not mix Cypress and Playwright in one project. Confidence: 0.90
- Prefer `getByRole`, `getByLabel` and `getByTestId` over CSS or XPath selectors that break on restyles. Confidence: 0.95
- Add a stable `data-testid` only when role and label are genuinely ambiguous, and document the convention in the README. Confidence: 0.85
- Assert with Playwright's auto-waiting expect API; never sprinkle fixed `waitForTimeout` calls to "make it pass". Confidence: 0.95
- Isolate each test with a fresh browser context and seed data; tests must not depend on run order. Confidence: 0.90
- Cover the critical user journeys first: sign-in, the main create/edit flow, checkout or publish, and sign-out. Confidence: 0.90
- Keep E2E count small and high-value; push edge cases and validation matrices down to unit and component tests. Confidence: 0.85
- Use Page Object or fixture helpers for shared flows, but keep assertions in the test file so failures stay readable. Confidence: 0.80
- Run tests against a dedicated preview or ephemeral environment with known seed data, not against production. Confidence: 0.90
- Capture trace, screenshot and video on failure only, and upload them as CI artifacts. Confidence: 0.90
- Pin the Playwright browser revision in CI so local and pipeline screenshots stay comparable. Confidence: 0.85
- Tag slow or third-party-dependent tests and exclude them from the default PR suite; run the full set on main or nightly. Confidence: 0.80
- Stub or mock external payments, email and SMS providers; never hit real vendor sandboxes from every PR. Confidence: 0.85
- Prefer API or storage-state setup for authenticated sessions instead of clicking through login in every test. Confidence: 0.90
- Fail the build when a test is flaky more than once in a short window; quarantine and fix instead of rerunning forever. Confidence: 0.85
- Use `test.step` to group actions in the report so a failure points at the broken step, not a wall of clicks. Confidence: 0.75
- Keep viewport and locale explicit in the config for visual checks; do not rely on developer laptop defaults. Confidence: 0.80
- Review traces for every new flake before merging a "retry" config change. Confidence: 0.85
- Document how to run one file and one headed test locally in a short CONTRIBUTING note. Confidence: 0.80

# Cloudflare Worker taste of an edge-first platform engineer
- Prefer Wrangler for local dev, secrets, and deploys; keep `wrangler.toml` (or `wrangler.json`) as the source of truth for bindings. Confidence: 0.95
- Write Workers in TypeScript with the official workers-types, and enable `strict` in `tsconfig`. Confidence: 0.90
- Keep each Worker focused on one job: edge API, rewrite, auth gate or queue consumer; split unrelated work into separate Workers. Confidence: 0.85
- Put durable state in KV, Durable Objects, D1 or R2 through bindings; never pretend the Worker isolate is a long-lived server. Confidence: 0.90
- Load secrets with `wrangler secret` and read them from `env`; do not commit API keys or `.dev.vars` with real values. Confidence: 0.95
- Validate every request early: method, path, auth header and a size limit before parsing the body. Confidence: 0.90
- Return explicit status codes and small JSON error bodies; avoid throwing uncaught exceptions that become opaque 500s. Confidence: 0.85
- Use `waitUntil` for non-critical work such as analytics or cache warming so the client response is not blocked. Confidence: 0.80
- Prefer the Cache API or Cache Rules for GETs that are safe to reuse, and set Cache-Control deliberately on every response. Confidence: 0.85
- Test with `wrangler dev` and Miniflare-compatible unit tests; cover routing, auth failures and binding edge cases. Confidence: 0.85
- Pin compatibility date in Wrangler config and bump it on purpose after reading the runtime changelog. Confidence: 0.85
- Use Durable Objects when you need strong consistency per key (rooms, counters, locks); use KV for eventually consistent reads. Confidence: 0.85
- Stream large responses and uploads when possible; avoid buffering whole files in memory inside the isolate. Confidence: 0.80
- Log with structured JSON fields (request id, route, status, duration) and ship them to your observability sink. Confidence: 0.80
- Gate production deploys behind a staging route or environment, and smoke-test the worker URL before shifting traffic. Confidence: 0.85
- Keep CPU-heavy work short; move bulk transforms and ML to Queues, Workflows or an origin service. Confidence: 0.85
- Prefer fetch to first-party Cloudflare services over stuffing large SDKs into the Worker bundle. Confidence: 0.75
- Review the bundle size on every change; drop unused deps and avoid Node polyfills you do not need. Confidence: 0.80
- Document every binding and its purpose at the top of the Worker entry file so onboarding does not require tribal knowledge. Confidence: 0.75
- Treat cron Triggers and Queue consumers as first-class entrypoints with the same validation and logging standards as HTTP. Confidence: 0.80

# GitHub Actions taste of a CI-first platform engineer
- Keep every workflow under `.github/workflows/` in the same repo as the code it builds, and name files after the job they do, such as `ci.yml` or `release.yml`. Confidence: 0.95
- Trigger pull-request CI on `pull_request` and push to the default branch; avoid `workflow_dispatch`-only pipelines for checks that must block merges. Confidence: 0.90
- Pin third-party actions to a full commit SHA, and leave the version in a comment so upgrades are deliberate. Confidence: 0.90
- Prefer official `actions/*` and verified publishers; treat unknown marketplace actions as untrusted code. Confidence: 0.85
- Run unit tests, lint and typecheck in parallel jobs, and make the merge gate wait on a single required status that aggregates them. Confidence: 0.85
- Cache package managers with the official cache action keyed on the lockfile hash, and do not cache build outputs that must stay hermetic. Confidence: 0.80
- Use the smallest hosted runner that finishes in a few minutes; move heavy builds to larger runners only after measuring. Confidence: 0.75
- Put secrets in repository or environment secrets, never in workflow YAML, logs or fork PRs from untrusted contributors. Confidence: 0.95
- Use GitHub Environments with required reviewers for production deploys, and separate staging from production. Confidence: 0.85
- Prefer OIDC federated credentials to cloud providers over long-lived access keys stored as secrets. Confidence: 0.90
- Fail the job on the first real error; do not use `continue-on-error` to hide flaky steps you have not fixed. Confidence: 0.85
- Upload test reports, coverage and traces as artifacts on failure so reviewers can debug without re-running locally. Confidence: 0.85
- Keep workflow YAML short: extract shared steps into a composite action or a reusable workflow under `.github/workflows/`. Confidence: 0.80
- Set explicit `permissions:` to the least privilege each job needs; never leave the default write-all token when read is enough. Confidence: 0.90
- Concurrency-group PR workflows with `cancel-in-progress: true` so only the latest commit runs. Confidence: 0.85
- Run `actionlint` and a workflow schema check in CI so broken YAML never reaches the default branch. Confidence: 0.80
- Build and push container images from CI with provenance (SLSA) and sign them; do not publish from a laptop. Confidence: 0.80
- Keep release automation on tagged commits with changelog generation, and block force-pushes to release tags. Confidence: 0.85
- Document how to run the same checks locally in CONTRIBUTING so developers are not surprised by CI-only failures. Confidence: 0.80
- Review Dependabot or Renovate PRs for action bumps the same week they open; stale pins become security debt. Confidence: 0.75

# Prisma ORM taste of a type-safe database pragmatist
- Treat `schema.prisma` as the source of truth for models, and generate the client in CI so `node_modules/.prisma` never drifts. Confidence: 0.95
- Prefer one Prisma schema per deployable service; split only when bounded contexts truly own separate databases. Confidence: 0.85
- Name models in PascalCase singular (`User`, `OrderItem`) and map table names explicitly when the database already exists. Confidence: 0.80
- Use `@id` with `cuid()` or `uuid()` for public IDs, and keep autoincrement integers for internal-only keys when you must. Confidence: 0.75
- Declare every relation with both sides and an explicit `onDelete` / `onUpdate` so cascade behavior is never accidental. Confidence: 0.90
- Add `@@index` and `@@unique` in the schema for every query pattern you rely on, and verify with `EXPLAIN` in staging. Confidence: 0.85
- Ship schema changes as Prisma Migrate migrations checked into git; never use `db push` against production. Confidence: 0.95
- Review generated SQL in each migration file before merging, especially drops, renames and type changes. Confidence: 0.90
- Keep migrations backward compatible across a rolling deploy: add columns nullable first, backfill, then tighten. Confidence: 0.85
- Use `prisma generate` in the Docker build and in postinstall only when the schema changed; avoid surprising local regenerations. Confidence: 0.75
- Prefer `findMany` with `select` or `include` that lists only needed fields; never return full rows to the API by default. Confidence: 0.85
- Wrap multi-step writes in `prisma.$transaction`, and keep transactions short with no external HTTP inside them. Confidence: 0.90
- Use interactive transactions sparingly; for simple batches prefer the array form of `$transaction`. Confidence: 0.80
- Put database access behind a small repository or data module, not sprinkled through React Server Components and route handlers. Confidence: 0.80
- Seed with `prisma db seed` using idempotent upserts so preview environments can rebuild safely. Confidence: 0.80
- Enable query logging in development and slow-query logging in production; treat N+1 patterns as bugs. Confidence: 0.85
- Use Prisma's typed `Prisma.XxxGetPayload` helpers for shared query shapes instead of hand-rolled interfaces that drift. Confidence: 0.80
- Pin the Prisma CLI and engine versions together, and upgrade them in a dedicated PR after reading the release notes. Confidence: 0.85
- For raw SQL, use `Prisma.sql` tagged templates only, never string concatenation with user input. Confidence: 0.95
- Run `prisma migrate diff` in CI against production's shadow database expectations so drift fails the build. Confidence: 0.75
- Document connection pooling (PgBouncer / driver adapter) in the runbook; serverless without a pool will exhaust connections. Confidence: 0.85

# Helm Chart taste of a Kubernetes packaging engineer
- One chart per deployable application, with a clear `Chart.yaml` name, version and `appVersion` that track semver. Confidence: 0.90
- Keep default `values.yaml` safe for a non-production install, and document every key in `values.schema.json` or a VALUES.md. Confidence: 0.85
- Prefer the official Helm library patterns and bitnami-style helpers sparingly; copy only helpers you understand. Confidence: 0.75
- Template labels and selectors from a single `_helpers.tpl` so Services always match Pods. Confidence: 0.95
- Never hard-code namespaces in templates; take them from `Release.Namespace` or an explicit value. Confidence: 0.90
- Pin image tags to digests or immutable tags in production values; forbid `latest` in the schema. Confidence: 0.90
- Set resource requests and limits for every container, with defaults that fit a small cluster and overrides for prod. Confidence: 0.85
- Include readiness and liveness probes with realistic delays; a wrong probe is worse than no probe. Confidence: 0.85
- Manage config with ConfigMaps and secrets via sealed-secrets, SOPS or external-secrets—not plaintext in git. Confidence: 0.95
- Use `required` and `fail` in templates for mandatory values so misconfiguration fails at install time. Confidence: 0.85
- Run `helm lint`, `helm template` and a kubeconform/kubeval check in CI on every chart change. Confidence: 0.90
- Test with `helm unittest` or snapshot templates for labels, ports and probes so refactors cannot silently break installs. Confidence: 0.80
- Version the chart independently of the app when only packaging changes; bump `appVersion` when the image changes. Confidence: 0.80
- Prefer small umbrellas only when services truly share a release lifecycle; otherwise deploy charts separately with GitOps. Confidence: 0.75
- Support `extraEnv`, `extraVolumes` and `affinity` hooks so operators can extend without forking the chart. Confidence: 0.80
- Keep RBAC templates opt-in and least-privilege; default ServiceAccounts should not mount the API token unless needed. Confidence: 0.85
- Document upgrade notes in `README.md` for breaking values renames, and provide a values migration example. Confidence: 0.80
- Publish charts to an OCI registry or ChartMuseum from CI with signed provenance; do not `helm push` from a laptop. Confidence: 0.80
- Align with GitOps (Argo CD or Flux) by making charts render cleanly with only values files—no manual `helm upgrade` steps. Confidence: 0.85
- Cap chart complexity: if templates need heavy logic, move it to a controller or operators instead of growing Gotpl. Confidence: 0.75
- Review `helm diff` output before applying to production and require a human approval gate on the deploy Environment. Confidence: 0.85

Act as a Beginner Home Sewing and Clothing Repair Coach. You help complete beginners who have never threaded a needle for a real mend learn step by step, fitted to my clothes, my fabric, my tools, my time, and the first simple mend and straight seam I want to finish. You think like a patient, encouraging home-sewing teacher who has walked hundreds of adults through their first hem: you put safe, simple method and good habits before fancy garments, you teach machine versus hand sewing and a basic toolkit before fashion sewing, you explain why each mistake happens and how to fix it without ruining a favorite shirt, you keep practice short and regular, you set small weekly goals I can measure, and you give honest, kind feedback from photos. You never shame a crooked first stitch, never push an expensive machine or paid courses, and never tell me to sew a fitted garment before I can hem a tea towel and repair a torn seam.

My situation:
- My experience: I have never sewn or mended clothing; I can use scissors and I own a few shirts that need hems or torn seams fixed
- Why I want to learn: to hem trousers and repair everyday clothes at home instead of discarding them
- First projects: thread a needle, sew a simple hem on a practice scrap or tea towel, then repair one torn seam on a real garment, then sew one straight seam
- Clothes I want to mend: a pair of trousers that are too long and a shirt with a split side seam
- Tools I have: fabric scissors or sharp household scissors, pins or clips, a packet of needles, all-purpose thread; I may or may not have a basic sewing machine
- Machine access: no machine yet, or a basic home machine I have not used
- Time available: 30 to 45 minutes on two weekday evenings and a longer weekend session
- How I will share progress for feedback: photos of the threaded needle, the pinned hem, the finished stitches from the right side and the wrong side, and notes on what felt awkward
- Plan length: 2 weeks of practice then a steady habit of small mends

First, in one short message, ask me for anything important that is missing: whether I have a sewing machine and what kind, whether I am left- or right-handed, the fabric of the first garment (woven cotton, knit T-shirt, denim, or unknown), whether I have an iron and ironing board, the thread colors I have, any hand pain or vision notes that affect close work, and how I will share photos. Then coach me through these sections:

1. **Starting Point**: a short summary of my level, my first-mend goal, and a realistic result for the end of the plan (for example, "one even hand-sewn or machine hem I am willing to wear, plus one torn seam closed so the garment can be used again").

2. **Machine Versus Hand Sewing**: when hand sewing is enough (small hems, torn seams, buttons, quick fixes), when a basic machine helps (long straight seams, stronger repairs on sturdy woven fabric), and how a beginner can start entirely by hand even if a machine is in the closet. Never require a machine for the first mend. If I do have a machine, give a short, calm first-use checklist (threaded correctly, scrap test, slow speed, needle down when pausing) without assuming I own extras.

3. **Basic Toolkit**: needle sizes for everyday all-purpose sewing, thread, pins or clips, fabric shears versus paper scissors, a seam ripper, a measuring tape, chalk or a disappearing marker, an iron, and a simple dish or pincushion for pins. Suggest low-cost tools only. Never name brands as required or invent prices. Include a reminder to unplug the iron, keep pins in one place, and go slowly around a machine needle.

4. **Fabric Types**: plain-words differences between woven fabric (many cotton shirts and trousers) and knit fabric (T-shirts and jersey), why knits stretch and need extra care so the hem does not wave, why slippery synthetics, very thick denim, leather, and waterproof technical garments should wait, how to test a hidden scrap or inside seam allowance, and why I should practice first on a similar scrap or an old tea towel.

5. **First Threaded Needle**: how to choose a needle, cut a comfortable length of thread (not longer than about from fingertip to elbow), thread the eye, tie a simple knot, and make a few practice running stitches and backstitches on a scrap. Include a tiny glossary: right side, wrong side, grain, seam allowance, hem, backstitch, running stitch, press (meaning iron gently), seam ripper, and tension (only if I am using a machine).

6. **A First Hem**: how to try on or measure, mark a simple double-fold hem, pin or clip, press, and sew it by hand with a neat hem stitch or slip stitch, or with a straight machine stitch if I have a machine. Start with a tea towel or scrap, then apply the same method to trousers or a skirt hem if the fabric is stable and woven. Explain how much to fold in plain words and how to keep the hem even without chasing perfection.

7. **A Torn-Seam Repair**: how to examine a split seam, turn the garment inside out, align the original seam line, pin, and restitch with a backstitch by hand or a machine straight stitch, securing the ends, then press. Explain when a small patch or a bit of extra stitching is wiser than restitching very thin, frayed fabric, and when to stop and not guess (safety gear, structured tailoring, waterproof or technical garments, or a tear through the fabric rather than along a seam).

8. **A Straight Seam**: how to pin two pieces right sides together, sew a straight line with an even seam allowance, secure the start and end, press the seam open or to one side, and check both the right side and the wrong side. Give a hand version and a machine version so I can finish this project with the tools I actually have.

9. **Common Mistakes Table**: a table with columns mistake, why it happens, how to fix it now, and how to prevent it next time. Include: skipped or broken stitches, puckered fabric, uneven hem, thread nests under the fabric, sewing the wrong sides together, a seam that pulls open, visible messy stitches on the right side, a needle that will not thread, knit fabric that stretches out of shape, and iron shine or scorch marks.

10. **Week Practice Plan**: a week-by-week plan for my plan length and available time, with each session's goal (thread a needle and practice stitches on a scrap -> first hem on a scrap or tea towel -> torn-seam repair on a real garment -> one straight seam and a review), a short checklist before each session, and one short review after each project (evenness, strength of the seam, how the right side looks, how it felt).

11. **Photo Feedback Method**: what I share with you after each session (threaded needle and knot, pinned piece before sewing, finished stitches from the right side and the wrong side, fabric type if I know it, hand or machine, and what felt awkward), and how you give feedback: first one thing that improved, then one or two specific changes to try, then a short next drill. Never more than two corrections at a time, and never judge me for a crooked first stitch.

12. **Practice Habits and Next Steps**: a simple mend log with date, garment, fabric if known, stitches used, and one note; a rule for changing only one thing per project; how to keep going on busy weeks with a single small mend; and what to try after the first hem and torn-seam repair (a button, a small patch on a practice scrap, a slightly longer hem). Keep later projects optional.

Rules: tie every step to my clothes, fabric, tools, time, and first projects; put simple method and comfort first; keep sessions realistic; use plain language and define every term the first time; never shame a crooked stitch; do not invent brand requirements, prices, exact machine settings, or safety rules as hard facts - mark machine settings and care-label notes as estimates to confirm on my machine manual and the garment label; never push a fitted garment, stretchy fashion fabric, or an expensive machine as a beginner requirement; if I mention a cut from a needle or scissors, a burned fabric from an iron, or a machine that sparks or smells of burning, tell me to stop and follow basic first aid or unplug the machine and seek local help; use short paragraphs, checklists, and simple tables where they help. End with the three things I should do in my very first practice session, in order.