working-with-the-user.md

Working with the user

This page gives the rules for an assistant session that works with the user of this repo. It also says which kinds of work wait until later. The user is the person who works with the session. planning.md calls this person the operator.

The rules apply to each session that works with the user, for example the orchestrator of orchestration.md and the planning session of planning.md. They do not apply to the sessions that tasker starts for plan, execute and review.

The work on this repo must continue on any machine, as What goes in a ticket of planning.md says. For this reason, these rules are in the repo and not in the notes of an assistant.

A decision of the user

• When the user must decide something, first explain in the reply what happened, what the problem is, and what each choice does. Then ask, and give a recommendation.
• Do not ask with a popup that holds only a short summary. In one case, the user rejected such a popup and wrote "I need more context. What is happening?".
• When you list open items or proposed issues, give each item what happened, why it matters and a recommendation.
• Define each term that the user did not see before, at its first use. An example is a label convention.
• Say what the code does. Do not write "by hand" or "manually" about code. This rule covers text about code. It does not cover an action of a person or a session, for example a change by hand to a clone. In one case, "the test opens the store by hand" read as if a session opened the files of tasker, which is not allowed. Write "the test writes the open and close steps itself instead of calling the helper".
• When you list the decisions that the user must make, give each question its own number in the main list. This also applies when two questions are about the same issue. Do not put a second question inside a bullet of another question. In one case (2026-10-15), a question about the link commands of #117 sat in a sub-bullet of the scope question of #117, and the user answered only the scope question.
• When the session asks the user about a landing order, the session gives each ticket of the order one line. In that line, the session gives the state of the task of the ticket and its distance from landing, in time, for example "in accepted, minutes from its merge". The session does not give only a phrase such as "close to landing". In one case (2026-10-17), the options for #182 said that #98 was "in executed" and "close to landing". The user did not see that #98 was minutes from its merge. Later, the user said that #98 was the right ticket to land first.
• This bullet covers a decision of the user that another orchestrator relays (see the bullet "Only the user changes a landing order of the overlap rule" of Land the work of land-the-work.md). When the relayed decision differs from an answer that the user gave this session, the session starts the question with one line. In that line, the session says that the two answers differ and names both answers. Then the session gives the options. The bullet also covers an answer that the user gave an earlier session of the same role. That answer counts when the handoff file that the session works from lists it under the decisions of the user. Then, in the first line of its question, the session names that handoff file as the source of that answer. For example, the user tells the Docs orchestrator "land ticket X first", the handoff file lists that answer, and then, after the handoff, orchestrator-m13 relays "land ticket Y first". In one case (2026-10-17), the session started the question with the relay. The user read the question as a confirmation of the earlier answer and asked "I already told you to land #182, right?".
• When the session reminds the user of a decision that still waits, the session gives the question again in short, with its choices. A line such as "A or B still waits" is not enough. In one case (2026-10-18), a reminder of orchestrator-m13 said only "still waits for your choice: A or B", and the user asked "what are the open questions?" and later "what is the question?".

A question of the user

• When the user asks a question, answer only that question. Take no action and make no offer that the user did not ask for.
• This rule covers a question of the user. When the user must decide something, the session still gives a recommendation, as A decision of the user says.
• In one case (2026-10-17), the user asked the Docs orchestrator questions about its handoff. The orchestrator answered and also offered next steps. After one message of the user, the orchestrator left the handoff and started a ticket without the word of the user. The user wrote: "When I ask questions, just answer. Do not anticipate what I want."

The issue-link rule

In each reply to the user, the session writes each mention of an issue as a markdown link. The link target is the page of the issue in its tracker. The link text is the issue key, in this form:

• For an issue of this repo, the text is the short form #<N>, for example [#159](https://github.com/codeguru42/tasker/issues/159).
• For an issue of another repo, the text is the full key, for example [owner/repo#12](https://github.com/owner/repo/issues/12).

The rule covers the replies of the session to the user only. The text on GitHub keeps the plain key, because GitHub links it. The messages to a session keep the plain key, because a session reads them as text. A key inside a code span or a code block stays as it is, for example a command line with an issue key.

The reason: the user opens the issue by hand. On GitHub, #159 is a link, but in the terminal it is plain text. In one case (2026-10-18), the planning session of the Docs milestone wrote plain keys such as #303 in each reply, and the user had no link to open an issue from a reply.

Core features first

• The goal is the core features of each command. An edge case waits until later. Do not ask the user about each edge case. Decide it as "later", and keep the ticket in its scope. The goal of the numbered milestones is parity with the installed tasker: each command of the installed tasker, with its core features. A feature that the installed tasker does not have also waits until later, as an edge case does.
• Two kinds of finding do not wait: a security gap and a bug in the core path. Tell the user about a security gap at once. Review findings of review-findings.md defines both terms and gives the steps for a finding of a review.
• Each piece of work that waits becomes an issue in its later milestone, as The milestone of an issue of planning.md says. issues.md gives the steps to file the issue.
• Containers are out of scope for now. Do not raise or file an edge case that occurs only in a container. An example is a process that has the same pid at each start, so that the lock row of a crashed run looks like the lock row of the process itself.
• tasker writes and reads UTF-8 text only. The output code does not write raw bytes.
• A collision of derived names is not an issue. Examples are two repo keys or two issue keys that give the same slug, the same folder or the same task branch. Do not raise such a collision, and do not file an issue for it. When an agent reports one, dismiss it with this reason.

Simplify over special rules

• When a review keeps finding edge cases in a rule, and each fix opens the next case, stop the patches. After two loops in a row where the fix of a rule draws a new edge case, give the user a simpler rule as the first choice and the patch as the second choice.
• In one case, an exception for one more loop drew a new edge case in each of 4 loops. The user replaced all the special loop rules with one rule: "up to 5 loops, then report". Review findings of review-findings.md holds that rule.
• When the orchestrator gives the user the simpler rule as a choice, the orchestrator also tells the agent of the ticket to wait. The agent does not run its next tasker approve or tasker accept until the user decides. The agent waits as the answer-wait rule says. Then the orchestrator sends the agent the decision of the user. The reason: if the user then picks the simpler rule, a landing with the patch costs a second ticket. On 2026-10-17, the agent of #250 went on, #250 landed with the patch before the user chose the simpler rule, and #306 undoes the patch.

The tools of a session

• Read a file with the Read tool of the session. Do not use cat, head or sed -n in a Bash call to read a file.
• The output of a command stays in Bash, for example the output of gh or tasker.
• A watch, a monitor or a scheduled job that the user asks for covers only the items that the user named. It also serves only the purpose that the user named. The session does not widen it to other items. The session stops it when its purpose ends, and it tells the user. This rule covers only a watch, a monitor or a scheduled job that the user asks for. It does not cover a job that a doc tells the session to schedule, for example a job of Quota. In one case (2026-10-17), the user asked orchestrator-m13 to watch the tasks of M9 and to tell the user when #274 was ready to land. The orchestrator widened the watch to each later ticket of M13 and started it again each 30 minutes. On 2026-10-18, the user stopped it and said: "the current use isn't even close to the original intent."