@bendyline/gilde 0.1.38 → 0.1.39

package/data/craftbook-templates/da/data-viz-page/versions/1.0.2/craftbook.json

@@ -0,0 +1,155 @@
+{
+  "id": "data-viz-page",
+  "name": "Data Visualization Explorer",
+  "description": "Build a single interactive chart or data explorer page — bar, line, scatter, or pie — driven by sample or provided data, with controls to filter, switch series, or change the dimension and a tooltip on hover. Scopes the dataset and the question the chart answers first, then the chart type and encodings, then implements a canvas or SVG chart with real interactivity. A chart that does not map data to pixels correctly is worse than a table, so the data and chart-design phases lock the encoding and the axes before any rendering code.\n\nA gallery craftbook generated from an archetype spec. It runs\n`phase → (per-phase gate) → … → evaluate → (loop) → finish`. Each build\nphase that produces a checkable artifact is followed by a **runtime\ngate-checkpoint** — the runtime verifies the artifact and routes with no\nmodel turn, looping back to redo the phase on a miss. The final `evaluate`\nstep holds a static deliverable gate plus a reviewer QA pass. What it adds\nover the generic `build-loop`: a specialist role per phase, a\ndomain-correct ordering, and a concrete per-phase quality bar.\n\nDeliverables marked \"artifact\" land in the project's artifacts drawer (`write_artifact` / `read_artifact`), not the shipped workspace — review output is not product source.\n\nPhases:\n\n1. Data scope (planner) — dataset shape + the question the chart answers → gated on artifact `{{workPath}}/data-scope.md` (markdown-notes)\n2. Chart design (designer) — chart type, encodings, axes, legend, tooltip → gated on artifact `{{workPath}}/chart-design.md` (markdown-notes)\n3. Build (developer) — implement index.html with the interactive chart → gated on `index.html` (html-page)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "data-scope",
+  "triggers": [
+    "data visualization",
+    "interactive chart",
+    "data explorer",
+    "build a chart",
+    "visualize data",
+    "graph page"
+  ],
+  "steps": [
+    {
+      "id": "data-scope",
+      "name": "Data scope",
+      "description": "dataset shape + the question the chart answers",
+      "prompt": "Scope the data and the question. (1) Define the dataset shape (fields, types) and embed a realistic sample array if none is provided. (2) State the ONE question the chart answers (e.g. 'how do sales trend by month?'). (3) Identify the dimension(s) and measure(s) to plot and any aggregation. (4) Decide the interactive controls (filter, series toggle, dimension switch) and the hover tooltip content. (5) Write an acceptance-criteria checklist of 5-8 items, e.g. 'the chart renders from the data', 'axes are labeled with correct scales', 'a hover tooltip shows the underlying value', 'a control filters or switches the view and the chart updates', 'responsive', 'no console errors'. Write to {{workPath}}/data-scope.md and via write_task_note. No chart code yet.\n\nThe deliverable `{{workPath}}/data-scope.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "planner",
+      "advanceWhen": {
+        "file": "{{workPath}}/data-scope.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/data-scope.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/data-scope.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "data-scope",
+        "maxAttempts": 3
+      },
+      "next": "chart-design"
+    },
+    {
+      "id": "chart-design",
+      "name": "Chart design",
+      "description": "chart type, encodings, axes, legend, tooltip",
+      "prompt": "Design the chart precisely. (1) Choose the chart type that fits the question and justify it in one line. (2) Map each variable to a visual channel (x, y, color, size) and define the axis scales and ranges. (3) Specify the legend, gridlines, color palette (hex), and the tooltip layout. (4) Design the control affordances (dropdown/buttons) and the empty/loading state. (5) Self-contained — canvas or inline SVG, no chart-library CDN. Write the visual spec to {{workPath}}/chart-design.md and via write_task_note. No HTML yet.\n\nThe deliverable `{{workPath}}/chart-design.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "designer",
+      "advanceWhen": {
+        "file": "{{workPath}}/chart-design.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/chart-design.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/chart-design.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "chart-design",
+        "maxAttempts": 3
+      },
+      "next": "build"
+    },
+    {
+      "id": "build",
+      "name": "Build",
+      "description": "implement index.html with the interactive chart",
+      "prompt": "Implement index.html with inline CSS/JS to the chart and data scope. (1) Embed the data and compute scales mapping data values to pixel coordinates correctly (mind the inverted y-axis). (2) Render the chart with labeled axes, gridlines, and a legend via canvas or SVG. (3) Implement the hover tooltip showing the underlying value at the cursor's data point. (4) Wire the controls so changing them recomputes and re-renders the chart. (5) Make it responsive; vanilla JS, no CDN. Verify a couple of plotted points sit at the right coordinates. On a loop-back, fix only the named gaps without regressing passing criteria. write_task_note the path and passing criteria.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "index.html",
+        "minBytes": 1,
+        "sniff": "html-complete"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "index.html",
+            "bytes": 800
+          },
+          {
+            "kind": "htmlLint",
+            "file": "index.html"
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkHtmlComplete",
+            "scope": "standard",
+            "inputs": {
+              "file": "index.html"
+            }
+          }
+        ],
+        "onReject": "build",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Evaluate the explorer. Open/render index.html, hover for tooltips, and operate every control. Check EACH criterion from {{workPath}}/data-scope.md and write PASS/FAIL with a reason: does the chart render from the data, are axes labeled with correct scales, does the tooltip show the right underlying value, does a control update the chart, is it responsive, zero console errors? Verify one data point's screen position against its value by hand — a mis-scaled axis is a FAIL, loop back to build.\n\nThen route — this is the whole point of the loop:\n\n- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: \"evaluate\", next: \"finish\" })`.\n- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: \"evaluate\", next: \"build\" })` to loop back. The builder fixes exactly those gaps.\n\nNever route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.",
+      "suggestedRole": "reviewer",
+      "consumes": [
+        {
+          "file": "index.html"
+        }
+      ],
+      "next": "build"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All acceptance criteria met. Stamp a short summary and report DONE.",
+      "prompt": "Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.",
+      "suggestedRole": "developer",
+      "terminal": true
+    }
+  ],
+  "version": "1.0.2",
+  "releasedAt": "2026-08-21T00:00:00Z",
+  "paramSchema": {
+    "type": "object",
+    "properties": {
+      "workPath": {
+        "type": "string",
+        "title": "Working folder",
+        "description": "Per-task working folder in the artifacts drawer. Defaults to this task's own folder so runs never collide; override with a stable name when you deliberately want runs to share files.",
+        "default": "{{task.dir}}"
+      }
+    }
+  },
+  "minGezelVersion": "1.26233"
+}

package/data/craftbook-templates/da/data-viz-page/versions/1.0.2/test.json

@@ -0,0 +1,120 @@
+{
+  "schemaVersion": 1,
+  "title": "Source-grounded data visualization page",
+  "objective": "Measure whether the data-viz-page craftbook scopes a chart and builds a self-contained HTML visualization from seeded metrics.",
+  "tags": [
+    "html-page"
+  ],
+  "prompt": "In the `Data Viz Page Eval` project, read `source/metrics.csv` and build `index.html`: a responsive one-page visualization of weekly conversion rate by region. Include a chart using inline SVG or canvas, a legend for North/South/West, a short insight summary grounded in the data, and hover/click affordance text or tooltip behavior. Inline CSS/JS only, no external assets.",
+  "setup": {
+    "projectName": "Data Viz Page Eval",
+    "about": "Self-contained eval project for data-viz-page. Source metrics are in workspace/source/metrics.csv and the deliverable is workspace/index.html.",
+    "missionObjectives": "Build a self-contained chart page from the seeded conversion-rate data with grounded summary and visible chart/legend behavior.",
+    "files": [
+      {
+        "path": "source/metrics.csv",
+        "content": "week,region,conversion_rate\n2026-W01,North,0.41\n2026-W01,South,0.34\n2026-W01,West,0.29\n2026-W02,North,0.45\n2026-W02,South,0.36\n2026-W02,West,0.31\n2026-W03,North,0.53\n2026-W03,South,0.39\n2026-W03,West,0.35\n2026-W04,North,0.51\n2026-W04,South,0.47\n2026-W04,West,0.38\n"
+      }
+    ],
+    "worker": {
+      "name": "Daan",
+      "role": "Developer"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "index.html is a complete chart page grounded in the seeded regional conversion data.",
+    "deliverables": [
+      {
+        "path": "index.html",
+        "kind": "html-page",
+        "minBytes": 3400,
+        "checks": [
+          {
+            "kind": "cssMinBytes",
+            "bytes": 700,
+            "file": "index.html"
+          },
+          {
+            "kind": "jsParses",
+            "file": "index.html"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "svg|canvas",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "North",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "South",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "West",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "conversion",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "legend|tooltip|hover",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "0\\.53|53%|0\\.47|47%",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "index.html",
+      "kind": "html"
+    },
+    "axes": [
+      {
+        "name": "structure",
+        "description": "Layout and hierarchy fit the content; sections are scannable and coherent."
+      },
+      {
+        "name": "grounding",
+        "description": "Seeded source content is used faithfully — no invented facts or dropped requirements."
+      },
+      {
+        "name": "interactivity",
+        "description": "Controls and states the page claims to offer actually work."
+      },
+      {
+        "name": "polish",
+        "description": "Styling is intentional and responsive rather than unstyled or broken."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "data grounding",
+    "chart semantics",
+    "interactive HTML"
+  ]
+}

package/data/craftbook-templates/da/dataset-clean/versions/1.2.3/craftbook.json

@@ -0,0 +1,113 @@
+{
+  "id": "dataset-clean",
+  "name": "Clean a Dataset",
+  "description": "Profile, clean, and validate a messy CSV/TSV/JSON dataset into an analysis-ready table. Profiles the raw data FIRST (row/column counts, types, null rates, duplicates, outliers, encoding) so cleaning decisions are evidence-based, then applies deterministic transforms (dedup, type coercion, null handling, whitespace/case normalization, value standardization), then validates the cleaned output against the same profile so nothing was silently dropped or corrupted. Use this for data wrangling, tidying, deduplication, normalizing dirty spreadsheets, and prepping raw exports for charts or modeling.\n\nA gallery craftbook generated from an archetype spec. It runs\n`phase → (per-phase gate) → … → evaluate → (loop) → finish`. Each build\nphase that produces a checkable artifact is followed by a **runtime\ngate-checkpoint** — the runtime verifies the artifact and routes with no\nmodel turn, looping back to redo the phase on a miss. The final `evaluate`\nstep holds a static deliverable gate plus a reviewer QA pass. What it adds\nover the generic `build-loop`: a specialist role per phase, a\ndomain-correct ordering, and a concrete per-phase quality bar.\n\nDeliverables marked \"artifact\" land in the project's artifacts drawer (`write_artifact` / `read_artifact`), not the shipped workspace — review output is not product source.\n\nPhases:\n\n1. Profile the raw data (data-analyst) — measure the data's shape, types, and defects before touching it → gated on artifact `{{workPath}}/profile.md` (markdown-notes)\n2. Clean the data (developer) — apply the planned deterministic transforms and emit the cleaned file → gated on `data/clean.csv` (data-file)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "profile",
+  "triggers": [
+    "clean this dataset",
+    "tidy a csv",
+    "deduplicate data",
+    "fix dirty data",
+    "prep data for analysis"
+  ],
+  "steps": [
+    {
+      "id": "profile",
+      "name": "Profile the raw data",
+      "description": "measure the data's shape, types, and defects before touching it",
+      "prompt": "Load the raw dataset and PROFILE it before deciding any fix. Step 1: report row count, column count, and the delimiter/encoding. Step 2: for EACH column report inferred type, % null/blank, # distinct values, and 3 sample values. Step 3: count exact-duplicate rows and flag candidate key columns. Step 4: list concrete defects you observe — mixed types in a column, inconsistent casing ('USA' vs 'usa'), stray whitespace, mojibake/encoding issues, impossible values (negative ages, dates in the future), and outliers (values > 3 stdev). Step 5: turn each defect into a planned, deterministic fix and write an acceptance-criteria checklist (e.g. 'no exact-duplicate rows', 'date column parses as ISO-8601', 'no nulls in key columns', 'cleaned row count >= 95% of raw unless dupes explain the drop'). Call write_task_note with the profile table + defects + fixes + checklist, and also write the same content to {{workPath}}/profile.md. No cleaning code yet.\n\nThe deliverable `{{workPath}}/profile.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "data-analyst",
+      "advanceWhen": {
+        "file": "{{workPath}}/profile.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/profile.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/profile.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "profile",
+        "maxAttempts": 3
+      },
+      "next": "clean"
+    },
+    {
+      "id": "clean",
+      "name": "Clean the data",
+      "description": "apply the planned deterministic transforms and emit the cleaned file",
+      "prompt": "Apply EXACTLY the fixes the profile planned — no new undocumented transforms. Step 1: read the raw file with the correct encoding/delimiter. Step 2: in order, drop exact duplicates, coerce each column to its target type, normalize whitespace and casing, standardize known value variants to a canonical form, and handle nulls per the plan (impute, drop, or leave with a reason). Step 3: keep a running tally of rows-in vs rows-out and WHY any row was dropped. Step 4: write the cleaned dataset to data/clean.csv with a header row and consistent quoting. Step 5: call write_task_note with the path, the rows-in/rows-out delta, and which checklist items the output now satisfies. Do not lose columns the profile expected to keep.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "data/clean.csv",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "data/clean.csv",
+            "bytes": 120
+          },
+          {
+            "kind": "sniff",
+            "file": "data/clean.csv",
+            "sniff": "data-table"
+          }
+        ],
+        "onReject": "clean",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Validate that data/clean.csv is genuinely analysis-ready by re-profiling it. Step 1: confirm it parses as CSV, has a header row, and zero exact-duplicate rows. Step 2: confirm the key column(s) have no nulls and every column holds its declared type. Step 3: reconcile the row count — raw rows minus documented duplicates must equal the cleaned row count, and no column was dropped. Step 4: re-measure at least two of these numbers yourself rather than trusting the build note. Step 5: spot-check 5 rows against the raw source to confirm values were transformed, not corrupted. Write PASS/FAIL per acceptance criterion from the profile note; any FAIL loops back to clean.\n\nThen route — this is the whole point of the loop:\n\n- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: \"evaluate\", next: \"finish\" })`.\n- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: \"evaluate\", next: \"clean\" })` to loop back. The builder fixes exactly those gaps.\n\nNever route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.",
+      "suggestedRole": "reviewer",
+      "consumes": [
+        {
+          "file": "data/clean.csv"
+        }
+      ],
+      "next": "clean"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All acceptance criteria met. Stamp a short summary and report DONE.",
+      "prompt": "Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.",
+      "suggestedRole": "developer",
+      "terminal": true
+    }
+  ],
+  "version": "1.2.3",
+  "releasedAt": "2026-08-21T00:00:00Z",
+  "paramSchema": {
+    "type": "object",
+    "properties": {
+      "workPath": {
+        "type": "string",
+        "title": "Working folder",
+        "description": "Per-task working folder in the artifacts drawer. Defaults to this task's own folder so runs never collide; override with a stable name when you deliberately want runs to share files.",
+        "default": "{{task.dir}}"
+      }
+    }
+  },
+  "minGezelVersion": "1.26233"
+}

package/data/craftbook-templates/da/dataset-clean/versions/1.2.3/test.json

@@ -0,0 +1,98 @@
+{
+  "schemaVersion": 1,
+  "title": "Messy CSV cleanup",
+  "objective": "Exercise the data-cleaning class with messy CSV fixtures, dedupe rules, date normalization, and deterministic JSON output.",
+  "tags": [
+    "html-page"
+  ],
+  "prompt": "Can you biuld us a little page for this? The content notes are in source/page-content.md. Save it as index.html — one file, nothing fancy needed on our end.",
+  "setup": {
+    "projectName": "Clean a Dataset Eval",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# Clean a Dataset Eval Brief\n\nClient: Boreal Desk, a home-office accessories company.\nAudience: operations leads who need an artifact they can use this week.\n\nFixed source facts for grounding:\n- The returns desk pilot covered 18 SKUs.\n- Median first response improved from 18 hours to 6 hours.\n- Preventable refund leakage fell from 14.2% to 8.9%.\n- The top unresolved complaint is status silence after photo submission.\n- Required next actions are automated status emails, barcode-exception training, and a weekly Finance exception export.\n\nUse these facts when the task asks for prose, analysis, copy, UI content, or test data. Do not use live web services, real credentials, or current outside data.\n\nCraftbook under test: dataset-clean - Clean a Dataset.\n"
+      },
+      {
+        "path": "source/page-content.md",
+        "content": "# Boreal Desk Support Board\n\nBuild content around a support operations board. Required labels: Open issues, Status silence, Response time, Refund leakage, Next action. Required metric text: 18 hours to 6 hours and 14.2% to 8.9%.\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "role": "Developer"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "The hand-authored data-wrangle grader validates parseability, schema, normalization, dedupe, row count, ordering, and golden records.",
+    "deliverables": [
+      {
+        "path": "index.html",
+        "kind": "html-page",
+        "minBytes": 3000,
+        "checks": [
+          {
+            "kind": "cssMinBytes",
+            "bytes": 650,
+            "file": "index.html"
+          },
+          {
+            "kind": "jsParses",
+            "file": "index.html"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "Boreal|Support Board|returns",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "18\\s*hours|6\\s*hours|14\\.2%|8\\.9%",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "index.html",
+            "pattern": "button|input|filter|tab|card|section|nav",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "index.html",
+      "kind": "html"
+    },
+    "axes": [
+      {
+        "name": "structure",
+        "description": "Layout and hierarchy fit the content; sections are scannable and coherent."
+      },
+      {
+        "name": "grounding",
+        "description": "Seeded source content is used faithfully — no invented facts or dropped requirements."
+      },
+      {
+        "name": "interactivity",
+        "description": "Controls and states the page claims to offer actually work."
+      },
+      {
+        "name": "polish",
+        "description": "Styling is intentional and responsive rather than unstyled or broken."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "precision ETL",
+    "fixture-backed grading",
+    "single-gap feedback"
+  ]
+}

package/data/craftbook-templates/db/db-index-tuning/versions/1.0.2/craftbook.json

@@ -0,0 +1,160 @@
+{
+  "id": "db-index-tuning",
+  "name": "Diagnose + Add Database Indexes",
+  "description": "Diagnose slow database queries and add the right indexes — driven by the query plan, not by hunches — then prove the speedup without harming writes. Analyzes FIRST with EXPLAIN/query plans to find the actual full scans and missing indexes, then adds the targeted indexes (right columns, right order, covering where it helps), then a reviewer confirms the plans now use the index and queries are faster. Covers EXPLAIN/query plans, full-table-scan detection, composite index column order, covering indexes, selectivity, and the write-amplification tradeoff.\n\nA gallery craftbook generated from an archetype spec. It runs\n`phase → (per-phase gate) → … → evaluate → (loop) → finish`. Each build\nphase that produces a checkable artifact is followed by a **runtime\ngate-checkpoint** — the runtime verifies the artifact and routes with no\nmodel turn, looping back to redo the phase on a miss. The final `evaluate`\nstep holds a static deliverable gate plus a reviewer QA pass. What it adds\nover the generic `build-loop`: a specialist role per phase, a\ndomain-correct ordering, and a concrete per-phase quality bar.\n\nDeliverables marked \"artifact\" land in the project's artifacts drawer (`write_artifact` / `read_artifact`), not the shipped workspace — review output is not product source.\n\nPhases:\n\n1. Analyze the queries (data-analyst) — use query plans to find scans and missing indexes → gated on artifact `{{workPath}}/analyze.md` (markdown-notes)\n2. Add the indexes (developer) — write the index migration to the analysis → gated on `migrations/add_indexes.sql` (code-module)\n3. Verify the plans (reviewer) — confirm plans use the index and queries are faster → gated on artifact `{{workPath}}/verify.md` (markdown-notes)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "analyze",
+  "triggers": [
+    "add database indexes",
+    "speed up slow queries",
+    "tune database performance",
+    "fix a slow query",
+    "explain plan and index"
+  ],
+  "steps": [
+    {
+      "id": "analyze",
+      "name": "Analyze the queries",
+      "description": "use query plans to find scans and missing indexes",
+      "prompt": "Diagnose with data, not hunches — index by the query plan. Step 1: Identify the slow queries and run EXPLAIN/EXPLAIN ANALYZE on each to capture the actual plan, noting full table scans, expensive sorts, and the rows examined vs returned. Step 2: For each problem query, determine the columns in WHERE/JOIN/ORDER BY that drive the scan and would benefit from an index, and the right COLUMN ORDER for a composite (most selective / equality before range). Step 3: Consider covering indexes where a query reads only a few columns. Step 4: Note the WRITE cost tradeoff so you do not over-index. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'each target query's plan no longer does a full table scan', 'the added index columns/order match the query predicates', 'no redundant/duplicate index is added', 'write-heavy tables are not over-indexed'). `write_task_note` the plans + proposed indexes + checklist and write the same to the produces path.\n\nThe deliverable `{{workPath}}/analyze.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "data-analyst",
+      "advanceWhen": {
+        "file": "{{workPath}}/analyze.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/analyze.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/analyze.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "analyze",
+        "maxAttempts": 3
+      },
+      "next": "change"
+    },
+    {
+      "id": "change",
+      "name": "Add the indexes",
+      "description": "write the index migration to the analysis",
+      "prompt": "Write the index changes to the analysis. Step 1: Author the CREATE INDEX statements (as a migration) with the columns and ORDER the analysis specified — composite order matters. Step 2: Add covering/included columns only where the analysis justified them; avoid duplicating an existing index's prefix. Step 3: Use concurrent/online index creation if the database supports it to avoid locking, and include the down/rollback (DROP INDEX). Step 4: Keep the change minimal — only the indexes the plans demanded, not a scattershot of indexes that bloat writes. Write the migration to the produces path. On a loop-back, adjust only the index the reviewer flagged. `write_task_note` the migration path and which criteria now pass.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "migrations/add_indexes.sql",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "migrations/add_indexes.sql",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "migrations/add_indexes.sql",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "migrations/add_indexes.sql"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "migrations/add_indexes.sql"
+          }
+        ],
+        "onReject": "change",
+        "maxAttempts": 3
+      },
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Verify the plans",
+      "description": "confirm plans use the index and queries are faster",
+      "prompt": "Verify the indexes actually help. Step 1: Re-run EXPLAIN on each target query and confirm the plan now USES the new index (index scan/seek) instead of a full table scan. Step 2: Confirm the query timing improved against the baseline. Step 3: Confirm the index column order matches the predicates and no redundant/duplicate index was created. Step 4: Sanity-check that write-heavy tables were not over-indexed (the tradeoff is acknowledged). Write a verification note with before/after plans and timings to the produces path.\n\nThe deliverable `{{workPath}}/verify.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "reviewer",
+      "advanceWhen": {
+        "file": "{{workPath}}/verify.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "migrations/add_indexes.sql",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "migrations/add_indexes.sql",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "migrations/add_indexes.sql"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "migrations/add_indexes.sql"
+          }
+        ],
+        "onReject": "verify",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Re-run EXPLAIN on the target queries. For EACH acceptance criterion: confirm each query's plan now uses the index (no full scan), confirm timings improved over baseline, confirm the index columns/order match the predicates, and confirm no redundant index and no over-indexing of write-heavy tables. Write PASS/FAIL per criterion; an index the plan does not use is a FAIL.\n\nThen route — this is the whole point of the loop:\n\n- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: \"evaluate\", next: \"finish\" })`.\n- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: \"evaluate\", next: \"change\" })` to loop back. The builder fixes exactly those gaps.\n\nNever route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.",
+      "suggestedRole": "reviewer",
+      "consumes": [
+        {
+          "file": "migrations/add_indexes.sql"
+        }
+      ],
+      "next": "change"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All acceptance criteria met. Stamp a short summary and report DONE.",
+      "prompt": "Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.",
+      "suggestedRole": "developer",
+      "terminal": true
+    }
+  ],
+  "version": "1.0.2",
+  "releasedAt": "2026-08-21T00:00:00Z",
+  "paramSchema": {
+    "type": "object",
+    "properties": {
+      "workPath": {
+        "type": "string",
+        "title": "Working folder",
+        "description": "Per-task working folder in the artifacts drawer. Defaults to this task's own folder so runs never collide; override with a stable name when you deliberately want runs to share files.",
+        "default": "{{task.dir}}"
+      }
+    }
+  },
+  "minGezelVersion": "1.26233"
+}