gilde

← All craftbooks

Data Dictionary

Data and analysisevalv1.0.0released 2026-06-05workflow: build-loop

Document a dataset's schema as a clear, complete data dictionary so others can use it without guessing. Inspects the data FIRST to derive each column's real type, value domain, null rate, units, and relationships from the actual values (not assumptions), then writes a readable dictionary with one entry per column plus dataset-level context. Use this for documenting a schema, building a data dictionary, a column glossary, a table reference, or onboarding docs for a dataset.

Steps

Entry step: inspect. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Inspect the schemadata-analystentry

    derive each column's real type, domain, and relationships from values

    Show working prompt
    Profile the dataset to learn each column's TRUE characteristics from the data itself. Step 1: list every column. Step 2: for each, derive the data type, the value domain (range for numerics, the enumerated set for low-cardinality categoricals, format/pattern for strings like dates or IDs), the null/blank rate, the unit of measure, and an example value. Step 3: infer the likely meaning of each column and flag any whose name is ambiguous. Step 4: identify keys (unique columns), likely foreign keys, and any computed/derived columns. Step 5: write an acceptance-criteria checklist ('one entry per column', 'each entry has type + description + example', 'enumerated columns list their allowed values', 'keys and relationships are documented', 'units are stated where relevant'). Call write_task_note and write the per-column profile + checklist to notes/inspect.md.
  2. Write the dictionarycopywriter

    produce a readable per-column dictionary with dataset context

    Show working prompt
    Write the data dictionary from the inspection profile — only describe what the data actually shows. Step 1: open with a dataset overview: what it is, the grain (one row = ?), the source, and the row/column counts. Step 2: produce a Markdown table with one row per column: Column, Type, Description, Allowed values / range, Nullable, Unit, Example. Step 3: write plain-English descriptions a newcomer understands; expand ambiguous names. Step 4: add a short 'Keys & relationships' section and a 'Notes / caveats' section (quirks, deprecated columns, derived fields). Step 5: ensure every column from the inspection appears. Write the dictionary to data-dictionary.md and call write_task_note with the path and column count. On a loop-back, fix only the named gaps.
  3. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Read data-dictionary.md and cross-check it against notes/inspect.md and the dataset. Verify: there is exactly one entry per column (count them against the data); each entry has a type, a plain description, and an example; enumerated columns list their allowed values; nullability and units are stated where relevant; and keys/relationships are documented. Spot-check 3 columns' types and value domains against the actual data. Write PASS/FAIL per criterion; any FAIL loops back to write.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "write" })` to loop back. The builder fixes exactly those gaps.

Never 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.
  4. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working 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.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license