Load mahou:basics first, then mahou:design-tree and mahou:docs. Then read .mahou/design.md if present. The tree, the rounds, the question format, the facts rule and how answers grow the tree come from design-tree and apply here as written. Diagrams are validated with superpowers:mermaid-validation before they are shown; when that skill is not installed, say so and show the diagram unvalidated.
Design
Takes a definition the user has settled and designs the system that satisfies it: what is stored, how it moves, what rules apply, and whatever else the change needs. The level is system design. What a program needs decided before it can be written, from its package layout to the contract of each part, belongs to mahou:program-architecture. Function signatures, file lists, migrations and test cases belong to the code itself. The output is a settled design tree, each branch carrying its prose and its representation, handed to mahou:write-documentation to be recorded.
Opening
Read the settled shape tree. Do not read code unless the user asks a question that needs it; when they do, a mahou:code-scout keeps the reading out of the conversation.
List what has to be designed, as the tree. The root is "System design", each item is a pending branch, and each item names what must be specified, not how. Order the branches from abstract to concrete so each one builds on the previous, typically data model, then how data moves, then the rules that produce it, then whatever the change adds on top. Do not propose representations yet. When the change contains several independent pieces, for instance two APIs or two features designed in one session, each piece is its own root with its own areas, worked one root at a time.
System design
├─ 1 <area> pending
├─ 2 <area> pending
└─ 3 <area> pending
- Wait for the user's corrections. Drop items that are implementation (a migration, a schema field list, a function), or move them into the item they serve. Absorb items about prior artifacts (an earlier branch, a superseded document) into the design rather than naming them. Defer verification to after the program is designed. Open the first branch in the reply to the approval.
Working a branch
Open one branch at a time, in order. The first opens with the tree's approval. Each later one opens when the user approves the previous branch's rendering.
Pick the type. Check references/types/ for a reference matching the branch (see Types). A reference says how the branch is usually split, what it needs to question and which representation has worked. It is a guide, not a rule. When the case needs a different split, different questions, another format or another diagram, work that out with the user. When no reference matches, propose a split in the opening statement and let the corrections settle it.
State the branch as settled so far. Every decision that explore, the shape tree or an earlier branch already made about this branch goes in as a ✓ leaf, and the prose under the branch states those decisions in simple terms. The prose stands on its own: no references to the current implementation, no comparison with how things work today, no mention of prior artifacts, nothing that belongs to another branch. It may say what the thing is for, not the flows that use it. Ask the user to correct what is wrong and stop. A corrected leaf goes back to ❔.
Ask the frontier. It goes in the reply after the confirmation. The reference lists what the branch needs to question; what is still open among those becomes the frontier. A situation the definition does not mention is a hypothetical and follows the Scope section of design-tree: raised in one question, opened only when the user picks it. Record a deferred situation as a ✓ leaf under the branch, reading "not considered: ". Do not ask about the representation.
Split when asked. When the user wants the parts of a branch reasoned about separately, add a level, one sub-branch per part, and work them one at a time, each with its own prose, frontier and representation.
Render when settled. Once every leaf is ✓, produce the branch's representation in the reference's form when one matches: the diagram, validated, or the prototype reconciled through mahou:prototype. The user asks for a different form when they want one, and when they want to compare, render the candidates side by side. When no reference matches, ask which form before rendering. The prose under the representation is the opening statement extended with the new leaves, not a new draft, and explains what the representation does not show. Numbered steps in prose refer to the diagram's numbers. Show the whole tree with the branch settled and stop. Open the next branch when the user approves.
Types
| The branch is about |
Reference |
| What is stored: new entities, fields, their shape and meaning |
references/types/data-model.md |
| How a value moves between components: who produces it, who carries it, who persists it |
references/types/data-flow.md |
| How a value is derived or a decision is made from an input |
references/types/rules.md |
| What a program is made of: its components, what crosses between them, its inputs and outputs |
references/types/component-architecture.md |
| What a component agrees with the rest of the system: its inputs and their sources, what it exposes, the value it hands on |
references/types/contract.md |
| What the user sees on a screen: placement, states, encodings, interactions |
references/types/ui.md |
A branch that fits none of these is worked out with the user. A type that turns out to generalize beyond this session is a candidate for mahou:learn to add to this table.
Recording
When the tree is complete, the project's docs record it, and mahou:write-documentation owns that. Before handing off:
Existing notes the change touches. List them from what was read during the work, with what each would need. When the set is unknown or incomplete, say so and offer a mahou:docs-scout to find them. The user settles each one: update it, add the minimum and point to the new note, or skip it.
New notes. The change may need one note or several. Propose the split, and the user settles it.
Then run mahou:write-documentation once per note, giving it the tree. Each settled branch already carries its prose and its representation, so drafting is mostly moving that text into the note; write-documentation fits it to the project's charter and templates, which this skill never reads.
What this skill is not
It does not choose endpoints, functions, files or test cases, does not write code, does not commit, and does not write into the docs folder itself. When the user decides that a piece of the change goes straight into a repository, that is their decision and happens outside this skill.
1---2name: design3description: Turns a settled problem definition into a system design. Works a design tree one area at a time, from data model to flows to rules, with the user settling every leaf. Hands the tree to mahou:write-documentation so the project's docs record it. Stays above endpoints, functions and files. Use after shape, before mahou:program-architecture.4---56Load mahou:basics first, then mahou:design-tree and mahou:docs. Then read `.mahou/design.md` if present. The tree, the rounds, the question format, the facts rule and how answers grow the tree come from `design-tree` and apply here as written. Diagrams are validated with superpowers:mermaid-validation before they are shown; when that skill is not installed, say so and show the diagram unvalidated.78# Design910Takes a definition the user has settled and designs the system that satisfies it: what is stored, how it moves, what rules apply, and whatever else the change needs. The level is system design. What a program needs decided before it can be written, from its package layout to the contract of each part, belongs to mahou:program-architecture. Function signatures, file lists, migrations and test cases belong to the code itself. The output is a settled design tree, each branch carrying its prose and its representation, handed to mahou:write-documentation to be recorded.1112## Opening13141. Read the settled shape tree. Do not read code unless the user asks a question that needs it; when they do, a `mahou:code-scout` keeps the reading out of the conversation.15162. List what has to be designed, as the tree. The root is "System design", each item is a pending branch, and each item names what must be specified, not how. Order the branches from abstract to concrete so each one builds on the previous, typically data model, then how data moves, then the rules that produce it, then whatever the change adds on top. Do not propose representations yet. When the change contains several independent pieces, for instance two APIs or two features designed in one session, each piece is its own root with its own areas, worked one root at a time.1718```19System design20├─ 1 <area> pending21├─ 2 <area> pending22└─ 3 <area> pending23```24253. Wait for the user's corrections. Drop items that are implementation (a migration, a schema field list, a function), or move them into the item they serve. Absorb items about prior artifacts (an earlier branch, a superseded document) into the design rather than naming them. Defer verification to after the program is designed. Open the first branch in the reply to the approval.2627## Working a branch2829Open one branch at a time, in order. The first opens with the tree's approval. Each later one opens when the user approves the previous branch's rendering.30311. **Pick the type.** Check `references/types/` for a reference matching the branch (see Types). A reference says how the branch is usually split, what it needs to question and which representation has worked. It is a guide, not a rule. When the case needs a different split, different questions, another format or another diagram, work that out with the user. When no reference matches, propose a split in the opening statement and let the corrections settle it.32332. **State the branch as settled so far.** Every decision that explore, the shape tree or an earlier branch already made about this branch goes in as a ✓ leaf, and the prose under the branch states those decisions in simple terms. The prose stands on its own: no references to the current implementation, no comparison with how things work today, no mention of prior artifacts, nothing that belongs to another branch. It may say what the thing is for, not the flows that use it. Ask the user to correct what is wrong and stop. A corrected leaf goes back to ❔.34353. **Ask the frontier.** It goes in the reply after the confirmation. The reference lists what the branch needs to question; what is still open among those becomes the frontier. A situation the definition does not mention is a hypothetical and follows the Scope section of `design-tree`: raised in one question, opened only when the user picks it. Record a deferred situation as a ✓ leaf under the branch, reading "not considered: <situation>". Do not ask about the representation.36374. **Split when asked.** When the user wants the parts of a branch reasoned about separately, add a level, one sub-branch per part, and work them one at a time, each with its own prose, frontier and representation.38395. **Render when settled.** Once every leaf is ✓, produce the branch's representation in the reference's form when one matches: the diagram, validated, or the prototype reconciled through mahou:prototype. The user asks for a different form when they want one, and when they want to compare, render the candidates side by side. When no reference matches, ask which form before rendering. The prose under the representation is the opening statement extended with the new leaves, not a new draft, and explains what the representation does not show. Numbered steps in prose refer to the diagram's numbers. Show the whole tree with the branch settled and stop. Open the next branch when the user approves.4041### Types4243| The branch is about | Reference |44|---|---|45| What is stored: new entities, fields, their shape and meaning | `references/types/data-model.md` |46| How a value moves between components: who produces it, who carries it, who persists it | `references/types/data-flow.md` |47| How a value is derived or a decision is made from an input | `references/types/rules.md` |48| What a program is made of: its components, what crosses between them, its inputs and outputs | `references/types/component-architecture.md` |49| What a component agrees with the rest of the system: its inputs and their sources, what it exposes, the value it hands on | `references/types/contract.md` |50| What the user sees on a screen: placement, states, encodings, interactions | `references/types/ui.md` |5152A branch that fits none of these is worked out with the user. A type that turns out to generalize beyond this session is a candidate for mahou:learn to add to this table.5354## Recording5556When the tree is complete, the project's docs record it, and mahou:write-documentation owns that. Before handing off:57581. **Existing notes the change touches.** List them from what was read during the work, with what each would need. When the set is unknown or incomplete, say so and offer a `mahou:docs-scout` to find them. The user settles each one: update it, add the minimum and point to the new note, or skip it.59602. **New notes.** The change may need one note or several. Propose the split, and the user settles it.6162Then run mahou:write-documentation once per note, giving it the tree. Each settled branch already carries its prose and its representation, so drafting is mostly moving that text into the note; `write-documentation` fits it to the project's charter and templates, which this skill never reads.6364## What this skill is not6566It does not choose endpoints, functions, files or test cases, does not write code, does not commit, and does not write into the docs folder itself. When the user decides that a piece of the change goes straight into a repository, that is their decision and happens outside this skill.
asermax