JetBrains/thinkrail

# Asking User Questions

The workflow family's shared norms for `ask_user_question`: how to interview in rounds, what makes a
question worth asking, how to shape options, and how to degrade when answers don't come. Process
skills name this concept at the steps that ask; *when* to ask — and where the answers get recorded —
stays with the referencing skill.

## Interview in rounds until nothing is assumed

- Map the subject as a **design tree**: every decision branches into the decisions that hang off it.
  The **frontier** is every open decision whose prerequisites are already settled — the questions you
  can ask *now* without guessing at answers you haven't heard.
- One call = one **round** = the whole frontier, with no cap on its size. A question whose answer
  depends on another question still open belongs to a *later* round, never the same one. Never split

# Brainstorming

## Interview before you build

- Every feature, behavior change, or bug fix goes through this workflow. Depth scales with the
  change and never drops to zero: a small change gets one short round and a few lines of task-spec.
- The aim is a design the user understands and has accepted, recorded in a spec-graph `task-spec`,
  built, and then reflected in the durable specs — not a speculative implementation.
- Do not implement until the design is accepted. An explicit design or acceptance criteria in the
  request count as approval of what they cover; build on them and never re-ask them.

## Doc map

- `fixing-a-bug.md` — the bug branch (step 4).

# Choosing a Workflow

The root router of the workflow family. It classifies new
workflow-eligible work and names the workflow skill that governs it — nothing more. Work already routed
resumes its active workflow instead. A routed skill's steps live in that skill alone; read it, don't run
it from memory.

## Classify

For a new piece of work, read the request and use what is already known to answer three questions:

1. **Is this project onboarding?** No spec graph yet — an empty or effectively empty workspace where
   the user brings a raw idea, or an existing codebase being set up or specced for the first time.
2. **Is this the PR lifecycle?** Finished work shipping as a pull request, or an existing PR being

# Importing a codebase

The workspace holds real code but no specs. **Reverse-engineer the spec graph the project should have
had.** When the repo already carries real spec-like documents, build the graph around them, not
parallel to them. Do as much as possible yourself, from the files; ask the user only where the code genuinely can't
tell you and the answer changes a spec.

**Hold the writing-specs bar.** Read that concept skill before drafting — everything in this flow is
inferred rather than confirmed, so its honesty rules (draft until the user reviews, unconfirmed marked
inline) bind hardest here.

## 1. Read first, ask last

Survey before you ask a single question. Read, in roughly this order:

# Setting up a project — dispatcher

The single entry point for turning a project into a spec graph. Figure out which situation you're in, then
follow the matching skill — don't improvise the flow yourself.

## 1. Detect

Look at the workspace and use the spec tools (`spec_grep` / `spec_graph`):

- Is there already a spec graph (a `goal-and-requirements.md` or any `SPEC.md`)?
- Is there real source code, or is the repo empty / near-empty (just a README or scaffolding)?

## 2. Route

# Shipping a PR

The PR lifecycle: ship the workspace's finished work, maintain PR metadata, and keep the PR healthy
when requested. One workflow, six phases as sibling docs — enter at the phase the ask names.

## Completion modes

- **Snapshot mode is the default** for creating, syncing, or updating a PR and for one-time status
  requests. Take one fresh checks and merge-state snapshot, report pending/failing/indeterminate state
  as observed, and stop without polling or fixing unrelated state. A push never upgrades the mode by
  itself.
- **Wait mode requires an explicit remote-completion ask**: monitor or watch checks, investigate CI,
  wait until green, or make the PR merge-ready. Done means every configured check is green, the head
  is current with its base, and GitHub reports an affirmative merge state; a requested draft is

# Starting a new project

The workspace is empty: no code, no decisions. Turn the user's idea into one clear, living product
document — `goal-and-requirements.md`. Later features, behavior changes, and bug fixes go through
`brainstorming`.

**Hold the writing-specs bar.** Read that concept skill before saving anything — it carries the
short / honest / on-rails rules and the goal-doc shape every section you save must meet.

## Method

1. **Build on what's already said.** Never re-ask what the request already told you.
2. **Infer, then confirm** — propose a concrete draft and let the user correct it; a suggestion beats an
   open question. Compose `ask_user_question` rounds per the **asking-user-questions** concept skill

# Writing Specs

The workflow family's shared bar for every spec a workflow produces: **short, honest, on-rails**.
Process skills name this concept at the steps that draft or revise specs; *what* to draft and *when*
stays with the referencing skill. Graph mechanics — frontmatter, link kinds, the `spec_*` tools — are
the spec-graph skill's ground; this concept carries the quality bar the family holds on top of them,
and is where the family's rules for specs and the spec graph accrue.

## Short

- Small enough to read in one sitting. Target signal, not completeness.
- Explain intent, not inventory: what the thing is for, what it owns, where its boundary runs — never
  a file listing or a restatement of the code.

# Writing Workflow Skills

The authoring checklist for workflow skills in `packages/pi-thinkrail-workflow`. It carries the *what
to do*; every *why* — the concept model, the three roles, the meta-rules cited as "(rule N)" below —
lives once in the workflow-system spec beside this directory, **`skills/SPEC.md`**. Read that spec
first; where this checklist and that spec disagree, the spec wins.

**Workspace guard.** This checklist edits `packages/pi-thinkrail-workflow` in the thinkrail repo. If
that package is not in the current workspace (a ThinkRail-managed project, where these skills are a
read-only staged cache), the family cannot be extended from here: say so in one line and stop — the
terminal state for foreign workspaces.

## Design (before writing)

# Chat TODO plan

## What it is

- A plan **scoped to this chat** — your tasks for the conversation. Shown to the user in the Todo
  panel; lives with the session (not committed to the repo).
- **Group = task, item = step.** One user ask = one group; its title is the *outcome* ("Fix login
  redirect"), not the process. The steps inside are the items — each has a **title**, a **status**
  (`pending` → `in_progress` → `done`), and an optional **note**. The note is **agent-facing working
  detail** — the human's default plan view shows titles + status and keeps notes behind a disclosure —
  so it's where your own tracking, reminders, and the done-criterion live (e.g. "login e2e green"),
  never a place the user must read to follow along. A task's own status is never stored — it derives from its steps.
- **Loose items are the shared raw-input queue — and they sit at the END of the plan.** Both sides
  write there: the user adds from the UI, and you may drop an unprocessed note with `todo_add` (no

# Managing MCP servers in ThinkRail

ThinkRail uses pi's built-in MCP support but has no `pi` executable. Never run `pi mcp add`,
`pi mcp login` or other `pi` commands; edit the configuration files and point the user at
**Settings › MCP servers** for everything that needs them.

## Where servers are configured

- **User level** — pi's agent directory, usually `~/.pi/agent/mcp.json`: available in every project.
- **This repository** — `.pi/mcp.json` in the worktree, tracked in git. A server defined here does not
  run until the user approves it in Settings, and any later change to its entry needs approval again.
  It only loads when the user trusts the project.

Both files use pi's format:

# Spec graph

## Specs are the ground truth

- Specs describe the architecture, decisions, contracts, and boundaries behind the code — the intent
  that the code alone does not reveal. Treat them as authoritative.
- **Consult the owning spec when it governs the work.** When work depends on, checks, explains, or
  may alter a documented boundary, contract, invariant, behavior, or architecture decision, use
  `spec_grep` / `spec_get` / `spec_graph` to find the applicable record and align with it. If a change contradicts a recorded
  decision, surface and reconcile the contradiction rather than silently diverging.
- **Keep lookup proportional.** Specs are the map for decisions and boundaries; code confirms the
  implementation. A localized fix, explanation, or check that changes no documented decision may
  inspect only the files it needs without reading unrelated specs.
- **Keep them honest.** A change that moves or blurs a boundary, or overturns a decision, updates the