docs(common): iteratively improved prompts #1926

seefeldb · 2025-10-21T16:34:22Z

Summary by cubic

Adds shopping list patterns (basic, categorized, composed) and updates CommonTools docs to center on bidirectional binding, making recipes simpler and faster to build. Also refreshes ct-select/ct-checkbox demos and introduces a comprehensive PATTERNS.md.

New Features
- Added shopping-list.tsx, shopping-list-categorized.tsx (grouping via derive), and shopping-list-composed.tsx (shared state rendered with ct-render).
- Updated ct-checkbox and ct-select demos to showcase $checked/$value binding, logging, and numeric selections.
- Introduced docs/common/PATTERNS.md with the “prefer bidirectional binding” rule and quick decision guides; expanded COMPONENTS.md, HANDLERS.md, and RECIPES.md to clarify when handlers are needed.
- Improved tutorials and dev workflow tips; added PATTERN_DOCUMENTATION_FEEDBACK.md capturing gaps and proposed fixes.

cubic-dev-ai

5 issues found across 14 files

Prompt for AI agents (all 5 issues)


Understand the root cause of the following 5 issues and fix them.


<file name="docs/common/HANDLERS.md">

<violation number="1" location="docs/common/HANDLERS.md:51">
The example calls `items.key(el)` with the array element, but `Cell.key` expects an array index. Update the example to pass the index so developers don&#39;t copy a non-compiling pattern.</violation>
</file>

<file name="packages/patterns/shopping-list.tsx">

<violation number="1" location="packages/patterns/shopping-list.tsx:57">
Add a stable key prop to the element rendered inside items.map so React can track each shopping list item during updates.</violation>
</file>

<file name="packages/patterns/ct-select.tsx">

<violation number="1" location="packages/patterns/ct-select.tsx:36">
Both selects share the same `selected` state but expose disjoint value sets, so changing the categories select leaves the string select with a value it can&#39;t render. Give the categories example its own state so each select&#39;s value always matches its items.</violation>
</file>

<file name="docs/common/RECIPES.md">

<violation number="1" location="docs/common/RECIPES.md:603">
Numbering jumps backward here, so the ordered list now contains duplicate headings and no longer reads sequentially.</violation>

<violation number="2" location="docs/common/RECIPES.md:920">
This example reintroduces index-based removal even though the new best-practices section just marked index passing as an anti-pattern, so the guidance conflicts within the same page.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

docs/common/HANDLERS.md

packages/patterns/shopping-list.tsx

packages/patterns/ct-select.tsx

docs/common/RECIPES.md

cubic-dev-ai

5 issues found across 13 files

Prompt for AI agents (all 5 issues)


Understand the root cause of the following 5 issues and fix them.


<file name="docs/common/PATTERNS.md">

<violation number="1" location="docs/common/PATTERNS.md:58">
The Level 3 Shopping List Editor example calls `cell(&quot;Uncategorized&quot;)`, but the matching import omits `cell`, so the snippet won’t compile as written.</violation>
</file>

<file name="packages/patterns/shopping-list-categorized.tsx">

<violation number="1" location="packages/patterns/shopping-list-categorized.tsx:48">
Add a stable `key` prop to the `&lt;div&gt;` returned from `categories.map` so React can reconcile the list correctly.</violation>

<violation number="2" location="packages/patterns/shopping-list-categorized.tsx:73">
Provide a unique `key` on each `&lt;ct-checkbox&gt;` rendered inside the item map to keep React’s list reconciliation stable.</violation>
</file>

<file name="packages/patterns/ct-select.tsx">

<violation number="1" location="packages/patterns/ct-select.tsx:36">
The new categories demo reuses the same `$value={selected}` cell as the string-options demo, but the item values differ, so selecting a category (or even the initial default &quot;opt_1&quot;) has no matching option and leaves both selects blank. Please bind the categories example to its own state or align its option values.</violation>
</file>

<file name="docs/common/RECIPES.md">

<violation number="1" location="docs/common/RECIPES.md:300">
Example 1 still instructs removing items by index, contradicting rule 5’s new guidance to prefer item references. Please update this sample to align with the rule.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

docs/common/PATTERNS.md

packages/patterns/shopping-list-categorized.tsx

packages/patterns/ct-select.tsx

docs/common/RECIPES.md

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

cubic-dev-ai

5 issues found across 13 files

Prompt for AI agents (all 5 issues)


Understand the root cause of the following 5 issues and fix them.


<file name="docs/common/PATTERNS.md">

<violation number="1" location="docs/common/PATTERNS.md:100">
The Level 1 example uses a string for the `style` prop on a `&lt;div&gt;`, but JSX expects an object (`CSSProperties`) for HTML elements, so the sample won’t type-check. Please switch to object syntax so the documentation reflects working code.</violation>
</file>

<file name="docs/common/RECIPES.md">

<violation number="1" location="docs/common/RECIPES.md:920">
This example recommends removal by index right after Rule 5 marked index-based handlers as an anti-pattern, so the documentation gives conflicting guidance.</violation>
</file>

<file name="packages/patterns/shopping-list-categorized.tsx">

<violation number="1" location="packages/patterns/shopping-list-categorized.tsx:48">
Each category section rendered from categories.map needs a stable key so React can reconcile updates correctly. Please add a key for the enclosing &lt;div&gt;.</violation>

<violation number="2" location="packages/patterns/shopping-list-categorized.tsx:73">
List entries generated by the inner map also need keys so React can track each checkbox/item reliably when the grouped list changes.</violation>
</file>

<file name="docs/common/COMPONENTS.md">

<violation number="1" location="docs/common/COMPONENTS.md:122">
`ct-checkbox` emits the `ct-change` custom event, so handlers must be attached with `onct-change`. This example’s `onChange` prop will never fire, breaking the documented pattern.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

docs/common/PATTERNS.md

docs/common/RECIPES.md

packages/patterns/shopping-list-categorized.tsx

docs/common/COMPONENTS.md

cubic-dev-ai

No issues found across 2 files

…for arrays in doc

cubic-dev-ai

Reviewed changes from recent commits (found 1 issue).

1 issue found across 4 files

Prompt for AI agents (all 1 issues)


Understand the root cause of the following 1 issues and fix them.


<file name="docs/common/PATTERNS.md">

<violation number="1" location="docs/common/PATTERNS.md:87">
`item` is an `OpaqueRef&lt;ShoppingItem&gt;` in this example, and `OpaqueRef` does not expose an `equals` method. Calling `item.equals(...)` therefore fails to type-check, breaking the pattern sample.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

docs/common/PATTERNS.md

…ut leaving it alone for now

cubic-dev-ai

Reviewed changes from recent commits (found 7 issues).

7 issues found across 8 files

Prompt for AI agents (all 7 issues)


Understand the root cause of the following 7 issues and fix them.


<file name="docs/common/RECIPES.md">

<violation number="1" location="docs/common/RECIPES.md:891">
`currentItems` is now referenced without being defined, so this handler example no longer compiles. Please remove the extra argument and push just the new item.</violation>
</file>

<file name="docs/common/PATTERNS.md">

<violation number="1" location="docs/common/PATTERNS.md:84">
The handler now requires `items: Cell&lt;Array&lt;Cell&lt;ShoppingItem&gt;&gt;&gt;`, but the recipe still provides `items` as `Cell&lt;ShoppingItem[]&gt;`, so this example no longer type-checks. Please keep the handler parameter aligned with the actual recipe input type.</violation>
</file>

<file name="docs/common/COMPONENTS.md">

<violation number="1" location="docs/common/COMPONENTS.md:111">
`items` and `max` are referenced here but never destructured, so this snippet fails to compile. Please include them in the parameter destructuring.</violation>

<violation number="2" location="docs/common/COMPONENTS.md:113">
`item.done` is a cell, so filtering on it counts every item. Use `.get()` so the max check reflects the true done count.</violation>

<violation number="3" location="docs/common/COMPONENTS.md:117">
The `else` branch is left open here, resulting in invalid TypeScript. Add handling logic or remove the `else` so the example compiles.</violation>

<violation number="4" location="docs/common/COMPONENTS.md:121">
`max = 3` is invalid in an object literal—use a property assignment so the example parses.</violation>

<violation number="5" location="docs/common/COMPONENTS.md:149">
`v` is undefined in this scope. Compare against `validatedValue` (or destructure it first) so the ternary works.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

cubic-dev-ai · 2025-10-21T22:57:53Z

docs/common/RECIPES.md

+  const itemName = detail?.message?.trim();
+  if (!itemName) return;
+
+  items.push(currentItems, { title: itemName, done: false, category: "Uncategorized" });


currentItems is now referenced without being defined, so this handler example no longer compiles. Please remove the extra argument and push just the new item.

Prompt for AI agents

Address the following comment on docs/common/RECIPES.md at line 891: <comment>`currentItems` is now referenced without being defined, so this handler example no longer compiles. Please remove the extra argument and push just the new item.</comment> <file context> @@ -911,8 +888,7 @@ const addItem = handler< - const currentItems = items.get(); - items.set([...currentItems, { title: itemName, done: false, category: "Uncategorized" }]); + items.push(currentItems, { title: itemName, done: false, category: "Uncategorized" }); }); </file context>

Suggested change

items.push(currentItems, { title: itemName, done: false, category: "Uncategorized" });

items.push({ title: itemName, done: false, category: "Uncategorized" });

cubic-dev-ai · 2025-10-21T22:57:53Z

docs/common/PATTERNS.md

+
+const removeItem = handler<
+  unknown,
+  { items: Cell<Array<Cell<ShoppingItem>>>; item: Cell<ShoppingItem> }


The handler now requires items: Cell<Array<Cell<ShoppingItem>>>, but the recipe still provides items as Cell<ShoppingItem[]>, so this example no longer type-checks. Please keep the handler parameter aligned with the actual recipe input type.

Prompt for AI agents

Address the following comment on docs/common/PATTERNS.md at line 84: <comment>The handler now requires `items: Cell<Array<Cell<ShoppingItem>>>`, but the recipe still provides `items` as `Cell<ShoppingItem[]>`, so this example no longer type-checks. Please keep the handler parameter aligned with the actual recipe input type.</comment> <file context> @@ -81,10 +81,10 @@ const addItem = handler< const removeItem = handler< unknown, - { items: Cell<ShoppingItem[]>; item: Cell<ShoppingItem> } + { items: Cell<Array<Cell<ShoppingItem>>>; item: Cell<ShoppingItem> } >((_event, { items, item }) => { const currentItems = items.get(); </file context>

Suggested change

{ items: Cell<Array<Cell<ShoppingItem>>>; item: Cell<ShoppingItem> }

{ items: Cell<ShoppingItem[]>; item: Cell<ShoppingItem> }

cubic-dev-ai · 2025-10-21T22:57:53Z

docs/common/COMPONENTS.md

+});
+
+// Show validation status
+{v !== null ?


v is undefined in this scope. Compare against validatedValue (or destructure it first) so the ternary works.

Prompt for AI agents

Address the following comment on docs/common/COMPONENTS.md at line 149: <comment>`v` is undefined in this scope. Compare against `validatedValue` (or destructure it first) so the ternary works.</comment> <file context> @@ -146,11 +146,10 @@ const validatedValue = derive(rawInput, (value) => { -{ifElse( - derive(validatedValue, (v) => v !== null), - ✓ Valid, +{v !== null ? + ✓ Valid : ✗ Must be 3+ letters </file context>

Suggested change

{v !== null ?

{validatedValue !== null ?

cubic-dev-ai · 2025-10-21T22:57:53Z

docs/common/COMPONENTS.md

+  }
+);
+
+<ct-checkbox $checked={item.done} onct-change={toggle({ items, item, max = 3 })} />


max = 3 is invalid in an object literal—use a property assignment so the example parses.

Prompt for AI agents

Address the following comment on docs/common/COMPONENTS.md at line 121: <comment>`max = 3` is invalid in an object literal—use a property assignment so the example parses.</comment> <file context> @@ -108,25 +108,25 @@ The bidirectional binding version is: ); -<ct-checkbox $checked={item.done} onct-change={toggle({ item })} /> +<ct-checkbox $checked={item.done} onct-change={toggle({ items, item, max = 3 })} /> ``` </file context>

Suggested change

<ct-checkbox $checked={item.done} onct-change={toggle({ items, item, max = 3 })} />

<ct-checkbox $checked={item.done} onct-change={toggle({ items, item, max: 3 })} />

cubic-dev-ai · 2025-10-21T22:57:53Z

docs/common/COMPONENTS.md

+
+    if (currentValue || max === undefined || doneCount < max) {
+      item.done.set(!currentValue);
+    } else {


The else branch is left open here, resulting in invalid TypeScript. Add handling logic or remove the else so the example compiles.

Prompt for AI agents

Address the following comment on docs/common/COMPONENTS.md at line 117: <comment>The `else` branch is left open here, resulting in invalid TypeScript. Add handling logic or remove the `else` so the example compiles.</comment> <file context> @@ -108,25 +108,25 @@ The bidirectional binding version is: - trackAnalytics("item_toggled", { done: !currentValue }); + if (currentValue || max === undefined || doneCount < max) { + item.done.set(!currentValue); + } else { } ); </file context>

cubic-dev-ai · 2025-10-21T22:57:53Z

docs/common/COMPONENTS.md

+const toggle = handler(
+  (_event, { item }: { item: Cell<Item>, items: Item[], max: number }) => {
+    const currentValue = item.done.get();
+    const doneCount = items.filter(item => item.done).length;


item.done is a cell, so filtering on it counts every item. Use .get() so the max check reflects the true done count.

Prompt for AI agents

Address the following comment on docs/common/COMPONENTS.md at line 113: <comment>`item.done` is a cell, so filtering on it counts every item. Use `.get()` so the max check reflects the true done count.</comment> <file context> @@ -108,25 +108,25 @@ The bidirectional binding version is: + (_event, { item }: { item: Cell<Item>, items: Item[], max: number }) => { const currentValue = item.done.get(); - item.done.set(!currentValue); + const doneCount = items.filter(item => item.done).length; - // Additional side effects </file context>

Suggested change

const doneCount = items.filter(item => item.done).length;

const doneCount = items.filter(item => item.done.get()).length;

cubic-dev-ai · 2025-10-21T22:57:53Z

docs/common/COMPONENTS.md

+```tsx
+// ✅ CORRECT - Handler needed for side effects
+const toggle = handler(
+  (_event, { item }: { item: Cell<Item>, items: Item[], max: number }) => {


items and max are referenced here but never destructured, so this snippet fails to compile. Please include them in the parameter destructuring.

Prompt for AI agents

Address the following comment on docs/common/COMPONENTS.md at line 111: <comment>`items` and `max` are referenced here but never destructured, so this snippet fails to compile. Please include them in the parameter destructuring.</comment> <file context> @@ -108,25 +108,25 @@ The bidirectional binding version is: // ✅ CORRECT - Handler needed for side effects const toggle = handler( - (_event, { item }: { item: Cell<Item> }) => { + (_event, { item }: { item: Cell<Item>, items: Item[], max: number }) => { const currentValue = item.done.get(); - item.done.set(!currentValue); </file context>

Suggested change

(_event, { item }: { item: Cell<Item>, items: Item[], max: number }) => {

(_event, { item, items, max }: { item: Cell<Item>, items: Item[], max: number }) => {

seefeldb added 7 commits October 20, 2025 13:45

shopping list pattern + feedback

e23d9ec

feedback applied

91d34d5

next round of shopping patterns and feedback

0b17498

improved docs based on last feedback

7a5227a

third round + feedback

19f630a

updated docs based on feedback

09a8d3f

newest version of pattern

d1462d3

seefeldb requested review from bfollington, ellyxir and jakedahn October 21, 2025 16:34

cubic-dev-ai bot reviewed Oct 21, 2025

View reviewed changes

ellyxir added 5 commits October 21, 2025 17:51

use onct-change instead of onchange

3cebc16

style should be object

d430f67

fix deno fmt complaints

823ba86

fix list item numbering

4c7fc78

fix formatting for shopping-list-categorized.tsx

a640bd6

ellyxir had a problem deploying to ci October 21, 2025 18:08 — with GitHub Actions Failure

ellyxir temporarily deployed to ci October 21, 2025 18:08 — with GitHub Actions Inactive

cubic-dev-ai bot reviewed Oct 21, 2025

View reviewed changes

added id for the integration test

ae02360

ellyxir temporarily deployed to ci October 21, 2025 18:36 — with GitHub Actions Inactive

ellyxir and others added 3 commits October 21, 2025 18:47

need to grab index to pass it into key()

77d297d

Update docs/common/PATTERNS.md

93e3f02

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

fix references to findIndex to pass index parameter

6badeac

ellyxir temporarily deployed to ci October 21, 2025 18:55 — with GitHub Actions Inactive

ellyxir temporarily deployed to ci October 21, 2025 19:56 — with GitHub Actions Inactive

cubic-dev-ai bot reviewed Oct 21, 2025

View reviewed changes

fix mentions of onChange to onct-change for example code

99e2783

ellyxir temporarily deployed to ci October 21, 2025 20:10 — with GitHub Actions Inactive

cubic-dev-ai bot reviewed Oct 21, 2025

View reviewed changes

updated removeItem references to use item.equals() rather than index …

34a696d

…for arrays in doc

ellyxir temporarily deployed to ci October 21, 2025 20:31 — with GitHub Actions Inactive

fix css style into objects

7fafbf7

ellyxir temporarily deployed to ci October 21, 2025 20:40 — with GitHub Actions Inactive

cubic-dev-ai bot reviewed Oct 21, 2025

View reviewed changes

docs/common/PATTERNS.md Outdated Show resolved Hide resolved

seefeldb added 4 commits October 21, 2025 15:03

fix various mistakes that crept in

0430b30

fixed a bunch of wrong advice here -- noticing a lot of duplication b…

853ef2c

…ut leaving it alone for now

some minor edits

0784c21

remove extra files from generation process

0147a42

seefeldb temporarily deployed to ci October 21, 2025 22:35 — with GitHub Actions Inactive

seefeldb merged commit a3f192c into main Oct 21, 2025
8 checks passed

seefeldb deleted the exp/shopping-pattern branch October 21, 2025 22:41

cubic-dev-ai bot reviewed Oct 21, 2025

View reviewed changes

	items.push(currentItems, { title: itemName, done: false, category: "Uncategorized" });
	items.push({ title: itemName, done: false, category: "Uncategorized" });

	{ items: Cell<Array<Cell<ShoppingItem>>>; item: Cell<ShoppingItem> }
	{ items: Cell<ShoppingItem[]>; item: Cell<ShoppingItem> }

	<ct-checkbox $checked={item.done} onct-change={toggle({ items, item, max = 3 })} />
	<ct-checkbox $checked={item.done} onct-change={toggle({ items, item, max: 3 })} />

	const doneCount = items.filter(item => item.done).length;
	const doneCount = items.filter(item => item.done.get()).length;

	(_event, { item }: { item: Cell<Item>, items: Item[], max: number }) => {
	(_event, { item, items, max }: { item: Cell<Item>, items: Item[], max: number }) => {

docs(common): iteratively improved prompts #1926

docs(common): iteratively improved prompts #1926

Uh oh!

Conversation

seefeldb commented Oct 21, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by cubic

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

seefeldb commented Oct 21, 2025 •

edited by cubic-dev-ai bot

Loading

cubic-dev-ai bot Oct 21, 2025 •

edited

Loading

cubic-dev-ai bot Oct 21, 2025 •

edited

Loading

cubic-dev-ai bot Oct 21, 2025 •

edited

Loading

cubic-dev-ai bot Oct 21, 2025 •

edited

Loading

cubic-dev-ai bot Oct 21, 2025 •

edited

Loading

cubic-dev-ai bot Oct 21, 2025 •

edited

Loading

cubic-dev-ai bot Oct 21, 2025 •

edited

Loading