asermax Design tree
A design tree is the record of a shared understanding built one question at a time. The user reads the tree, not the transcript. The skill that loads this one says what the root is, what the branches cover and what level the questions stay at.
The tree
The root is one line. Each branch is an area of the definition. Each leaf is one decision, and leaves can group under sub-branches when an area splits into parts the user wants to reason about separately.
Leaves carry their own mark. A branch is settled only when every leaf under it is settled. A branch that has not been opened yet is pending.
<root>
├─ <area> settled
│ ✓ <decision>
│ ✓ <decision>
├─ <area> open
│ ├─ <part> settled
│ │ ✓ <decision>
│ └─ <part> open
│ ✓ <decision>
│ ❔ Q4 <what is undecided>
└─ <area> pending
When the loading skill works one branch at a time, show the whole tree once it is built. Show it again when a branch settles and the next one opens, and once more at the end. Before every other round, show the branch being worked with its leaves and the rest of the tree collapsed to its branch lines and marks. When the whole frontier is worked at once, show the whole tree before every round and once more at the end.
Rounds
The frontier is every question whose prerequisites are settled. Ask the whole frontier in one round, then wait. A question whose answer depends on another question still open in the same round belongs to a later round. When the loading skill works one branch at a time, the frontier is that branch's open leaves.
Number questions across the whole session. Q7 in round two is the seventh question asked, not the seventh of that round.
❓ **Q1** - **<title>**: <body. The situation and what is undecided. No options.>
---
❓ **Q2** - **<title>**: <body>
Ask in plain prose, written straight into the reply. Never use a tool to ask, AskUserQuestion or any other. A tool cannot ask without options, and options are what a question must not carry.
Every question is a decision that changes the outcome if answered differently. Before asking, check that different answers lead to different outcomes, and drop the question when they would not.
State a decision the user already made, in an earlier round or before the tree existed, as a ✓ leaf, and never ask it again. The user corrects a leaf that is wrong; the corrected leaf goes back to ❔ and joins the next frontier.
What a question carries
A question states what is undecided and stops. It does not list the ways it could be answered. Once you write the options, the user chooses among yours instead of thinking about the problem, and the answers they would have found on their own never appear.
The body carries the context the user needs to decide, and every piece of it is required when it exists:
- What the decision is about.
- Which earlier answers bear on it, and how. If Q3 settled that the value is derived at request time, a question about where it is stored says so.
- Which other parts of the system the answer will change, whether they are already in the tree or not.
- What the loading skill's source (a ticket, a document) says about it, when it says anything.
The body carries nothing about which answers exist. Each of these proposes an answer and none belongs in a question:
- A list of candidates, however even: "on the order, on the user, or in a separate table".
- One candidate with a question mark. "Should we store it on the order?" proposes an answer; "where does it live?" does not.
- A default the user did not set: "by default", "typically", "usually", "the standard approach".
- A verdict: "I'd go with", "the obvious choice", "the simplest is", "probably", "it makes sense to", "we should".
- What follows from one particular answer: "if it goes on the order, every read pays for it". Naming that the answer affects reads is context; working out the effect of one answer is a candidate.
- A confirmation, "so it goes on the order?". A decision the user settled is a ✓ leaf, and one they never settled is asked open.
Before sending a round, reread every question, check that the context is complete and cut anything from the second list. If the user does not know how to answer, they will ask.
When the user asks for the options or for your opinion, give the facts and the current state that bear on the choice: what exists, what earlier decisions constrain it, what a candidate would have to satisfy. Enumerate candidates only when they ask for that, evenly, and give a verdict only when they ask for one explicitly, marked as yours.
Scope
A question is about what the definition covers. A situation the definition does not mention is a hypothetical: a value that might be missing, a step that might fail, two requests arriving at once, a feature that might come later. A checklist in the loading skill or in a type reference may name such situations. The checklist says what to look for. It does not make each item a decision to ask.
Never ask a hypothetical as a decision on its own. Raise it once per branch, in a single question that names the situations noticed and asks which of them the user wants to consider now. Not "what happens when X and Y are missing" but "do we consider that X and Y might be missing?". Naming situations is not naming answers. The options rule forbids candidates for a decision, not the subjects a decision could be about.
Each situation the user picks becomes a ❔ leaf in the next frontier. Record each one they defer where the loading skill says, so that it is not raised again.
Facts
Never look up a fact on your own initiative. When a question needs a fact you do not have, say inside the question that you lack that context and offer to search for it. The user decides whether the lookup happens.
When the user asks for a check, run it, then report the result before the next round's tree, labelled by the question it unblocks. A fact about a library, a tool or anything else outside the project goes to a mahou:researcher, with the requirements taken from the branch being worked. A fact about the project's own code or docs goes to a scout. When the result contradicts a claim the user made or a decision already settled, say so in the first sentence.
Answers
Each answer becomes a leaf. Read the answer literally. When it approves the question instead of answering it, state the reading you took so the user can correct it.
An answer can do more than settle a leaf:
- It can open new leaves under the same branch, asked in the next frontier.
- It can reveal an area the tree does not have yet. Add a branch for it, put its open decisions under it as ❔ leaves, and ask them in the next frontier.
- It can show that a branch mixes things the user wants apart. Add a level and split the leaves under the new parts.
- It can invalidate a settled leaf. Change the mark back to ❔ and ask again with the new information.
- It can reopen a settled branch, by adding a leaf under it or widening what it covers. The branch's mark goes back to open, its settled leaves keep their ✓, and the new leaves are asked in the next frontier. There is no separate mark for a reopened branch.
The tree grows during the questioning.
An answer that departs from the source the work came from, such as a ticket or a document, is recorded as a decision with the departure named once.
Ending
The frontier is empty when a round of answers opens no new question. Show the final tree with every leaf marked ✓ and state that it is complete. Ask nothing. What happens after the tree is the loading skill's business.