From ddabf46bf3853036c7ef27b866a3855390ad33e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Padez?= <andre.padez@gmail.com>
Date: Tue, 25 Aug 2026 04:15:38 +0000
Subject: [PATCH] the first turn asks one question, and gets its suggestion
 from the platform
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

three corrections, all the owner's, all from watching a real first turn.

it asked too much at once. the section listed five things to settle, so the
commander laid out the trigger, the action AND the destination in its
second message. every question must now be answerable with "yes" or "no, do
this instead" — if the reply needs a paragraph, the question was too big.
turns are cheap; a wrong guess armed for a week is not.

it must not raise the destination at all. output goes in the commander's
own directory, by default and without discussion. i had written "beside the
source is often exactly right", which was wrong and was the thing prompting
the question.

and the suggestion has to come from `GET /api/tasks` and the skills index —
what this platform actually has — not from an example in this file. which
it could not have, because the examples WERE the answer: the first-turn
section spelled out nine .m4a files named memo-<date>-<time>, and the shape
section named "fire on a new recording, transcribe it" as the simplest
commander. it read as a commander that understood the job. it was a
commander reading its own documentation back.

those examples are gone or varied. the template was written from one
commander last night and fitted it perfectly, which proves nothing. the
test is the second one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
---
 src/servers/api/command-hq/directory.ts | 71 ++++++++++++++-----------
 1 file changed, 39 insertions(+), 32 deletions(-)

diff --git a/src/servers/api/command-hq/directory.ts b/src/servers/api/command-hq/directory.ts
index 0f668a5b..4e99a216 100644
--- a/src/servers/api/command-hq/directory.ts
+++ b/src/servers/api/command-hq/directory.ts
@@ -107,10 +107,11 @@ export function notifySection(): string[] {
     'curl -X POST "$OFFICER_API_URL/api/notify/_officer/notify" \\',
     '  -H "Authorization: Bearer $OFFICER_API_KEY" -H "Host: $OFFICER_API_HOST" \\',
     '  -H "content-type: application/json" \\',
-    '  -d \'{"code":"officer/core:commander","id":"1","title":"Voice Memos","body":"3 memos filed"}\'',
+    '  -d \'{"code":"officer/core:commander","id":"1","title":"<your name>","body":"<one sentence>"}\'',
     '```',
     '',
-    'That arrives as **Commander: Voice Memos** / *3 memos filed*.',
+    'A commander named Ledgers sending "4 invoices filed" arrives as **Commander: Ledgers** / *4 invoices',
+    'filed*.',
     '',
     'Almost every notification in Officer carries only a code and a number, and the device renders the',
     'words itself — so nothing readable leaves the machine. This one is the exception: `title` and `body`',
@@ -181,10 +182,9 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     'A commander is a trigger, then up to three steps: **act**, **classify**, **dispatch**. Only the trigger',
     'and the ledger are compulsory. The rest are chosen per commander, and most need fewer than all three.',
     '',
-    'The simplest useful one has no classification at all: fire on a new recording, transcribe it, write the',
-    'text beside the original. Trigger, act, dispatch — and at that point the commander is a schedule over a',
-    'task that already exists, which is the right answer rather than a lesser one. Do not invent steps to',
-    'fill the shape.',
+    'The simplest useful one has no classification and no dispatch: fire when something new appears, run one',
+    'task on it, keep the result here. At that point the commander is a schedule over a task the platform',
+    'already has, which is the right answer rather than a lesser one. Do not invent steps to fill the shape.',
     '',
     '**One trigger.** A schedule that asks a single question: what has appeared that I have not handled?',
     'The trigger runs constantly, so it must never need judgement. If deciding whether something happened',
@@ -204,9 +204,9 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     'A crash between doing the work and writing the line costs a repeat; the other order loses the item',
     'silently. Append, never rewrite — two writers cannot corrupt an append.',
     '',
-    'Key it on a HASH of the source, not a name. Names change: a recording gets renamed from a phone, a',
-    'file is moved, and a name-keyed ledger quietly does all of it again. Do not key it on the OUTPUT',
-    'either — outputs move, get filed, get renamed. The source is the only thing that holds still.',
+    'Key it on a HASH of the source, not a name. Names change — renamed on the device that made it, moved,',
+    'tidied — and a name-keyed ledger quietly does all of it again. Do not key it on the OUTPUT either:',
+    'outputs move, get filed, get renamed. The source is the only thing that holds still.',
     '',
     'Two consequences to accept deliberately. The same content under two names is one item, done once. And',
     'deleting an output does not bring it back, because the ledger still says done.',
@@ -215,9 +215,9 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     'those live here, in your own directory. The reference path holds its subject and nothing about how you',
     'are getting on with it.',
     '',
-    'Output is a different thing and goes wherever the job says. Beside the source, with the same name, is',
-    'often exactly right — a transcript next to its recording is the most useful place it could be. That is',
-    'dispatch making a decision, not a rule being broken.',
+    'Output goes in THIS directory, by default and without discussion — the layout below. Somewhere else is',
+    'a dispatch decision, made later and only if the owner asks for it. Do not raise it on the first turn',
+    'and do not put anything of yours in the reference path unless you have been told to.',
     '',
     '**A spawned agent follows a FILE, not a prompt.** Put the rules in `procedures/<something>.md` here and',
     'point the agent at it. When the rule changes you edit one document; a prompt baked into a loop is a',
@@ -263,31 +263,38 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     '## The first turn',
     '',
     "Two things were named before anything was said: this commander's name, and the reference path above.",
-    'That is all anybody has decided. Everything else is settled in conversation, on this turn.',
+    'Everything else is settled in conversation, and it is settled ONE QUESTION AT A TIME.',
     '',
-    '**Look before you ask.** Go and read the reference path first — how many items, what kinds, how they',
-    'are named, how recently they arrive. A first question grounded in what is actually there is worth ten',
-    'generic ones: "there are nine `.m4a` files, newest twenty minutes ago, all named',
-    '`memo-<date>-<time>` — are those what I am watching for?" tells the owner you understand the subject',
-    'and gives them something concrete to correct.',
+    '**Assume the person answering is busy and knows less about this than you do.** Every question should',
+    'be answerable with "yes" or "no, do this instead". If they have to read a paragraph to reply, or choose',
+    'between options you have laid out, the question was too big. Break it up and take more turns. Turns are',
+    'cheap; a wrong guess armed for a week is not.',
+    '',
+    '**Look, then look again, then ask.**',
+    '',
+    '1. Read the reference path. What is in there, what kinds of file, how they are named, how recently they',
+    '   arrive.',
+    '2. Ask the platform what it can already do — `GET /api/tasks` lists every task on this machine, and',
+    '   your skills index names the rest. If one of them plainly fits what you just saw, that is your',
+    '   suggestion. It has to come from what this platform actually has, not from a guess about what would',
+    '   be useful.',
+    '3. Then ask ONE question: when a new one of these appears, should I do <that thing>?',
+    '',
+    'That is the whole of the first turn. Nothing else.',
+    '',
+    '**Do not ask where the output goes.** It goes in this directory — see "Where things go" above, which',
+    'is the same for every commander. Putting it somewhere else is a later decision and usually never comes',
+    'up at all.',
+    '',
+    '**Do not ask about categories, dispatching, or how often to look.** Those are separate steps and most',
+    'commanders never need the first two. They come up later, one at a time, once the action is agreed and',
+    'has actually run.',
     '',
     'The name is a clue, not a specification. It says what the subject is. It never says what to do about',
     'it, and guessing that is how a commander ends up doing something nobody asked for.',
     '',
-    '**One question at a time.** This is a conversation, not a form. Ask, listen, and let the answer change',
-    'what you ask next.',
-    '',
-    'What has to be settled before anything is armed:',
-    '',
-    '- **What counts as a new item.** Which extensions, top level or recursive, anything to ignore.',
-    '- **What happens to one.** The action — or that there is none, and the trigger is the whole job.',
-    '- **Where the result goes.** Beside the source, into `classification/`, somewhere else entirely.',
-    '- **Whether there is classification at all.** Most commanders do not need it. Do not invent it.',
-    '- **How often to look**, and say out loud that the number is provisional until it has run a while.',
-    '',
-    '**Never arm a watcher on this turn.** Arming before the above is agreed is arming a guess, and a wrong',
-    'condition either never fires or fires constantly — either way it is found out days later. Ask, agree,',
-    'then arm.',
+    '**Never arm a watcher on this turn.** Arming before the action is agreed is arming a guess, and a wrong',
+    'condition either never fires or fires constantly — either way it is found out days later.',
     '',
     'When it is settled, REPLACE this section with what was agreed: what this commander watches for, what it',
     'does about it, and which numbers were guesses. The next turn should read the answer, not the questions.',