Interviewing the user
Load adl-spec first.
Talking to the user
Use the ask_user tool if you have it. As a sub-agent without it, end your
turn with exactly one relay block and nothing after it:
ASK_USER
{
"question": "<one focused question, self-contained>",
"choices": ["<option 1>", "<option 2>", "<option 3>"],
"default": "<recommended option>",
"why": "<one line on what the answer changes>"
}
END_ASK_USER
choices and default are optional. The block is JSON: check it with
signal-check --expect ASK_USER before ending the turn (see your agent
file, "Signals"); a proposal or a code snippet the question refers to goes
before the block.
Write the question in the user's language (the orchestrator tells you which)
and code snippets exactly as they will be written, comments and docs in
English. The orchestrator forwards it verbatim and replies with the user's
answer as your next turn. Never guess an answer to a question you asked.
Principles
- One question per turn, preferably a concrete proposal the user can
accept, amend or reject ("I propose these three domains: …").
- Ask about the domain; decide implementation details yourself.
- Challenge the design: cycles, a component every other one depends on,
names hiding two responsibilities, assertions that cannot be checked
statically.
- Never add an artifact or an assertion the user has not confirmed; show the
complete ADL text and get an explicit yes before writing a file.
Order of the interview
- Scope. A whole system, a domain, a subdomain or a component;
greenfield or a change to an existing architecture. First read the
shopping list (
.sources/shopping_lists/<branch>.md), the domain spec
(.sources/spec.yaml) and .sources/as-is/ if they exist, and do not ask what
they answer.
- Artifacts, top-down. System, then domains, then each domain's
subdomains and components, then libraries and services if relevant,
confirming the logical and physical name of each.
- Assertions. Containment first (
CLASSES are only CONTAINED within …),
then dependency rules between siblings, then cross-domain rules; FOREACH
when a rule applies to every artifact of a collection. Say whether each
can become a static fitness function (see adl-fitness); if not, ask
whether to keep it as documentation and record the tooling it needs in
REQUIRES.
- Review. Show each complete file and wait for approval, then write it.
- Component interfaces (not ADL: they go straight into code), one
component at a time: its responsibility in one sentence; its public
operations (name, inputs, output, failure modes); the data types crossing
the boundary; facade (plain public functions) or port (behaviour/Protocol
with pluggable implementations). Get the signatures, in the target
language, approved before writing them with the
adl-scaffold skill.
1---2name: adl-interview3description: Protocol for interviewing the user to build ADL definitions and component interfaces one question at a time, including the ASK_USER relay format used by sub-agents that cannot talk to the user directly. Use when composing or revising .adl files or designing component interfaces with the user.4metadata:5 source: https://skillmd.com/skills/korsmakolnikov/adl-interview6---78# Interviewing the user910Load `adl-spec` first.1112## Talking to the user1314Use the `ask_user` tool if you have it. As a sub-agent without it, end your15turn with **exactly one** relay block and nothing after it:1617```18ASK_USER19{20 "question": "<one focused question, self-contained>",21 "choices": ["<option 1>", "<option 2>", "<option 3>"],22 "default": "<recommended option>",23 "why": "<one line on what the answer changes>"24}25END_ASK_USER26```2728`choices` and `default` are optional. The block is JSON: check it with29`signal-check --expect ASK_USER` before ending the turn (see your agent30file, "Signals"); a proposal or a code snippet the question refers to goes31before the block.3233Write the question in the user's language (the orchestrator tells you which)34and code snippets exactly as they will be written, comments and docs in35English. The orchestrator forwards it verbatim and replies with the user's36answer as your next turn. Never guess an answer to a question you asked.3738## Principles3940* **One question per turn**, preferably a concrete proposal the user can41 accept, amend or reject ("I propose these three domains: …").42* Ask about the **domain**; decide implementation details yourself.43* Challenge the design: cycles, a component every other one depends on,44 names hiding two responsibilities, assertions that cannot be checked45 statically.46* Never add an artifact or an assertion the user has not confirmed; show the47 complete ADL text and get an explicit yes before writing a file.4849## Order of the interview50511. **Scope.** A whole system, a domain, a subdomain or a component;52 greenfield or a change to an existing architecture. First read the53 shopping list (`.sources/shopping_lists/<branch>.md`), the domain spec54 (`.sources/spec.yaml`) and `.sources/as-is/` if they exist, and do not ask what55 they answer.562. **Artifacts, top-down.** System, then domains, then each domain's57 subdomains and components, then libraries and services if relevant,58 confirming the logical and physical name of each.593. **Assertions.** Containment first (`CLASSES are only CONTAINED within …`),60 then dependency rules between siblings, then cross-domain rules; `FOREACH`61 when a rule applies to every artifact of a collection. Say whether each62 can become a static fitness function (see `adl-fitness`); if not, ask63 whether to keep it as documentation and record the tooling it needs in64 `REQUIRES`.654. **Review.** Show each complete file and wait for approval, then write it.665. **Component interfaces** (not ADL: they go straight into code), one67 component at a time: its responsibility in one sentence; its public68 operations (name, inputs, output, failure modes); the data types crossing69 the boundary; facade (plain public functions) or port (behaviour/Protocol70 with pluggable implementations). Get the signatures, in the target71 language, approved before writing them with the `adl-scaffold` skill.