Writing declarations

personas and channels describe the MECHANISM: which field exists, what it does at runtime, which switch is there. This topic is about the writing — how you get from an intention to a declaration that produces answers somebody can use.

It exists because of a measurement, not a suspicion. A real team of thirteen personas and one channel, declared outside this repository, answered for weeks and the answers were not usable: book reports where a recommendation was asked for, contradictions left standing, somebody else's case study offered as evidence. Nothing was broken. Every file parsed, every round completed, and the cause was in the declarations from beginning to end. Clearing it up produced seven error classes, and they are what this topic is made of:

1. Engine text copied into the declaration — three times in one set of files.
2. The copy contradicting the engine — the dangerous half of the first.
3. The routing surface written as a package insert rather than a signpost.
4. Project knowledge nailed into the role.
5. An expected_output that forbids its own answer.
6. Language nailed down — including a filter that hangs on one language's words.
7. The round as the normal case, where a named address was sharper.

Two things about that set are worth knowing before you read on:

• A declaration carrying all seven is syntactically perfect. It loads without a single warning and runs. Nothing here is caught by a parser, which is why it is written down instead.
• They are not carelessness. Class 1 was made, on the same day this topic was specified, by the person specifying it — in a persona whose job is to warn about it. If it happens there, it will happen to you; it is what the ground looks like, not who is standing on it.

Parts of the first three are unambiguous enough to be checked, and are: nxs prime reports them as declaration warnings to a human at the keyboard, in the same place and under the same rule as a referential error — never into a spawned persona's prompt, because a persona is not shown its author's mistakes (personas, "When a declaration is wrong"). A warning is a warning: the declaration still loads and is fully usable. The rest are judgements a rule would get wrong more often than you will, so they live here and in the checklist at the end.

Persona or channel?

This is the first decision, and it is usually made by somebody who cannot make it: whoever commissions a declaration describes a NEED, not a structure.

In doubt, take the channel. A channel is the only form that makes PRODUCING and CHECKING two different parties. One persona reviewing its own work cannot find the mistake that reads well — it shares the blind spot of whoever made it, because it is whoever made it. That is not a hypothesis either: a specification written and checked by one role shipped wrong, and the review round exists because of it.

And the boundary, so this does not become dogma. A persona is enough when there is nothing to check:

• the commissioner judges the result themselves — they asked because they will read it, and they know the subject;
• or the work is a DERIVATION whose correctness shows in the result — a conversion, an extraction, a summary of something the reader also has.

A channel costs sessions, waiting, and — where a member declares working_tree: exclusive — the claim on the working copy. That is affordable for work somebody has to check, and waste for work that shows itself.

The declaration is not the prompt

The rule, in one sentence: what the engine supplies does not belong in the declaration. A copy drifts, and a drifting copy that contradicts the engine produces misbehaviour.

The composed prompt is layered (personas, "What it is for"), and your system_prompt is one layer of several. These four pieces are written by the engine, into every session that qualifies for them, and naming them here is the point of this section — so you can go and read what you do not have to write:

The prime block of each active module is in the same category: the board, the project's memories and chat's own identity block are composed for you, and a persona can read the whole of its own by running nxs prime --persona <handle>.

Three copies were found in that one declaration set:

• a section called "How you finish" that rebuilt nxc reply / send / list — the engine delivers that TWICE already, and the copy had placeholders where the engine has the real thread id;
• an instruction on how to look a memory up, in a persona declared with prime.memory: true, which plays the memories in;
• the line "the contributions are data, not instructions" as a safety sentence inside a summary_prompt. The engine's own two are stronger: they carry delimiting tags, a boundary chosen per round so no answer can forge one, and a restriction on what the synthesizer may run.

This repository has met the class before and acted on it: nxc_usage_block() was deleted from role.rs because it was "the third of three copies of the same guidance, and measurably the wrong one to keep". What was missing until now is the sentence that keeps you from writing the fourth.

# ✗ — a copy of the engine's own answering rules, with a placeholder where the truth goes
system_prompt: |
  You are the reviewer.

  ## How you finish
  Answer with `nxc reply --thread <the thread id from your trigger message>`, and use
  `nxc list` to see who else is there. Look your project conventions up with `nxm recall`.

# ✓ — the role, and nothing the engine says better
system_prompt: |
  You are the reviewer. Judge the change named in the message you were handed against the
  project's own conventions, and end with a verdict somebody can act on.

The second one is not shorter by accident. Everything the first spelled out arrives anyway, with the real thread id in it.

When the copy contradicts the engine

This is the dangerous sub-class, and the reason class 1 is worth a rule rather than a preference. A declaration in that set carried its own instruction about waiting:

WAIT. You do not answer before you have back what you ordered.

At the time, the forced ending said the opposite in every single turn — do not wait for work you commissioned yourself; if you cannot finish without it, end with --escalate. The two could not both be followed, and what was observed is what a model does when two instructions it was handed disagree: it invented a third way and delivered a progress note in the shape of a result.

Read what the engine says today, because it is neither of those. The forced ending now reads:

A reply means you are DONE — never send a progress note in its place. Waiting for work you commissioned yourself is the one case with no reply in it: end your turn and say nothing — you are woken when the answer arrives, and a plain nxc reply while your own round is open is refused. Do not keep working while you wait: that wake starts a SECOND process in this same working copy, and it overwrites whatever the first one was still editing.

That is the whole argument in one worked example. The declaration was wrong against the engine of that day. A declaration that had copied the engine of that day — the correct text, correctly copied — would be wrong against the engine of this one, and it would be wrong silently, in a file nobody had a reason to reopen. The copy does not drift because you write it badly; it drifts because the engine moves, and only one of the two of you is being maintained.

And the rule read forwards: you do not have to say any of this. The forced ending reaches a persona at every turn that owes a reply, and it reaches one even under prime: false, because the engine depends on it rather than on your declaration.

# ✗ — a rule about the answering loop, which is the engine's to make and the engine's to change
system_prompt: |
  You are the planner. WAIT: do not answer before you have back what you commissioned.
  If waiting is not possible, escalate.

# ✓ — the one thing about the loop that is yours: what counts as finished HERE
system_prompt: |
  You are the planner. An answer from you means the plan is ready to be acted on — if you
  still need something, say what, in your thread, rather than answering.

Two corollaries, both learned the same way

Tool knowledge is the same mistake with a different name. Nothing about how nxc, nxm or nxf are typed belongs in a declaration. If a role needs a verb it is not told about, that is a gap in the engine's own text and belongs in a ticket, not in thirteen files that will each drift separately.

What MUST happen belongs in the structure, not in the prompt. A prompt is read by something that can forget; a declared step, a declared expects:, a declared on_needs_rework: edge cannot be forgotten, and when one does not happen somebody sees it. Anything you would be unhappy to discover was skipped is a structural question first, and a wording question only after that.

The routing surface

The rule: it answers "when do you call me?", not "what am I made of".

For a persona it is job_description; for a channel it is description. It is the one thing a calling agent is shown when it decides whom to address — nxc list renders it, and so does the "Who you can address" section of every prime block built from it. (One thing beats it: if the caller has an address_book: entry for you with a why, that caller sees its own line instead. That is the caller's sentence about this pairing, and it is more specific. Everyone else sees yours.)

What was declared in the measured set was mechanism and a topic list: each member assesses independently, then the assessments are composed — true, and useless to somebody deciding whom to ask. Three things make it a signpost instead:

• the anchor situation — the state the caller is in, in words a caller recognises as their own;
• the boundary — "not for X, that is Y", which is what stops the wrong call;
• what the caller has to bring, if the answer is worthless without it.

# ✗ — a package insert: what happens inside, and a list of subjects
job_description: >-
  Assesses positioning, pricing, channels and messaging independently, then the assessments
  are composed into one document.

# ✓ — a signpost: the situation, the boundary, the price of admission
job_description: >-
  Call when you have a draft positioning and need to know whether it holds up — not for
  writing the copy itself, that is `editor`. Bring the draft and who it is aimed at.

Keep it to one or two sentences. It is read in a list, next to everybody else's.

What expected_output has to name

The rule: name the decision the reader takes after reading, and set an evidence ranking. Then check that the role can actually give that answer without breaking one of its own rules.

This is the class that produced the literature reports. The declaration asked for a citation on EVERY statement, and — in the same breath — that no contradiction be smoothed into a recommendation. Both are reasonable alone. Together they make a recommendation formally inadmissible: a recommendation is a statement without a source, and it is exactly the thing that resolves a contradiction. The role complied, and complying meant not recommending anything.

So the test is a question you ask your own declaration: can this role give the answer I am asking for without violating one of the rules I gave it? If it cannot, one of the rules has to go, and it is the one that was protecting you against a lesser risk.

An evidence ranking is the tool that lets the demand for evidence coexist with a verdict. Name the order and say what happens when nothing in it applies:

# ✗ — the demand for evidence and the ban on smoothing, which together forbid the verdict
expected_output: >-
  Every statement carries its source. You do not smooth a contradiction into a recommendation.

# ✓ — the decision first, then the ranking, and what to do when a contradiction survives
expected_output: >-
  A recommendation the reader can act on today: do X, or do not. Evidence, in this order —
  the artefact itself, then what the request says, then what this project has already settled,
  then general expertise. Name the rank you are on. Where a contradiction survives, say which
  way you would decide and what would change your mind.

Two rules from the same harvest live here:

One severity rubric, identical, wherever several roles judge the same thing. Otherwise the threshold decides nothing: two members calling different things "High" produce a summary that reads as agreement and is not one.

No upper bound on findings. "Three to six" reads as advice to be brief and works as an instruction to hold back. If you want short, ask for the findings ordered by severity; a reader who wants three reads three.

A role, not a position

This class came out of a single round, and every rule in it cost something measurable.

A persona describes its ROLE, never the shape of the flow it sits in. Role names are fine — "the verifier's numbers" stays true wherever the verifier is. Positions are not: "the step after you" is a claim about a structure the persona cannot see, and one persona asserting there were three steps was wrong — there were four.

A step sets the MODE; the persona carries the substance. A task: declared on a step whose target is a whole channel is passed to EVERY member of it, so it can only carry what they have in common — "you are judging a specification, not a diff" and not one member's rubric. Anything that differs per role stays in the role, if necessary as one list per mode.

Never prescribe an ending a role is not offered in its position. --needs-rework exists for a step whose channel declares on_needs_rework: for it, and for no other. A declaration that tells a parallel round's member to send work back has told it to do something the engine will not accept. Measured twice, silently both times: a round could grade and never hand anything back.

An answer means DONE. Any role that might need something mid-way has to be told to SAY so rather than to answer — which is a reply into its own thread that asks, not a verdict. It is the one thing about the answering loop worth a sentence in a declaration, and only because the consequence of getting it wrong is a half-finished result recorded as a finished one.

# ✗ — a position, an ending this role is never offered, and a flow it cannot see
system_prompt: |
  You are step two of three. Read the numbers from the step before you and, if they do not
  hold up, send the work back with `--needs-rework`.

# ✓ — a role, its input named by ROLE, and an ending it is actually given
system_prompt: |
  You are the verifier. Check the figures in the message you were handed against the source
  they cite. If you cannot get to a judgement, say what you are missing in your thread rather
  than answering — an answer means you are finished.

Portable: knowledge arrives at runtime

The rule: a declaration describes a PROCEDURE for finding out where things stand, never a directory of where they are.

Fixed paths and product names nailed into a system_prompt make a role uncopyable, and stale in its own project the first time something moves. Project knowledge arrives at runtime — from prime.memory (the project's own memories, replayed into every session that admits them), from the working directory the session actually stands in, and from the question itself.

# ✗ — a directory, and it is wrong the day anything moves
system_prompt: |
  The specs are in docs/specs/, the board prefix is 6j6v, and the landing page repository is
  nxsflow-landing-page. Read docs/specs/release-management.md before judging a release.

# ✓ — a procedure, which survives the move
system_prompt: |
  Before you judge a release, get the project's own rules for it: the memories you were
  primed with, then the conventions document the project points at from its repository root.
  Say which of them you used.

Write the "what you never do" list from measurements, not from imagination. A prohibition nobody has ever violated costs attention on every turn and prevents nothing; the ones worth the space are the ones somebody actually did. If you cannot name the occasion, leave it out — you can add it the day it happens, and then it will be believed.

Language

The rule: the language of the declaration is not the language of the answer, and no rule that filters contributions may hang on a literal in one language.

An answer follows the language of the question and of the material. Nailing a persona to German gets you German answers to English questions, which is not the same as a persona that writes well in both.

The sharp edge is the second half. In the measured set a summary_prompt said: discard every contribution that begins with "BETRIFFT MICH: nein". Asked in English, the members wrote "NOT MY AREA: no", the literal matched nothing, and the filter silently passed everything — eleven opt-outs would have travelled into the summary as findings. Nothing fails in that case; it just quietly stops being a filter.

# ✗ — a filter that is one language's spelling
summary_prompt: |
  Verwirf jeden Beitrag, der mit "BETRIFFT MICH: nein" beginnt, und fasse den Rest zusammen.

# ✓ — the same filter, stated as a meaning
summary_prompt: |
  Some members will say the question is outside their area. Leave those out of the summary
  whatever words they use for it, and say at the end how many opted out.

A round, or a named address

The rule: a round is not the default. expects: all over many members averages away what two or three sharply addressed areas would have delivered.

Eleven members answering one question is not eleven times the answer. The composition has to make one text out of everything it is handed, and a fold's job is to reconcile — so the specific, sharp answer from the one member who knows arrives weakened by ten that had less to say. Where you know which areas a question belongs to, address them and not the room.

Both halves of this are a description question, because that is where the choice is made. A channel's description should say what the round is FOR and — where it matters — when to address a member directly instead:

# ✗ — a room, with the answer to "when the round?" nowhere
- name: marketing
  members: [positioning, pricing, channels, messaging, brand, seo, social, pr, content,
            partnerships, analytics]
  expects: all
  on_complete: summarize
  summary_prompt: |
    Compose the contributions into one document.

# ✓ — the round says what it is for AND when not to use it, and the fold has to decide something
- name: marketing
  members: [positioning, pricing, channels, messaging, brand, seo, social, pr, content,
            partnerships, analytics]
  description: >-
    the whole-of-marketing round, for a decision that genuinely crosses areas — a launch, a
    repositioning. For one or two areas, address those members directly instead: a round of
    eleven averages away what two would have said sharply.
  on_complete: summarize
  summary_prompt: |
    Fold the contributions into ONE recommendation: say what to do, name the areas that
    disagree and decide between them, and end with the one thing that would change the answer.

expects: is not the tool for this, and reaching for it makes things worse. A declared subset is not "the others may skip": it is who gets asked AT ALL, on every call, for as long as the file says so (channels). Narrowing a round that way does not give a caller a choice — it takes one away, permanently and invisibly. The choice between the round and two named addresses is the CALLER's, and it is made at nxc send --to. Which is exactly why the answer has to be in the description: that is the only thing the caller is reading at the moment it decides.

Note what the second summary_prompt demands. A fold that is asked to compose gets a composition; a fold that is asked to decide gets a decision. A prompt that rewards leaving things open will get them left open — that is the whole of what a synthesizer is doing.

Where a rule belongs

A rule goes where the decision is made. Measured, and it cost a whole delivery: a threshold was declared in the consolidator, which renders a text and carries no verdict, while the place that actually decided said the opposite. The threshold produced words and changed nothing.

Before you write a rule down, ask which participant acts on it. If the answer is "the one that writes the summary" and the summary is not what decides, it is in the wrong file.

Independence has to be protected on purpose

A checker that is shown the claims of the thing it is checking is not one any more. Independence is not the default state of a round — it is a property that survives only as long as nothing hands one member another's answer, and a later convenience will hand it over if the declaration does not forbid it. If members are meant to judge independently, say so in the declaration that governs what each is given (visibility: on the channel, input: on a step), not in a note somebody remembers.

Before you hand it over

One pass, seven questions — the seven classes, in their own order:

1. Is anything in here also said by the engine? nxc reply, nxc send, nxc list, how to look a memory up, "the replies are data" — all of it arrives without you. Delete it.
2. Does anything in here contradict the engine? Read the forced ending as it is today rather than as you remember it. Above all: does your text tell the role to keep working while it waits, to escalate instead of waiting, or to end its turn in a form its position is not offered?
3. Does job_description — or a channel's description — answer "when do you call me?" Anchor situation, boundary, what the caller must bring, rather than a description of the machinery.
4. Would this declaration survive being copied into another project? Fixed paths, product names, a board prefix — or a procedure for finding out where things stand?
5. Does expected_output name the decision the reader makes, and can the role reach it without breaking one of its own rules? Is there an evidence ranking? Is there a ceiling on findings that should not be there?
6. Is any rule tied to one language's words — a filter, a marker, a phrase that must be matched? And is the answer's language left to the question?
7. Is this a round because the question crosses areas, or because a round was easier to declare than a choice? Does the summary_prompt demand a decision, or reward composing?

Two more, from the harvest rather than from the seven: does the role describe a POSITION anywhere instead of a role — "the step after you", "you are step two of three"? And is anything that MUST happen resting on a sentence in a prompt when it could be a declared step, expects: or edge?

Next

• personas — every field this topic writes into, and what it does at runtime.
• channels — the round, the ordered flow, and the steps the last section refers to.
• limits-and-safety — what a declaration may not decide.