discuss

Files (74)

• SKILL.md
• openai.yaml · agents/
• README.md · evals/
• case.yaml · evals/agent-tool-withheld-asks-the-developer/
• asks-the-developer-naming-the-agent-tool.md · evals/agent-tool-withheld-asks-the-developer/graders/
• no-agent-forked-in-its-place.md · evals/agent-tool-withheld-asks-the-developer/graders/
• no-agent-ran.md · evals/agent-tool-withheld-asks-the-developer/graders/
• nothing-ruled-or-written.md · evals/agent-tool-withheld-asks-the-developer/graders/
• prompt.md · evals/agent-tool-withheld-asks-the-developer/
• case.yaml · evals/auto-contradiction-ruled/
• contradiction-item-marks-ruled.md · evals/auto-contradiction-ruled/graders/
• not-asked-forked-to-choice-taker.md · evals/auto-contradiction-ruled/graders/
• prompt.md · evals/auto-contradiction-ruled/
• case.yaml · evals/auto-rules-every-branch/
• briefs-carry-the-closed-rows.md · evals/auto-rules-every-branch/graders/
• flag-dropped-from-the-plan.md · evals/auto-rules-every-branch/graders/
• last-line-carries-the-flag.md · evals/auto-rules-every-branch/graders/
• no-question-to-the-user.md · evals/auto-rules-every-branch/graders/
• ruled-adr-carries-the-line.md · evals/auto-rules-every-branch/graders/
• rulings-apart-from-decisions.md · evals/auto-rules-every-branch/graders/
• tree-shown-once-rows-ruled.md · evals/auto-rules-every-branch/graders/
• prompt.md · evals/auto-rules-every-branch/
• case.yaml · evals/choice-taker-unreachable-asks-the-developer/
• asks-the-developer-with-the-reason.md · evals/choice-taker-unreachable-asks-the-developer/graders/
• no-choice-taker-or-other-agent-forked.md · evals/choice-taker-unreachable-asks-the-developer/graders/
• nothing-ruled-or-written.md · evals/choice-taker-unreachable-asks-the-developer/graders/
• prompt.md · evals/choice-taker-unreachable-asks-the-developer/
• case.yaml · evals/empty-plan-under-auto-asks-for-the-plan/
• asks-for-the-plan-and-nothing-else.md · evals/empty-plan-under-auto-asks-for-the-plan/graders/
• no-agent-forked.md · evals/empty-plan-under-auto-asks-for-the-plan/graders/
• nothing-written.md · evals/empty-plan-under-auto-asks-for-the-plan/graders/
• prompt.md · evals/empty-plan-under-auto-asks-for-the-plan/
• case.yaml · evals/explores-first/
• contradiction-named.md · evals/explores-first/graders/
• glossary-challenged.md · evals/explores-first/graders/
• prompt.md · evals/explores-first/
• case.yaml · evals/extreme-branch-asks-the-developer/
• asks-the-developer-on-extreme.md · evals/extreme-branch-asks-the-developer/graders/
• no-ruling-written-for-the-extreme-branch.md · evals/extreme-branch-asks-the-developer/graders/
• prompt.md · evals/extreme-branch-asks-the-developer/
• case.yaml · evals/extreme-branch-keeps-the-others-ruled/
• asks-only-the-extreme-branch.md · evals/extreme-branch-keeps-the-others-ruled/graders/
• earlier-branches-stay-ruled.md · evals/extreme-branch-keeps-the-others-ruled/graders/
• prompt.md · evals/extreme-branch-keeps-the-others-ruled/
• case.yaml · evals/no-writes-without-decision/
• tree-clean.md · evals/no-writes-without-decision/graders/
• prompt.md · evals/no-writes-without-decision/
• case.yaml · evals/one-question/
• grounded-first.md · evals/one-question/graders/
• single-question.md · evals/one-question/graders/
• prompt.md · evals/one-question/
• case.yaml · evals/runnable-branch-ruled-unseen/
• no-prototype-forked.md · evals/runnable-branch-ruled-unseen/graders/
• rulings-line-ruled-unseen.md · evals/runnable-branch-ruled-unseen/graders/
• runnable-branch-ruled-from-descriptions.md · evals/runnable-branch-ruled-unseen/graders/
• prompt.md · evals/runnable-branch-ruled-unseen/
• case.yaml · evals/runnable-branch/
• forks-prototype.md · evals/runnable-branch/graders/
• prompt.md · evals/runnable-branch/
• case.yaml · evals/steered-choice-taker-asks-the-developer/
• …and 14 more

SKILL.md (first lines)

# Discuss

This session is an interview about a plan, held before any code is written. Its product is decisions: read what the repository already knows, lay the plan out as a tree of decisions, settle each one with the user, and hand the result to `spec`, the next skill in the chain, which builds from the closing summary.

The plan is the subject of the interview, never a task to carry out. However concrete it reads, nothing in it is implemented here: the session writes `CONTEXT.md` and files under `docs/adr/`, and edits no code.

The user's attention is the scarce resource. A question the repository could have answered, or one about a detail that is cheap to change, spends attention the real trade-offs need, so every rule below either saves a question or makes the ones that remain easier to answer.

Every message to the user is written in the language the user opened the session in. Everything written into the repository (`CONTEXT.md`, ADRs, file names) is in **English**.

The run, in order: ground → tree → one question at a time → capture as it lands → write the ADRs → close.

## Vocabulary

Used consistently, in the thread and in what the session writes:

- _branch_: one decision the plan needs.
- _tree_: the branches and the dependencies between them.
- _lens_: a principle turned into a question.
- _tell_: the answer that fails a lens.
- _default_: an answer taken and stated instead of asked.
- _deferral_: a branch parked with the condition that reopens it.
- _runnable_: a branch only a running artifact can settle. A throwaway prototype is built and the question is put against it.
- _candidate_: a decided or ruled branch that passes the three gates of an ADR. Every candidate the close does not drop is written.

## How a turn ends

A message with no tool call ends the turn, and the session waits there until the user writes again. The turn ends at these points and no others:

- the ask for a missing plan (step 1);
- a question to the user (step 3), which includes the three exceptions under `--auto`;
- the close (step 6).

Everything between those points happens in one turn. The grounding note, the tree and the first question arrive together: the session never stops after the note or the tree to ask whether to begin. A status line is welcome, in the same message as the next tool call. Under `--auto` nobody is watching the run, so a turn that ends on a progress summary, on an announcement of the next branch, or on an offer to carry on stops the walk with branches still open. When a message is about to end that way, make the next tool call instead.

## 1. Ground

**The plan.** The plan is `$ARGUMENTS`.

- An `--auto` token among them, before the plan, after it or inside it, is dropped wherever it sat and puts the run under `--auto` (step 3). The plan is the rest, with no flag in it, and it is that plan the run grounds and hands on.
- Without the token the plan is `$ARGUMENTS` as typed.
- Empty → ask for it, in one message that carries nothing else.

**The reading.** Before any question, read what the repository already knows. Say in one line what is being read, then make the reads that do not depend on one another in one batch:

- **The glossary.** `CONTEXT-MAP.md` at the root, when it exists, names the contexts and where each lives: pick the one the plan touches, ask when it is unclear. Otherwise the root `CONTEXT.md`. Neither existing is fine; nothing is created until the first term is resolved (step 4).
- **The ADRs.** `docs/adr/*` at the root and, when the map names one, the context's own `docs/adr/`: titles first, bodies only for the ones the plan touches.
- **The code the plan touches.** Symbols the plan names get one `discover` batch: call the Skill tool with "discover", every candidate in one call. When the session lists a skill named `how` or `why`, call the Skill tool with it for the subsystem the plan reshapes; otherwise explore with `rg` and targeted reads. A search or a handful of reads stays in the thread. Exploration whose output would run to pages (a whole subsystem, many files) goes to a subagent, and the thread keeps the summary.
- **The working tree.** `git status --short` and the branch: dirty files are the user's work in progress and part of the picture.

**The grounding note.** Output, in the thread, a grounding note of three to six lines: what already exists, what the docs already decided, and every contradiction between the plan and the code or the glossary, each with `file:line`. A contradiction found here is the first branch of the tree.

## 2. Build the tree

List the branches: every decision the plan needs, one line each.

- **Order.** Mark the dependencies (a branch whose answer changes another branch's answer comes first) and order the walk by them.
- **Lenses.** Tag each branch with the lenses from step 5 that apply to it.
- **Runnable.** Mark a branch _runnable_ when its answer depends on seeing or driving the thing rather than on describing it: what a screen should look like, or how a state model behaves across a sequence too long to hold in the head.
- **Closed here.** A branch the repository already answers is closed here, with the evidence, and is never asked.

Show the tree once, compact, with each branch's state: `open`, `decided`, `default`, `deferred`, and `ruled` under `--auto` (step 3). Keep it updated as branches close; show it again only when its shape changes (a new branch, a reorder). A branch closing, a `ruled` one included, is not a shape change.

One shape the tree can take. The layout is free; the state on every row is not:

<example>
1. [decided] Where a reminder's due time is stored: a UTC column, already there (src/reminders/schema.ts:14)
2. [open] What snoozing a recurring reminder moves: the occurrence or the series · model-the-domain
3. [open] After 2: how a snoozed occurrence reaches the daily digest · boundary-discipline
4. [open, runnable] What the snooze picker looks like · experience-first
5. [default] Snooze presets of 10 minutes, 1 hour, tomorrow: a list that is cheap to change
</example>

## 3. Interview, one branch at a time

For the first open branch, in walk order:

1. **Explore first.** Whatever can still be settled from the repository is settled there: close the branch, say so in one line, move on.
2. **Talk before running.** A prototype is built only for a branch marked _runnable_ in the tree, or for one the user answers with "I need to see it"; a branch the user can answer from a description never gets one. The mechanics are under "A runnable branch" below.
3. **One question per message.** The message carries three things and nothing else: the question, the tell it hunts in one line, and the recommended answer with its reason. Never a list of questions, never a second question in the same message: one question gets a considered answer, and a list gets the first item answered and the rest skimmed.
4. **Wait for the answer.**
5. **Check the answer.** Push back once, with the evidence; the user's repeat is the decision.
   - Against the glossary: a term used in a sense `CONTEXT.md` does not give is called out immediately ("your glossary defines X as ..., you seem to mean ...").
   - Against the code: a claim about how something works is read in the code before it is accepted, and a contradiction is surfaced with `file:line`.
   - Against a scenario: a domain relationship gets one concrete scenario that probes its boundary ("a Customer with two open Orders cancels one: what happens to the Invoice?").
   - A fuzzy or overloaded word gets a proposed canonical term.
6. **Close the branch.**
   - `decided`: the user chose. The branch keeps the choice, its reason and the alternative it beat, in one line.
   - `default`: a reversible detail. State the choice and its reason instead of asking.
   - `deferred`: parked, with the condition that reopens it, in one line.
7. **Capture** (step 4), then update the tree. A branch the answer opened joins the tree at its dependency position.

A reversible execution detail is never a question. The question budget goes to direction, trade-offs and anything hard to undo.

### The question message

Three parts, in this order, in the user's language (the labels are translated with the rest). The examples show the shape on three kinds of branch; the wording, the length and the domain are the branch's own.

<examples>
<example>
An ordinary branch:

Does snoozing a recurring reminder move only the next occurrence, or shift the whole series?

Tell: one `snoozedUntil` field read as both, so the digest and the scheduler disagree about what was snoozed.

Recommendation: only the next occurrence, stored as an override on that occurrence. The series rule stays the single source of the schedule, and undoing a snooze is deleting one row.
</example>
<example>
A runnable branch, put against the prototype's report:

Open `/tmp/proto-snooze/index.html` and switch between the three variants with the bar at the top. Which picker lets you snooze to "tomorrow morning" without reading a label twice?

Tell: the variant that is easiest to build wins over the one that is fastest to use.

Recommendation: variant B, the preset row with one custom field. It covers the three presets in one tap, and A hides them behind a menu.
</example>
<example>
An `extreme` return under `--auto`:

From Thalisu/SKILLS, MIT.

More from Thalisu/SKILLS