quint-code

Reasoning with /q-reason

/q-reason is the entry point for structured engineering reasoning. It reads your intent from context and chooses the right behavior — not every question needs a full decision cycle.

Three paths, one command

The agent assesses what you actually want before doing anything. There are three distinct paths:

Path 1: Think and respond

You want structured thinking, not artifacts. The agent reasons through the problem using FPF principles and gives you a well-structured answer. No tool calls, no decision records. 

/q-reason what do you think about using gRPC
here instead of REST? what are the trade-offs?
/q-reason is our current auth approach the
right one? what's the weakest link?

Path 2: Prepare and wait (human drives)

You want to drive the decision cycle yourself. The agent gathers context — reads relevant code, searches existing decisions, researches the topic — and presents findings. Then it stops and waits for you to decide the next step. You call /q-frame, /q-char, etc. when ready. 

/q-reason I want to think through our caching
strategy. Gather context and prepare for framing.
/q-reason let's reason about the database
migration before deciding anything

This is the default when intent is unclear. The agent never assumes you want it to drive the full cycle.

Path 3: Full autonomous cycle (agent drives)

You explicitly delegate. The agent runs the full cycle: frame, generate options, compare, decide, implement. 

/q-reason figure out the best caching approach
for our API and implement it
/q-reason fix the auth architecture problem,
go through the full cycle and implement

Only this path runs without pausing. The agent asks for confirmation only at the final decision.

Why this matters: FPF is powerful, but if the agent always drives the whole cycle, you end up approving outputs rather than thinking. The three-path design ensures /q-reason augments your reasoning when you want to think, and takes over only when you explicitly ask it to.

Depth modes

When the agent does enter the decision cycle (Paths 2 or 3), it selects a depth:

Mode When What happens
Tactical Reversible, low risk, obvious approach Frame → Explore → Decide (skip characterization and comparison)
Standard Multiple viable approaches, moderate blast radius Frame → Char → Explore → Compare → Decide (full cycle)
Deep Hard to reverse, security implications, cross-team impact Full cycle + rich parity rules, rollback runbook, refresh triggers

You can override the depth: /q-reason deep: should we change our database?

The diagnostic conversation

Before the agent starts generating options, it drives a diagnostic conversation. This is the most important part — problem quality determines solution quality. The agent asks:

  1. "What observation doesn't fit?" — the signal, not the assumed cause
  2. "What have you already tried?" — avoids re-treading dead ends
  3. "What would solved look like?" — measurable acceptance criteria
  4. "What constraints are non-negotiable?" — hard limits
  5. "How reversible is this?" — determines mode
  6. "What should we watch but NOT optimize?" — Anti-Goodhart indicators

Answer these honestly. The better the framing, the better the variants.

What you get at the end

A decision record (.quint/decisions/dec-XXXXXXXX-XXX.md) with four sections:

  1. Problem Frame — what triggered the decision, constraints, acceptance criteria
  2. Decision — what was selected, invariants (what must always be true), pre/post conditions
  3. Rationale — why this and not the alternatives, comparison table, weakest link
  4. Consequences — rollback plan, refresh triggers, affected files

This file is designed for code review. Commit it alongside the code it describes. Full-cycle decisions contain enough structure to serve as test specifications — any agent can generate property-based tests from the invariants and post-conditions.

After the decision

After implementing the decision, the agent should:

  1. Snapshot affected files (baseline) — so drift detection can track changes
  2. Run measure — record whether acceptance criteria were met

This closes the loop. Without measurement, the decision stays in "Pending Implementation" on /q-status and on the board.

When not to use it

  • Obvious bug fixes with clear solutions
  • Formatting, import ordering, variable naming
  • Anything that takes less than 5 minutes and is trivially reversible

For these, just code. If the agent notices a decision worth recording, it'll create a note automatically.

Next