From 0e5384f30747213d39407f51d9fa2e4daa98b0f2 Mon Sep 17 00:00:00 2001 From: kaster Date: Wed, 7 Oct 2026 14:00:05 -0300 Subject: [PATCH] fix: render diagrams as text by default and split large ones Mermaid shows up as raw source in terminals, where most learners read Tacit. Diagrams now default to text, fit in 60 columns and about 8 boxes, flow top to bottom, and big ones are split into an overview plus one detail diagram per part. Learners who read in a Mermaid-capable viewer can set diagramStyle: mermaid. --- README.md | 1 + references/learner-profile.md | 1 + references/teaching-method.md | 49 +++++++++++++++++++++++++++++++--- skills/learn/SKILL.md | 2 +- skills/learning-setup/SKILL.md | 2 +- skills/walkthrough/SKILL.md | 6 ++--- 6 files changed, 53 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 4b4b23d..8a6c700 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ A typical flow: | `depth` | `quick` · `standard` · `deep` | `standard` | | `handsOn` | `off` · `light` (rarely, 1–5 lines) · `moderate` | `light` | | `diagrams` | `true` · `false` | `true` | +| `diagramStyle` | `text` (works in any terminal) · `mermaid` (for viewers that render it) | `text` | Your profile lives in `~/.tacit/profile.md` — plain markdown you can read and edit. It never leaves your machine through Tacit. diff --git a/references/learner-profile.md b/references/learner-profile.md index cef7b81..7785403 100644 --- a/references/learner-profile.md +++ b/references/learner-profile.md @@ -14,6 +14,7 @@ version: 1 depth: standard # quick | standard | deep handsOn: light # off | light | moderate diagrams: true +diagramStyle: text # text | mermaid languages: [typescript, sql] updated: 2026-10-06 --- diff --git a/references/teaching-method.md b/references/teaching-method.md index 3c83d4b..4f6a7b3 100644 --- a/references/teaching-method.md +++ b/references/teaching-method.md @@ -37,9 +37,52 @@ Concepts not present in the catalog can still be taught — explain them from yo ## Diagrams -- Use **Mermaid** fenced blocks (`flowchart`, `sequenceDiagram`, `erDiagram`, `classDiagram`). They render on GitHub, VS Code and most markdown viewers. -- When the environment clearly cannot render Mermaid (plain terminal), also include a compact ASCII version. -- Diagram what the learner needs right now: the overall flow at the start, a sequence diagram for a request crossing layers, an ER diagram for schema changes. Never more than one diagram per message. +Most learners read Tacit in a terminal, where Mermaid shows up as raw source. So the default is a **text diagram**, which reads the same everywhere. + +Read `diagramStyle` from the learner profile (default `text`): + +- `text`: draw the diagram with characters inside a ` ```text ` fenced block. +- `mermaid`: use Mermaid fenced blocks (`flowchart`, `sequenceDiagram`, `erDiagram`). Only for learners who read Tacit somewhere that renders it (IDE chat panels, markdown viewers). The size rules below still apply. + +### Fit the screen + +- **At most 60 columns wide** and about **8 boxes**. Terminals are often split or narrow, and wide lines get cut or wrapped. +- **Flow top to bottom**, not left to right: vertical scrolls, horizontal gets cut. +- **Short labels**: names and verbs only. Details go in the text below the diagram. +- Box-drawing characters and arrows (`─ │ ┌ ┐ └ ┘ ├ ▶ ▼`) are fine. Avoid emoji and other wide characters — they break alignment. + +### Split big diagrams + +If the picture doesn't fit those limits, split it: + +1. An **overview** with the main parts as single boxes (e.g. `API`, `Services`, `Database`). +2. One **detail diagram per part**, shown when the walkthrough reaches that part — not all at once. + +For a sequence with more than 4 participants, use a numbered list of steps instead of lanes. + +### Example + +```text +Before + Internet (no login) + │ GET /api/backup-database + ▼ + routes/api.php + │ + ▼ + BackupController::backup + ├─▶ mysqldump + └─▶ git push + +Now + GET /api/backup-database ──▶ 404 Not Found + ▲ + BackupRouteRemovedTest ─────────┘ checks +``` + +### What to draw + +Diagram what the learner needs right now: the overall flow at the start, the path of a request crossing layers, the tables and their relationships for schema changes. Never more than one diagram per message. ## Hands-on diff --git a/skills/learn/SKILL.md b/skills/learn/SKILL.md index 8ee1e9f..3e6a58d 100644 --- a/skills/learn/SKILL.md +++ b/skills/learn/SKILL.md @@ -32,7 +32,7 @@ At most **one** think-first question per slice — pick the concept closest to ` ## 1. Load the learner profile -Read `~/.tacit/profile.md`. If it doesn't exist, use the defaults (`depth: standard`, `handsOn: light`, `diagrams: true`, every concept `unseen`) and continue — don't ask for setup now. +Read `~/.tacit/profile.md`. If it doesn't exist, use the defaults (`depth: standard`, `handsOn: light`, `diagrams: true`, `diagramStyle: text`, every concept `unseen`) and continue — don't ask for setup now. ## 2. Understand the task diff --git a/skills/learning-setup/SKILL.md b/skills/learning-setup/SKILL.md index 6e952fa..5d407d4 100644 --- a/skills/learning-setup/SKILL.md +++ b/skills/learning-setup/SKILL.md @@ -41,7 +41,7 @@ Explain and ask for each, with the default in bold: - **Depth**: `quick` (only essentials) / **`standard`** / `deep` (trade-offs and alternatives) - **Hands-on**: `off` / **`light`** (rarely, 1–5 lines) / `moderate` (small exercises every few files) -- **Diagrams**: **on** / off +- **Diagrams**: **on** / off. If on, ask where they read the agent's replies: a **terminal** (`diagramStyle: text`, default) or somewhere that renders Mermaid, like an IDE chat panel (`diagramStyle: mermaid`). ## 5. Save and confirm diff --git a/skills/walkthrough/SKILL.md b/skills/walkthrough/SKILL.md index d3c0d4d..afb0cef 100644 --- a/skills/walkthrough/SKILL.md +++ b/skills/walkthrough/SKILL.md @@ -17,7 +17,7 @@ Before starting, read these files (paths relative to this skill's directory): ## 1. Load the learner profile -Read `~/.tacit/profile.md`. If it doesn't exist, use the defaults (`depth: standard`, `handsOn: light`, `diagrams: true`, every concept `unseen`) and continue — don't ask for setup now. +Read `~/.tacit/profile.md`. If it doesn't exist, use the defaults (`depth: standard`, `handsOn: light`, `diagrams: true`, `diagramStyle: text`, every concept `unseen`) and continue — don't ask for setup now. ## 2. Resolve the scope @@ -37,7 +37,7 @@ Ignore lockfiles, generated files, build output, binary assets and pure formatti In the first message: 1. One or two sentences on **what was built**, in plain language. -2. A diagram of how the files connect (if `diagrams` is on) — usually a `flowchart` from entry point to storage. +2. A diagram of how the files connect (if `diagrams` is on), from entry point to storage, following the diagram rules in teaching-method.md. If the change is big, show only the overview here and the details as each part comes up. 3. The **reading order**: list the files in dependency order, from foundations to the edges (schema/models → domain/services → API/handlers → UI → tests). Tests can be visited right after the code they cover. 4. Tell them how it works: one file at a time, short questions, and they can say "skip" anytime. @@ -50,7 +50,7 @@ For each file: 1. **Purpose** — what this file is responsible for, in one or two sentences. 2. **Key code** — point to the important parts with short excerpts (≤15 lines) and line references. Don't paste whole files. 3. **Concepts** — identify the concepts the file uses. Match them to the catalog (`../../concepts/INDEX.md`) and read the concept file for any concept you're going to teach. Treat each one according to its profile status (see teaching-method.md). Language-specific idioms count as concepts too. -4. **Connection** — how this file relates to the previous ones and what uses it next. A sequence diagram helps when a request crosses several layers. +4. **Connection** — how this file relates to the previous ones and what uses it next. A diagram of the request path helps when it crosses several layers. 5. **Question** — when a concept is new or shaky, end with **one** question (see question-types.md), plus the skip option. Otherwise, end by asking if they want to continue. Then **stop and wait for the learner's reply.** Never answer your own question, and never cover the next file in the same message.