sequential-thinking git:20260908.c37b890A

Immutable. This exact content is served forever at /api/v1/blob/a545be6eb4c60856.

---
description: Structured decision summaries with revisions and branches. Use only when
  the user explicitly requests sequential thinking, step-by-step reasoning, or a
  structured comparison of decision branches. NOT an automatic trigger for difficult
  tasks, ordinary planning, or debugging. For open-ended ideas use brainstorming-ideas.
name: sequential-thinking
---

# Sequential Thinking

Same intent as MCP-based sequential-thinking tools — present numbered decision summaries with revision and branch semantics — implemented as visible Markdown so reasoning-capable models can follow it without an extra tool round-trip.

## When to use

Use only on an explicit user request for this format. Complexity alone is not a
trigger. For ordinary work, provide the decision, supporting evidence, assumptions,
and validation briefly without Thought blocks.

## Why a visible protocol (not just internal CoT)

Modern reasoning models already think internally. They need a shared on-the-page format so:

- the user can audit which step a wrong conclusion came from,
- revisions can point at the specific thought they replace,
- branches can be compared side by side instead of overwriting each other,
- a downstream agent or reviewer can parse the structure.

Do not try to suppress, expose, or paraphrase the model's hidden reasoning trace. Use this protocol in addition to it — write the durable, reviewable summary as Thought blocks; let the internal trace stay internal.

## Protocol

Open with a one-line plan, then emit numbered Thought blocks. Use these exact markers so output is parseable:

```
**Plan:** N thoughts (estimate). Subject: <one-line problem statement>.

### Thought 1
<the step — observation, deduction, sub-decision, or question>

### Thought 2
<...>

### Thought 3 (revises 1)
<corrected version, with one sentence on why 1 was wrong>

### Branch A from 2
<alternative path>

### Thought 4 (Branch A)
<continuation of A>

### Thought 5 (main)
<continuation of the main line>

### Final
<the conclusion or recommendation. Names the winning branch if any.>
```

### Block rules

- **Numbering**: monotonic. A revision gets a new number; it does not overwrite an old one. `(revises N)` declares which thought it supersedes.
- **Branches** are labelled `Branch <letter> from <N>`. Subsequent thoughts on that branch tag themselves `(Branch <letter>)`. The default trunk needs no tag.
- **Estimate**: the opening `Plan:` is an estimate, not a contract. If more thoughts are needed, write `### Thought N (extending plan to M)` and continue. Don't pretend you knew all along.
- **One thought, one move**: a thought makes one observation, one deduction, or asks one question. Walls of text under a single number defeat the point.
- **Final**: mandatory. Stop with `### Final`. Without it, callers can't tell whether you finished or got cut off.

### Grounding

When a thought references the codebase, cite `path:line` (or quote the relevant snippet). When a thought rests on an unverified assumption, prefix it `ASSUMPTION:` so revision can target it later. Do not invent file paths or function signatures to make a step sound concrete — an unsupported step is worse than no step.

### Verification gate (before `### Final`)

Run a brief checklist in the last numbered thought:

1. Does the conclusion follow from the evidence cited, or only from assumptions?
2. Is any thought contradicted by a later finding without a `(revises N)` marker fixing it?
3. Were the alternative branches actually compared, or just listed?
4. If the user asked for a recommendation, is one named — not hedged?

If any check fails, add one more Thought to address it before writing Final.

## Example (compressed)

> **Plan:** 4 thoughts. Subject: pick auth strategy for the new internal dashboard.
>
> ### Thought 1
>
> Existing services use OIDC via the company IdP (`infra/auth/oidc.go:42`). Reusing it avoids a new identity surface.
>
> ### Thought 2
>
> Dashboard needs short-lived tokens for embedded widgets. OIDC ID tokens are 1h; refresh is browser-side. ASSUMPTION: widgets stay in the same origin.
>
> ### Branch A from 2
>
> Service-to-service: signed JWT minted by the dashboard backend, 5min TTL. Avoids browser refresh edge cases for widgets.
>
> ### Thought 3 (Branch A)
>
> Backend already has the signing key from `internal/jwt/signer.go:18`. No new infra. Tradeoff: widgets can't run as the user, only as the dashboard.
>
> ### Thought 4 (revises 2)
>
> Re-checked: widgets DO call user-scoped APIs. Branch A breaks that.
>
> ### Thought 5
>
> Verification: conclusion (stay on OIDC) follows from Thought 4; Branch A explicitly rejected; recommendation named.
>
> ### Final
>
> Use OIDC end-to-end. Add a 5min cached token endpoint for widgets so each widget doesn't trigger its own refresh. Touch points: `internal/auth/`, `web/widgets/token.ts`.

Six blocks beats six paragraphs because every step has a number a reviewer can point at.

## When to stop early

If a thought reveals the question was wrong (wrong scope, missing requirement, blocked by an unknown), write one more Thought summarising the blocker, then `### Final` stating "blocked: <reason>, need <thing>". Don't keep generating thoughts to look thorough — half-finished structured reasoning is fine; pretending to finish is not.

## Conditional References

- [patterns.md](references/patterns.md) — read for calibrated thought-count estimates by problem type, and copy-paste templates for bug diagnosis, architecture decisions, and multi-constraint tradeoffs.

## Anti-patterns

- Numbering stream-of-consciousness sentences as "thoughts" to hit a count.
- Writing `### Final` and then continuing with more thoughts. Final is terminal.
- Using `(revises N)` to extend a thought instead of correct it. New direction = new thought, not a revision.
- Branches that never resolve. Every branch must either be picked, rejected (with one-line reason), or explicitly deferred in Final.