Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

feat(shape): explain how to read each tool and name things one way

Eren38ab296cbae5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1ed1132..516ae32 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
+### Added
+- Every Shape tool's caption has a **?** that says how to read it: which way the arrows go, what a row means. Diagrams, examples and steps also list how names are written: a role in plain words, a file with its extension, a function with `()`, a field with its owner, a command after `$`, printed text in quotes.
+
+### Changed
+- The Shape writer follows that notation, names diagram actors and boxes by their role with the code name in parentheses, labels arrows with plain verbs, and gives no tool at all for a change nobody would notice from outside.
+
+### Fixed
+- A **?** explanation near the edge of a window or a scrolling panel opens on the side with room instead of being cut off; this also applies to the Settings explanations.
## [0.25.2] - 2026-10-31
### Added
diff --git a/packages/cli/skills/record/SKILL.md b/packages/cli/skills/record/SKILL.md
index 1154b84..d8c04ec 100644
--- a/packages/cli/skills/record/SKILL.md
+++ b/packages/cli/skills/record/SKILL.md
@@ -103,10 +103,16 @@ Tools (at most three, the ones that say the most; never two that tell the same t
or changed command or flag always gets one that runs it.
- `pseudo`: numbered plain-language steps of the new logic, naming the functions and files.
-Tables have no header row. Order them diagram, tables, example, steps. `{ "tools": [] }`
-means nothing worth showing. Skip messages whose commits are only release/version bumps,
-lockfiles or CHANGELOG, or change fewer than 5 lines in total. Write it in the conversation's language; the CLI validates each output and keeps an
-invalid diagram as text.
+Write names the same way in every tool: a role in plain words (`Git`, `cogit`, `Record`), a
+file with its extension (`session.ts`), a function with `()`, a field with its owner
+(`node.commits`), a command after `$`, printed text in quotes. In a diagram, name actors and
+boxes by role with the code name in parentheses (`Queue (shape-queue.ts)`) and label arrows
+with plain verbs. Tables have no header row. Order the tools diagram, tables, example, steps.
+
+`{ "tools": [] }` means nothing worth showing: give it for a change nobody would notice from
+outside (a refactor, a rename). Skip messages whose commits are only release/version bumps,
+lockfiles or CHANGELOG, or change fewer than 5 lines in total. Write it in the conversation's
+language; the CLI validates each output and keeps an invalid diagram as text.
## Branch summary
diff --git a/packages/cli/src/shape.ts b/packages/cli/src/shape.ts
index 9586776..21f2bd7 100644
--- a/packages/cli/src/shape.ts
+++ b/packages/cli/src/shape.ts
@@ -1,5 +1,5 @@
import type { LineageNode, Shape, ShapeInput, ShapeKind, ShapeTool } from "./schema/session.js";
-import { tableRows } from "./view/shape.js";
+import { SHAPE_NOTATION, tableRows } from "./view/shape.js";
/**
* The Shape catalogue (Story 13.6): a Shape sits between a message's Intent
@@ -319,10 +319,13 @@ export function shapePrompt(opts: {
"Rules:",
"- Give at most three tools, the ones that say the most about this change; never two that tell the same thing.",
"- A diagram for a change across two or more files: a sequence diagram when work is handed between actors over time, a flowchart for a path through code.",
- "- A Before / After table when behaviour someone can see changes (a fix, a new default, a rule). A pure refactor takes none.",
+ "- A Before / After table when behaviour someone can see changes (a fix, a new default, a rule).",
+ "- A change nobody would notice from outside (a refactor, a rename, moved code, a wording tweak in a prompt or comment) takes no tool at all: return none.",
"- An Interface table only for what is reached from outside the changed module: a CLI command or flag, an exported function or type other packages use, a config key, a stored schema field, an HTTP route. Never an internal helper, a component prop or a view-model field.",
- "- A new or changed command or flag always gets an example that runs it and shows what it prints, with real values from the diff. Otherwise an example only when one concrete case shows the change faster than steps.",
+ "- A new or changed command or flag always gets an example that runs it and shows what it prints, with real values from the diff; a file path in it must be one the diff touches, never an invented one. Otherwise an example only when one concrete case shows the change faster than steps.",
"- Steps only when the logic itself is the point and no other tool says it.",
+ `- Write names the same way in every tool: ${SHAPE_NOTATION.map((entry) => `${entry.sample} = ${entry.means}`).join("; ")}.`,
+ "- In a diagram, name actors and boxes by their role in plain words; put the code name after it in parentheses, written as above: Queue (shape-queue.ts). Arrow labels are plain verbs: puts it in the queue (enqueueShape()).",
"- Tables have no header row (the map adds one); every line is one row of three cells split by |.",
"- Order the tools: diagram, tables, example, steps. Return none when the change is a small fix not worth a picture.",
`- Name real functions, files and modules from the diff. Never invent a path.`,
diff --git a/packages/cli/src/view/shape.ts b/packages/cli/src/view/shape.ts
index d5d4ed2..ac0ad73 100644
--- a/packages/cli/src/view/shape.ts
+++ b/packages/cli/src/view/shape.ts
@@ -53,3 +53,40 @@ export function tableRows(text: string): [string, string, string][] | undefined
}
return rows;
}
+
+/**
+ * How names are written in every Shape tool, so a reader tells a role from a
+ * file, a function, a field, a command and the text it prints at a glance.
+ * The writer's prompt and the map's "?" read the same list.
+ */
+export const SHAPE_NOTATION: readonly { sample: string; means: string }[] = [
+ { sample: "Git, cogit, Record", means: "a role: a program, a person or a store that acts" },
+ { sample: "session.ts", means: "a file, with its extension" },
+ { sample: "drainShapeQueue()", means: "a function, with ()" },
+ { sample: "node.commits", means: "a field, variable or setting, with its owner and a dot" },
+ { sample: "$ cogit shape", means: "a command you type, after $" },
+ { sample: '"queued ba654e8"', means: "text the program shows, in quotes" },
+];
+
+/** What each tool shows and how to read it, for the "?" beside its caption. */
+export const SHAPE_READING: Readonly<Record<string, string>> = {
+ mermaid:
+ "Follow the arrows from the top. A box is a step; a diamond is a question, and the arrows leaving it are its answers.",
+ sequence:
+ "Each column is an actor, named at the top. Read from top to bottom: each arrow is one actor handing work to another at that moment, and a dashed arrow is a reply.",
+ table:
+ "One row per case: what happens, how it behaved before this change, and how it behaves now.",
+ interface:
+ "One row per thing other code or people use: a command, flag, function, setting or stored field. — means it did not exist before, or is gone now.",
+ example:
+ "One concrete run. The first line is what you do or what happens; each line after → is what you would see.",
+ pseudo: "What the code does now, in order, one step per line.",
+};
+
+/** Tools whose text names roles, files and functions, so their "?" shows the notation. */
+export const NOTATION_KINDS: ReadonlySet<string> = new Set([
+ "mermaid",
+ "sequence",
+ "example",
+ "pseudo",
+]);
diff --git a/packages/cli/test/shape.test.ts b/packages/cli/test/shape.test.ts
index 60eebfa..ed1e0fc 100644
--- a/packages/cli/test/shape.test.ts
+++ b/packages/cli/test/shape.test.ts
@@ -163,6 +163,10 @@ describe("the Shape tool catalogue", () => {
expect(prompt).toContain("A Before / After table when behaviour someone can see changes");
expect(prompt).toContain("A new or changed command or flag always gets an example");
expect(prompt).toContain("Never an internal helper");
+ expect(prompt).toContain("takes no tool at all");
+ expect(prompt).toContain("never an invented one");
+ expect(prompt).toContain("drainShapeQueue() = a function, with ()");
+ expect(prompt).toContain("Arrow labels are plain verbs");
expect(prompt).toContain('"table" (Before / After)');
expect(prompt).toContain('"sequence" (Sequence)');
expect(prompt).toContain('"interface" (Interface)');
diff --git a/packages/template/src/HelpTip.tsx b/packages/template/src/HelpTip.tsx
new file mode 100644
index 0000000..d4c79f6
--- /dev/null
+++ b/packages/template/src/HelpTip.tsx
@@ -0,0 +1,114 @@
+import { type CSSProperties, type ReactNode, useLayoutEffect, useRef, useState } from "react";
+
+/**
+ * A "?" with a plain-language explanation (Story 12.1): it floats over the page
+ * while the pointer rests on the "?" or the keyboard focuses it, so nothing
+ * below it moves; there is nothing to click. Escape closes it. The settings
+ * modal explains each setting with it, and the Shape layer each tool.
+ *
+ * The bubble is placed against the window, not its scrolling parent, so a "?"
+ * near the edge of a modal never has its explanation cut off: it opens below
+ * the "?" when there is room and above it otherwise.
+ */
+export function HelpTip({
+ id,
+ label,
+ children,
+}: {
+ id: string;
+ label: string;
+ children: ReactNode;
+}) {
+ const [hovered, setHovered] = useState(false);
+ const [focused, setFocused] = useState(false);
+ const open = hovered || focused;
+ const detailId = `${id}-details`;
+ const anchor = useRef<HTMLSpanElement>(null);
+ const bubble = useRef<HTMLSpanElement>(null);
+ const [place, setPlace] = useState<CSSProperties | undefined>(undefined);
+ useLayoutEffect(() => {
+ if (!open) {
+ setPlace(undefined);
+ return;
+ }
+ if (anchor.current === null || bubble.current === null) return;
+ setPlace(
+ bubblePlace(
+ anchor.current.getBoundingClientRect(),
+ bubble.current.offsetHeight,
+ window.innerWidth,
+ window.innerHeight,
+ ),
+ );
+ }, [open]);
+ return (
+ <span
+ className="settings-why-wrap"
+ onMouseEnter={() => setHovered(true)}
+ onMouseLeave={() => setHovered(false)}
+ >
+ <span
+ ref={anchor}
+ className="settings-why"
+ // Focusable so the keyboard reaches the explanation too.
+ tabIndex={0}
+ role="img"
+ aria-label={label}
+ aria-describedby={open ? detailId : undefined}
+ onFocus={() => setFocused(true)}
+ onBlur={() => setFocused(false)}
+ onKeyDown={(event) => {
+ if (event.key !== "Escape" || !open) return;
+ // Close the bubble, not the modal around it.
+ event.stopPropagation();
+ setHovered(false);
+ setFocused(false);
+ }}
+ >
+ ?
+ </span>
+ {open ? (
+ <span
+ ref={bubble}
+ className="settings-details"
+ id={detailId}
+ role="tooltip"
+ style={place ?? HIDDEN}
+ >
+ {children}
+ </span>
+ ) : null}
+ </span>
+ );
+}
+
+/** Measured before it is placed, so the first frame never shows it in the wrong spot. */
+const HIDDEN: CSSProperties = { position: "fixed", left: 0, top: 0, visibility: "hidden" };
+
+/** Space kept between the bubble and the window's edges. */
+const EDGE = 8;
+
+/**
+ * Where the bubble goes, fixed to the window: below the "?" when it fits, else
+ * above when that fits, else on the roomier side with its height capped so it
+ * scrolls inside itself. Never past the window's edges.
+ */
+export function bubblePlace(
+ rect: { left: number; top: number; bottom: number },
+ bubbleHeight: number,
+ width: number,
+ height: number,
+): CSSProperties {
+ const left = Math.max(EDGE, Math.min(rect.left - EDGE, width - EDGE - 360));
+ const below = height - rect.bottom - 6 - EDGE;
+ const above = rect.top - 6 - EDGE;
+ if (bubbleHeight <= below || (bubbleHeight > above && below >= above))
+ return { position: "fixed", left, top: rect.bottom + 6, maxHeight: below, overflowY: "auto" };
+ return {
+ position: "fixed",
+ left,
+ bottom: height - rect.top + 6,
+ maxHeight: above,
+ overflowY: "auto",
+ };
+}
diff --git a/packages/template/src/SettingsModal.tsx b/packages/template/src/SettingsModal.tsx
index 7cf6a4d..ae2cf5d 100644
--- a/packages/template/src/SettingsModal.tsx
+++ b/packages/template/src/SettingsModal.tsx
@@ -7,6 +7,7 @@ import {
withDefaults,
} from "../../cli/src/view/settings.js";
import { isLivePage, loadSettings, pageToken, saveSetting } from "./data.js";
+import { HelpTip } from "./HelpTip.js";
/**
* The settings modal (Story 8.13). Every page carries a ⚙ Settings button in
@@ -17,48 +18,12 @@ import { isLivePage, loadSettings, pageToken, saveSetting } from "./data.js";
type SettingValue = PanelSettings[keyof PanelSettings];
-/**
- * The "?" next to a setting's label (Story 12.1): a plain-language answer to
- * "what is this, when do I change it, what does it cost". It floats over the
- * modal while the pointer rests on the "?" or the keyboard focuses it, so
- * nothing below it moves; there is nothing to click. Escape closes it.
- */
+/** The "?" next to a setting's label: what it is, when to change it, what it costs. */
function FieldDetails({ id, field }: { id: string; field: SettingField }) {
- const [hovered, setHovered] = useState(false);
- const [focused, setFocused] = useState(false);
- const open = hovered || focused;
- const detailId = `${id}-details`;
return (
- <span
- className="settings-why-wrap"
- onMouseEnter={() => setHovered(true)}
- onMouseLeave={() => setHovered(false)}
- >
- <span
- className="settings-why"
- // Focusable so the keyboard reaches the explanation too.
- tabIndex={0}
- role="img"
- aria-label={`What does ${field.label} do?`}
- aria-describedby={open ? detailId : undefined}
- onFocus={() => setFocused(true)}
- onBlur={() => setFocused(false)}
- onKeyDown={(event) => {
- if (event.key !== "Escape" || !open) return;
- // Close the bubble, not the modal around it.
- event.stopPropagation();
- setHovered(false);
- setFocused(false);
- }}
- >
- ?
- </span>
- {open ? (
- <span className="settings-details" id={detailId} role="tooltip">
- {field.details}
- </span>
- ) : null}
- </span>
+ <HelpTip id={id} label={`What does ${field.label} do?`}>
+ {field.details}
+ </HelpTip>
);
}
diff --git a/packages/template/src/ShapeModal.tsx b/packages/template/src/ShapeModal.tsx
index e99c990..82650d7 100644
--- a/packages/template/src/ShapeModal.tsx
+++ b/packages/template/src/ShapeModal.tsx
@@ -1,8 +1,16 @@
import { type ReactNode, useEffect, useRef, useState } from "react";
import type { ViewNode } from "../../cli/src/view/model.js";
-import { shapePreview, shapeState, tableRows } from "../../cli/src/view/shape.js";
+import {
+ NOTATION_KINDS,
+ SHAPE_NOTATION,
+ SHAPE_READING,
+ shapePreview,
+ shapeState,
+ tableRows,
+} from "../../cli/src/view/shape.js";
import { DiffView } from "./DiffView.js";
import { isLivePage } from "./data.js";
+import { HelpTip } from "./HelpTip.js";
import { MermaidDiagram } from "./MermaidDiagram.js";
/**
@@ -109,6 +117,33 @@ const TEXT_CAPTION: Record<string, string> = {
interface: "Interface (as written)",
};
+/**
+ * A tool's caption with a "?" that says how to read it; tools that name roles,
+ * files and functions also list how those names are written.
+ */
+function ToolCaption({ id, kind, label }: { id: string; kind: string; label: string }) {
+ const reading = SHAPE_READING[kind];
+ return (
+ <figcaption className="shape-caption">
+ <span>{label}</span>
+ {reading ? (
+ <HelpTip id={`shape-${id}`} label={`How to read the ${label}`}>
+ <span className="shape-reading">{reading}</span>
+ {NOTATION_KINDS.has(kind) ? (
+ <span className="shape-notation">
+ {SHAPE_NOTATION.map((entry) => (
+ <span key={entry.sample} className="shape-notation-row">
+ <code>{entry.sample}</code> {entry.means}
+ </span>
+ ))}
+ </span>
+ ) : null}
+ </HelpTip>
+ ) : null}
+ </figcaption>
+ );
+}
+
/** Tools Mermaid draws. */
const DIAGRAM_KINDS = new Set(["mermaid", "sequence"]);
@@ -178,7 +213,11 @@ function ShapeLayer({
return (
<figure key={key} className="shape-figure">
{renderMermaid(tool.text)}
- <figcaption>{tool.kind === "sequence" ? "Sequence" : "Flowchart"}</figcaption>
+ <ToolCaption
+ id={key}
+ kind={tool.kind}
+ label={tool.kind === "sequence" ? "Sequence" : "Flowchart"}
+ />
</figure>
);
const columns = TABLE_COLUMNS[tool.kind];
@@ -187,13 +226,17 @@ function ShapeLayer({
return (
<figure key={key} className="shape-figure">
<ShapeTable columns={columns} rows={rows} />
- <figcaption>{tool.kind === "interface" ? "Interface" : "Before / After"}</figcaption>
+ <ToolCaption
+ id={key}
+ kind={tool.kind}
+ label={tool.kind === "interface" ? "Interface" : "Before / After"}
+ />
</figure>
);
return (
<figure key={key} className="shape-figure">
<pre className={`shape-source is-${tool.kind}`}>{tool.text}</pre>
- <figcaption>{TEXT_CAPTION[tool.kind] ?? tool.kind}</figcaption>
+ <ToolCaption id={key} kind={tool.kind} label={TEXT_CAPTION[tool.kind] ?? tool.kind} />
</figure>
);
})}
diff --git a/packages/template/src/styles.css b/packages/template/src/styles.css
index 8137309..e5eea30 100644
--- a/packages/template/src/styles.css
+++ b/packages/template/src/styles.css
@@ -2679,6 +2679,37 @@ time {
font-weight: 600;
}
+.shape-caption {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.shape-reading,
+.shape-notation,
+.shape-notation-row {
+ display: block;
+}
+
+.shape-notation {
+ margin-top: 8px;
+ padding-top: 8px;
+ border-top: 1px solid var(--line);
+}
+
+.shape-notation-row + .shape-notation-row {
+ margin-top: 3px;
+}
+
+.shape-caption .settings-details {
+ font-size: 12.5px;
+ line-height: 1.5;
+}
+
+.shape-notation code {
+ font-size: 11px;
+}
+
.shape-figure {
margin: 0 0 16px;
}
diff --git a/packages/template/test/shape-modal.test.tsx b/packages/template/test/shape-modal.test.tsx
index b62e013..adc2ab4 100644
--- a/packages/template/test/shape-modal.test.tsx
+++ b/packages/template/test/shape-modal.test.tsx
@@ -2,6 +2,7 @@ import { createElement } from "react";
import { renderToStaticMarkup } from "react-dom/server";
import { describe, expect, it } from "vitest";
import type { ViewNode } from "../../cli/src/view/model.js";
+import { bubblePlace } from "../src/HelpTip.js";
import { MermaidDiagram, mermaidAvailable } from "../src/MermaidDiagram.js";
import { ShapeLayers } from "../src/ShapeModal.js";
@@ -102,7 +103,9 @@ describe("Intent, Shape and Code", () => {
expect(html).toContain('<th scope="row">Long diff</th><td>runs past the window</td>');
expect(html).toContain("Before / After");
expect(html).toContain("a newer tool");
- expect(html).toContain("<figcaption>timeline</figcaption>");
+ expect(html).toContain("<span>timeline</span>");
+ // A kind this map does not know has no reading to offer.
+ expect(html).not.toContain("How to read the timeline");
});
it("draws a sequence, lays out an Interface table and shows an example", () => {
@@ -116,10 +119,11 @@ describe("Intent, Shape and Code", () => {
commits: [],
},
});
- expect(html).toContain("<figcaption>Sequence</figcaption>");
+ expect(html).toContain("<span>Sequence</span>");
+ expect(html).toContain('aria-label="How to read the Sequence"');
expect(html).toContain('<th scope="col">Item</th>');
- expect(html).toContain("<figcaption>Interface</figcaption>");
- expect(html).toContain("<figcaption>Example</figcaption>");
+ expect(html).toContain("<span>Interface</span>");
+ expect(html).toContain("<span>Example</span>");
expect(html).toContain("→ queued");
});
@@ -154,3 +158,34 @@ describe("the Mermaid diagram", () => {
expect(html).toContain("cogit open");
});
});
+
+describe("the help bubble", () => {
+ it("opens below when it fits, above when only that fits, and caps its height otherwise", () => {
+ const anchor = { left: 100, top: 100, bottom: 118 };
+ expect(bubblePlace(anchor, 200, 1200, 800)).toEqual({
+ position: "fixed",
+ left: 92,
+ top: 124,
+ maxHeight: 668,
+ overflowY: "auto",
+ });
+ const low = { left: 1150, top: 700, bottom: 718 };
+ expect(bubblePlace(low, 200, 1200, 800)).toEqual({
+ position: "fixed",
+ left: 832,
+ bottom: 106,
+ maxHeight: 686,
+ overflowY: "auto",
+ });
+ // Too tall for either side: the roomier one, scrolling inside itself.
+ expect(bubblePlace({ left: 2, top: 240, bottom: 258 }, 400, 400, 493)).toMatchObject({
+ left: 8,
+ bottom: 259,
+ maxHeight: 226,
+ });
+ expect(bubblePlace({ left: 2, top: 200, bottom: 218 }, 400, 400, 493)).toMatchObject({
+ top: 224,
+ maxHeight: 261,
+ });
+ });
+});