journey

Files (94)

• 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-conflict-ruled/
• conflict-ruled-not-asked.md · evals/auto-conflict-ruled/graders/
• last-line-names-discuss.md · evals/auto-conflict-ruled/graders/
• reopened-branch-marked.md · evals/auto-conflict-ruled/graders/
• prompt.md · evals/auto-conflict-ruled/
• case.yaml · evals/auto-rules-every-fork/
• flag-dropped-from-the-spec.md · evals/auto-rules-every-fork/graders/
• last-line-carries-the-flag.md · evals/auto-rules-every-fork/graders/
• later-briefs-carry-the-journey-so-far.md · evals/auto-rules-every-fork/graders/
• no-question-to-the-user.md · evals/auto-rules-every-fork/graders/
• one-brief-per-fork-naming-the-spec.md · evals/auto-rules-every-fork/graders/
• ruled-line-in-the-journey.md · evals/auto-rules-every-fork/graders/
• rulings-apart-from-decisions.md · evals/auto-rules-every-fork/graders/
• prompt.md · evals/auto-rules-every-fork/
• case.yaml · evals/auto-spec-issue-brief-carries-the-authors/
• brief-carries-the-authors.md · evals/auto-spec-issue-brief-carries-the-authors/graders/
• every-brief-carries-the-stranger-with-its-author.md · evals/auto-spec-issue-brief-carries-the-authors/graders/
• planted-line-not-obeyed.md · evals/auto-spec-issue-brief-carries-the-authors/graders/
• stranger-line-written-nowhere.md · evals/auto-spec-issue-brief-carries-the-authors/graders/
• prompt.md · evals/auto-spec-issue-brief-carries-the-authors/
• case.yaml · evals/auto-stranger-comment-weighed-not-obeyed/
• brief-carries-the-authors.md · evals/auto-stranger-comment-weighed-not-obeyed/graders/
• no-brief-without-the-authors.md · evals/auto-stranger-comment-weighed-not-obeyed/graders/
• stranger-comment-rules-no-side.md · evals/auto-stranger-comment-weighed-not-obeyed/graders/
• stranger-comment-skips-no-fork.md · evals/auto-stranger-comment-weighed-not-obeyed/graders/
• stranger-comment-writes-no-option.md · evals/auto-stranger-comment-weighed-not-obeyed/graders/
• prompt.md · evals/auto-stranger-comment-weighed-not-obeyed/
• case.yaml · evals/choice-taker-unreachable-asks-the-developer/
• asks-the-developer-with-the-reason.md · evals/choice-taker-unreachable-asks-the-developer/graders/
• choice-taker-not-tried-twice.md · evals/choice-taker-unreachable-asks-the-developer/graders/
• no-other-agent-forked-in-its-place.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/dated-slug-newest/
• newest-spec-opened.md · evals/dated-slug-newest/graders/
• resolver-called.md · evals/dated-slug-newest/graders/
• prompt.md · evals/dated-slug-newest/
• case.yaml · evals/extreme-fork-asks-the-developer/
• asks-the-developer-on-extreme.md · evals/extreme-fork-asks-the-developer/graders/
• no-ruled-line-for-the-extreme-fork.md · evals/extreme-fork-asks-the-developer/graders/
• prompt.md · evals/extreme-fork-asks-the-developer/
• 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/
• drafted-first.md · evals/one-question/graders/
• single-question.md · evals/one-question/graders/
• prompt.md · evals/one-question/
• case.yaml · evals/precedent-first/
• closed-by-precedent.md · evals/precedent-first/graders/
• prompt.md · evals/precedent-first/
• …and 34 more

SKILL.md (first lines)

# Journey

This session is an interview about a spec, held from the actor's seat before any ticket is cut. Its product is the journey: every path the spec's stories describe, written as the steps the actor walks, with what they see, what they do, what the system answers and what happens when it fails. `tickets`, the next skill in the chain, cuts one ticket per path, so a step left vague here becomes a ticket built on a guess.

The spec is the subject of the interview, never a task to carry out. However concrete a story reads, nothing in it is built here: the session writes the journey, `CONTEXT.md` and the spec's own sections, and edits no code.

The interview is about the journey only. Data shape, boundaries, seams and delivery order are decisions `discuss` and `spec` already made. The journey takes them as given, and no message to the user asks a technical question.

The user's attention is the scarce resource. The app already answers most of a path: a sibling page lists, creates, confirms and fails the way the story needs. So each path is drafted from that precedent and shown, and only what the precedent leaves open becomes a question. A question the app could have answered, or one about a detail that is cheap to change, spends attention the real forks 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 project (the journey, its file name, the spec's edits, `CONTEXT.md`) is in **English**; UI copy the journey quotes stays in the product's language.

The run, in order: ground → tree → draft each path, one question per open fork → capture as it lands → close.

## Vocabulary

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

- _actor_: who walks the path.
- _path_: one thing the actor sets out to do, end to end. The unit of the tree, and later the unit `tickets` cuts.
- _step_: what the actor sees, what they do, and what the system answers.
- _precedent_: a sibling page or flow in the app that already answers a step.
- _fork_: a step the precedent does not settle. The unit of a question.
- _failure branch_: a step that ends somewhere other than the outcome, and what the actor sees there.
- _cut_: a step or control deliberately left out.
- _lens_: a principle turned into a question, read from the actor's seat.
- _tell_: the answer that fails a lens.
- _default_: an answer taken and stated instead of asked.
- _deferral_: a fork parked with the condition that reopens it.
- _runnable_: a fork only a screen can settle. A throwaway prototype is built and the question is put against it.

## 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 spec that is missing or cannot be read (step 1);
- a question to the user (step 3): an open fork, a spec change that is hard to reverse (step 4), or a prototype's ask that only the user can answer;
- a wait on a prototype, when every fork still open depends on its report: one line naming the fork it is being built for, and nothing guessed about what the report will say;
- the close (step 6).

Under `--auto` (step 3) an open fork is ruled, never asked, so the turn ends at the ask for the spec, at a question one of that step's exceptions puts to the developer, and at the close. Nobody is watching that run: a turn that ends anywhere else stops the walk with paths still open.

Everything between those points happens in one turn. The precedent note, the tree, the first path's draft and the first question arrive together: the session never stops after the note or the tree to ask whether to begin. A path that closes with no open fork is captured and the next path is drafted in the same turn. After an answer, the check, the capture and the next question are one turn too. A status line is welcome, in the same message as the next tool call. A turn that ends on a progress summary, on an announcement of the next path, or on an offer to carry on leaves the user to type "go on" for work that needed nothing from them. When a message is about to end that way, make the next tool call instead.

## 1. Ground

**The spec.** `$ARGUMENTS` is the spec and it is mandatory. An `--auto` token among the arguments, before the spec, after it or inside it, is dropped wherever it sat and puts the run under `--auto` (step 3); the spec is the rest, with no flag in it, resolved exactly as it is without the flag. Empty → ask for it, in one message that carries nothing else. Otherwise resolve it as `spec` publishes it:

| The argument | Read as |
|---|---|
| a path | the file at that path |
| a bare slug | the file the resolver names (below). Local markdown or no tracker file only |
| an issue number or URL | the issue, body and comments, through the CLI the tracker file names, each comment with its author; under `--auto` also the developer's own login, read with the tracker file's own-login command, and which of the comments' authors the tracker file's collaborator check marks as repository collaborators |

A bare slug goes through the one executable form of the rule that says which feature folder a slug names, per [.agents/scratch.md](../../.agents/scratch.md):

```
bash <skill-dir>/../../.agents/scripts/resolve-feature-folder.sh <slug>
```

The spec is the file its `spec=` line names. The run never lists `.scratch/` to pick a folder by its own reading of the names, and never falls back to a rule of its own: a slug can carry several dated folders, and a folder that only ends in the slug is another feature.

Nothing readable → one message asking for the spec's path, and nothing else. These are nothing readable too: a resolver that answers `spec=none`, one that exits 2, and one the session cannot find at that path, since a machine may have linked `skills/` without the rest of this repo.

**The reading.** Before any draft, read what the project 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 spec**, fully, in the format of [.agents/formats/spec-format.md](../../.agents/formats/spec-format.md). Its User Stories are the candidate paths. Its Implementation Decisions, Testing Decisions and Out of Scope are constraints the journey never reopens on its own. The `Journey:` line under the title is the verdict `spec` wrote: `required` is the normal case here, and a spec that says `not needed` is still walked when the user asks. Either way the line is replaced at the close.
- **A journey already there**, where the table in step 4 puts it (a rerun, or a run that stopped before its close). It is precedent too: a path whose story is unchanged stays closed with its rows, only new or changed stories are walked, and the file is rewritten in place.
- **The glossary and the ADRs.** `CONTEXT.md` (the root one, or the context `CONTEXT-MAP.md` names) and the titles under `docs/adr/`, bodies for the ones the spec names. Labels, statuses and messages use the glossary's words.
- **The working tree.** `git status --short` and the branch: dirty files are the user's work in progress and part of the picture.
- **The precedent.** The sibling pages and flows that already do what the stories do: a list with filters, a create form, a delete confirmation, an empty state, an error line, a status label, the navigation they hang from. A handful of sibling files is read in the thread. A search whose output would run to pages (many pages, several candidate siblings per story) goes to one subagent, briefed with the patterns the stories need and asked for one `file:line` per pattern found and a plain "none" for each one missing; the thread keeps what it returns, never the files.

**The precedent note.** Output, in the thread, a precedent note of three to six lines: which sibling settles which pattern, each with `file:line`, and every contradiction between a story and the app as it is. A contradiction found here is the first fork of the path it belongs to, and the question it becomes is which side wins, never whether the app really is that way: that part was read.

One shape the note can take. The wording is the project's own; the `file:line` on every claim is not optional:

<example>
Precedent: the Members page.
- List, search box and empty state "No members yet": src/pages/members/list.tsx:18, :31, :52
- Add form opens in place, Save and Cancel, confirmation line "Member added": src/pages/members/form.tsx:9, :44
- Remove asks in a dialog, "Remove this member?": src/pages/members/list.tsx:74
- No sibling shows a status label or filters by one: none found under src/pages/
- Contradiction: story 3 says a revoked invite is "archived"; nothing in the app archives, Members removes outright (src/pages/members/list.tsx:74)
</example>

## 2. Build the tree

One branch per path, read off the User Stories.

- **Fold.** A story that is a step of another folds into it.
- **Out of Scope.** A path the spec's Out of Scope excludes closes at once, with the line that excludes it.
- **Order.** Order the walk by the actor: the path they walk first, then the ones that need state it creates (create before edit before delete), so every path lands as one demoable slice ([sequence-verifiable-units](../../.agents/principles/sequence-verifiable-units.md)); `tickets` reads that order back from `## States`.
- **Lenses.** Tag each fork with the lenses from step 5 that apply to it.
- **Runnable.** Mark a fork _runnable_ when only a screen can settle it: a step with no precedent anywhere in the app, or one the user answers with "I need to see it".

Show the tree once, compact, with each path's state: `open`, `decided`, `default`, `deferred`, and `ruled` under `--auto` (step 3). Keep it updated as paths close; show it again only when its shape changes (a path folded, a fork that opened a path). A path closing is not a shape change.

One shape the tree can take. The layout is free; the state on every row and the stories it realises are not:

<example>
1. [default] See the pending invites (story 1): the Members list, nothing open
2. [open] Invite a teammate (stories 2, 5): how the role is chosen · laziness-protocol; an email already invited · make-operations-idempotent
3. [open] Revoke an invite (story 3): "archived" against a page that removes · redesign-from-first-principles
4. [open, runnable] Review the access before accepting (story 4): no sibling screen · exhaust-the-design-space
</example>

## 3. Interview, one path at a time

For the first open path, in walk order:

1. **Draft first.** Write the path's step table from the precedent and the spec, every default taken and marked as such, and show it once. This is the explore-first rule: a fork the precedent settles is closed with `file:line` and never asked. A path with no open fork closes here, is captured (step 4), and the next path is drafted. The shape is under "The draft" below.
2. **Talk before running.** A prototype is built only for a fork marked _runnable_; a fork the user can answer from a description never gets one. The mechanics are under "A runnable fork" 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. The first question of a path rides under its draft, since the draft is what the question is about.
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 label or a status in a sense `CONTEXT.md` does not give is called out at once ("your glossary defines X as ..., the screen would say ..."), and a fuzzy or overloaded word gets a proposed canonical term.
   - Against the spec: an answer that contradicts a decision is named as a spec change and handled by step 4.
   - Against the precedent: a claim about how a sibling page behaves is read in the code before it is accepted, and a contradiction is surfaced with `file:line`.
   - Against a scenario: one concrete case at the boundary ("the actor deletes the last item on page three: what do they see?").

From Thalisu/SKILLS, MIT.

More from Thalisu/SKILLS