Load mahou:design first, then mahou:canvas. Then read .mahou/design-with-canvas.md if present.
Design with canvas
design and the skills it loads keep their procedure, branch types, question rules and tree rules.
When the user asks for a fast track, or fast track is already on in the session, load mahou:fast-track after mahou:canvas and before starting, unless it is already in context. It changes some of this skill's engagement rules.
The document is canvas/design.tldr.json in the change's scratch folder. design.md in the same folder keeps the tree, each branch's prose and its mermaid diagrams, updated whenever the canvas changes; the canvas draws from it.
The canvas is the tree
Each top-level branch is an area labelled <n> <title> · <status>.
- Left side: the branch's leaves, in monospace text, with the same marks as
design-tree. The sub-branches follow as a tree under them, ├─ <n.m> <title> <status> with their leaves indented, and a blank line above each sub-branch.
- Right side: the write-up, at the branch level. The branch's own representation and prose come first. Then each sub-branch that has a representation or prose gets a heading,
<n.m> <title> · <status>, with its diagrams and its prose under it. A sub-branch with neither gets no heading.
- Use
design's types for the representations. While a branch is open, draw its diagrams with tldraw shapes, which are easier to change as answers come in. Once the branch settles, replace each diagram with a mermaid shape that holds the source the final document uses. Size the shape to the diagram's own proportions, at one canvas unit per diagram unit. When the shape is wider than the branch's right side, widen every area in that column until the shape fits, so the column keeps one width. Draw a screen as a mockup copied from its prototype.
- Prose is plain paragraphs, all of them the same width, 1160 units, under the representation they describe.
- When a branch's sub-branches make it much taller than the others, lay its sub-branch sections side by side under its leaves.
- A folded branch keeps its area, labelled
<n> <title> · merged into <m>, holding only the leaf that says where its content went.
For a branch whose type has a canvas reference under references/types/, read both the type in design and the canvas reference: draw the canvas as the canvas reference describes, and write design.md and the final documentation in the type's own form. A type with no canvas reference is drawn in its own form. Each canvas reference has the same file name as the type it adapts.
| The branch is about |
design type |
Canvas reference |
| What a component agrees with the rest of the system |
contract.md |
references/types/contract.md |
| How a value moves between components |
data-flow.md |
references/types/data-flow.md |
Lay the branches out in tree order, read down each column and then across.
The opening tree goes on the canvas as the branch areas, each one pending, with no leaves yet. Above the areas, an Agent note says in one line per branch what that branch settles. A branch's opening statement goes on the canvas as its leaves and its prose. The exploration, the shape tree or earlier branches may already show how part of the branch looks. When they do, and a diagram would make that part easier to follow, draw it with tldraw shapes above the prose, in the diagram form of the branch's type, and mark on it the parts that are still undecided, so the unknowns are obvious. When they do not, the opening has leaves and prose only. The branch's first questions go on the canvas in the same step as its opening statement. When a branch settles, draw its representation and prose in its section and ask the user to approve it there.
Questions
Questions go in the open branch, on its right side, under its write-up. The branch's Agent note goes under the questions.
- A question is a violet card: a rectangle with violet border and fill, titled
❓ Q<n> · <title>, then the body, which gives the situation and ends with the question.
- Add a diagram, a table or a mockup to the card when text is not enough. The canvas offers tldraw shapes for a diagram drawn by hand, a monospace text for a table, a mockup, and a
mermaid shape. For example: a diagram of a library's format or of how its parts call each other, next to what the tree settled about it; a table in the summary box when findings compare options, one column per option and one row per point that matters for the decision; a small timeline with real values when the question is about order.
- Follow-ups stay inside the base question's card, one at a time, until the question branch closes. The card holds, top to bottom: the base question and its diagram, a summary box, one Agent note, and the current follow-up as a violet card of its own.
- The summary box, a solid grey rectangle labelled
Summary · Q<n> so far, holds what the question branch has settled and the findings that bear on it. Rewrite it each round; never add a line per answer.
- When the question branch closes, delete the card, update the branch's leaves on the left, and update its write-up.
- Keep two questions open for the user to answer. A question waiting on a spike, a prototype or a lookup does not count toward the two, so there are three while one waits. Open the next question from the frontier as soon as one closes.
- A spike's result goes in the card of the question that asked for it, as
canvas describes. When the question closes, carry the result to every place it affects, such as the write-up of the sub-branch whose leaves the result settled, a question the result raises in another branch, or a new branch the result opens.
- A merged question is one card. Retitle the lower-numbered card, fold the other card's summary into its summary box, and delete the other card.
Messages from the agent
Everything you would say in the chat goes on the canvas: how you read an answer, research results, a spike's progress, status, and requests to approve a branch. Write it as an Agent note: a grey dashed rectangle labelled Agent, in the branch or the question it is about. Keep one Agent note per place and replace its text each round. When a branch is done, delete its note.
Recording
When the tree is complete, stop the canvas and continue with design's Recording section in the chat.
1---2name: design-with-canvas3description: Runs the design skill on a canvas instead of in the chat. The canvas is the design tree, one section per branch with its leaves, its representation and its prose; questions, findings and readings are written on it, and the user answers with sticky notes. The recording at the end stays in the chat. Use when the user wants to design a system on a canvas.4argument-hint: <the settled shape tree, or where to find it>5metadata:6 source: https://skillmd.com/skills/asermax/design-with-canvas7---89Load mahou:design first, then mahou:canvas. Then read `.mahou/design-with-canvas.md` if present.1011# Design with canvas1213`design` and the skills it loads keep their procedure, branch types, question rules and tree rules.1415When the user asks for a fast track, or fast track is already on in the session, load mahou:fast-track after mahou:canvas and before starting, unless it is already in context. It changes some of this skill's engagement rules.1617The document is `canvas/design.tldr.json` in the change's scratch folder. `design.md` in the same folder keeps the tree, each branch's prose and its mermaid diagrams, updated whenever the canvas changes; the canvas draws from it.1819## The canvas is the tree2021Each top-level branch is an `area` labelled `<n> <title> · <status>`.2223- **Left side: the branch's leaves**, in monospace text, with the same marks as `design-tree`. The sub-branches follow as a tree under them, `├─ <n.m> <title> <status>` with their leaves indented, and a blank line above each sub-branch.24- **Right side: the write-up**, at the branch level. The branch's own representation and prose come first. Then each sub-branch that has a representation or prose gets a heading, `<n.m> <title> · <status>`, with its diagrams and its prose under it. A sub-branch with neither gets no heading.25- **Use `design`'s types for the representations.** While a branch is open, draw its diagrams with tldraw shapes, which are easier to change as answers come in. Once the branch settles, replace each diagram with a `mermaid` shape that holds the source the final document uses. Size the shape to the diagram's own proportions, at one canvas unit per diagram unit. When the shape is wider than the branch's right side, widen every area in that column until the shape fits, so the column keeps one width. Draw a screen as a mockup copied from its prototype.26- **Prose is plain paragraphs, all of them the same width**, 1160 units, under the representation they describe.27- When a branch's sub-branches make it much taller than the others, lay its sub-branch sections side by side under its leaves.28- **A folded branch keeps its area**, labelled `<n> <title> · merged into <m>`, holding only the leaf that says where its content went.2930For a branch whose type has a canvas reference under `references/types/`, read both the type in `design` and the canvas reference: draw the canvas as the canvas reference describes, and write `design.md` and the final documentation in the type's own form. A type with no canvas reference is drawn in its own form. Each canvas reference has the same file name as the type it adapts.3132| The branch is about | `design` type | Canvas reference |33|---|---|---|34| What a component agrees with the rest of the system | `contract.md` | `references/types/contract.md` |35| How a value moves between components | `data-flow.md` | `references/types/data-flow.md` |3637Lay the branches out in tree order, read down each column and then across.3839The opening tree goes on the canvas as the branch areas, each one pending, with no leaves yet. Above the areas, an Agent note says in one line per branch what that branch settles. A branch's opening statement goes on the canvas as its leaves and its prose. The exploration, the shape tree or earlier branches may already show how part of the branch looks. When they do, and a diagram would make that part easier to follow, draw it with tldraw shapes above the prose, in the diagram form of the branch's type, and mark on it the parts that are still undecided, so the unknowns are obvious. When they do not, the opening has leaves and prose only. The branch's first questions go on the canvas in the same step as its opening statement. When a branch settles, draw its representation and prose in its section and ask the user to approve it there.4041## Questions4243Questions go in the open branch, on its right side, under its write-up. The branch's Agent note goes under the questions.4445- **A question is a violet card**: a rectangle with violet border and fill, titled `❓ Q<n> · <title>`, then the body, which gives the situation and ends with the question.46- **Add a diagram, a table or a mockup to the card when text is not enough.** The canvas offers tldraw shapes for a diagram drawn by hand, a monospace text for a table, a mockup, and a `mermaid` shape. For example: a diagram of a library's format or of how its parts call each other, next to what the tree settled about it; a table in the summary box when findings compare options, one column per option and one row per point that matters for the decision; a small timeline with real values when the question is about order.47- **Follow-ups stay inside the base question's card**, one at a time, until the question branch closes. The card holds, top to bottom: the base question and its diagram, a summary box, one Agent note, and the current follow-up as a violet card of its own.48- **The summary box**, a solid grey rectangle labelled `Summary · Q<n> so far`, holds what the question branch has settled and the findings that bear on it. Rewrite it each round; never add a line per answer.49- **When the question branch closes**, delete the card, update the branch's leaves on the left, and update its write-up.50- **Keep two questions open for the user to answer.** A question waiting on a spike, a prototype or a lookup does not count toward the two, so there are three while one waits. Open the next question from the frontier as soon as one closes.51- **A spike's result goes in the card of the question that asked for it**, as `canvas` describes. When the question closes, carry the result to every place it affects, such as the write-up of the sub-branch whose leaves the result settled, a question the result raises in another branch, or a new branch the result opens.52- **A merged question is one card.** Retitle the lower-numbered card, fold the other card's summary into its summary box, and delete the other card.5354## Messages from the agent5556Everything you would say in the chat goes on the canvas: how you read an answer, research results, a spike's progress, status, and requests to approve a branch. Write it as an Agent note: a grey dashed rectangle labelled `Agent`, in the branch or the question it is about. Keep one Agent note per place and replace its text each round. When a branch is done, delete its note.5758## Recording5960When the tree is complete, stop the canvas and continue with `design`'s Recording section in the chat.