sequential-thinking

Sequential Thinking

The core of this skill is not "writing a few more paragraphs of thought," but rather enabling the AI, when facing complex problems, tokeep advancing, allow corrections, and ultimately converge into a conclusion. The CLI is merely the execution vehicle; the skill itself is responsible for defining when to enter this mode of thinking and how to avoid degrading sequential thinking into loose output.

Mission

This skill is used to process a complex problem into abounded, correctable, and reviewable reasoning process：

• Clarify the problem first, rather than rushing to give an answer
• Allow corrections and adjustments of judgment during the process
• Compare alternative paths when complexity rises, rather than forcing a single line of reasoning
• Converge into conclusions and recommendations within a limited number of steps
• Finally retain a replayable reasoning trace

What it solves is not "being unable to think," but rather "thinking too scattered, concluding too early, and being too hard to review."

Core Capabilities

• Iterative advancement: Break a complex problem into consecutive steps, rather than trying to get a complete answer in one go
• Dynamic correction: When new evidence appears, allow looking back and correcting previous judgments
• Branch comparison: When alternative paths exist, allow comparing before converging
• Context maintenance: Maintain clear problem boundaries and goals during multi-step reasoning
• Conclusion convergence: Ultimately a judgment must be formed, rather than diverging indefinitely

When to Use

Invoke in the following scenarios:

• The problem requires multiple interrelated reasoning steps
• The initial scope or method is unclear, and the problem must first be decomposed before a method is formed
• A comparison must be made among a limited set of candidate solutions, rather than diverging indefinitely
• Existing judgments must be reviewed, identifying loopholes, insufficient evidence, and implicit assumptions
• A replayable, exportable reasoning trace must be left behind

Inapplicable scenarios：

• Simple factual queries
• Tasks that can be completed in a single step
• Problems whose path is already very clear and require no multi-step deduction
• Scenarios of pure brainstorming where convergence is not required for the time being

Working Philosophy

• Find the main problem first, then find the answer: Do not mistake a description of symptoms for root-cause identification
• Allow corrections, rather than stubbornly propping up premises: If you reasoned incorrectly earlier, go back and fix it; do not continue advancing with a wrong premise
• Eliminate complexity first, then pile on solutions: Prioritize identifying the principal contradiction, rather than rushing to give patches
• Advance only one step at each step: The current step only expresses the current judgment, without repeating the entire background
• Ultimately it must land on a conclusion: "I can keep thinking" cannot be treated as the default exit

Installation & Runtime Model

This skill is oriented toward delivering a way of thinking and invocation constraints to agents; the CLI is distributed via npm.

Before use, first ensure the corresponding CLI is installed locally:

npm install -g sequential-thinking-cli

# 或
pnpm add -g sequential-thinking-cli

After installation, use sthink as the command entry point.

CLI Contract

This skill no longer requires the AI to hand-write thought JSON. The execution layer completes it through the CLI main-path actions:

• start
• step
• replay

start

Only four inputs are accepted:

• name
• goal
• mode
• totalSteps

Constraints:

• mode only allows explore、branch、audit
• totalSteps only allows 5 or 8

If you are not sure which mode to choose, use exploreby default. Use branchonly when the task is clearly comparing candidate paths; use audit。

step

Accept only:

• content

The rest of the context should be automatically restored and injected by the runtime.

replay

Used to read a completed session and generate a replay document; if needed, it can additionally be exported to the current directory.

Recommended Workflow

1. 先判断问题是否真的需要 sequential-thinking，而不是默认套用。
2. 如需要，先安装或确认本地已有 npm CLI。
3. 用 `sthink start` 给出 `name`、`goal`、`mode`、`totalSteps`。
4. 用 `sthink step` 逐步推进，每一步只写当前推进内容。
5. 当出现新证据时，允许修正，而不是硬撑旧判断。
6. 到收敛阶段时，必须输出结论、风险与下一步建议。
7. 完成后按需使用 `sthink replay` 生成与导出回放文档。

Examples

The following examples are not meant to make you go back to writing JSON by hand, but to illustrate where this kind of skill is truly valuable:how to advance, how to revise, how to converge。

Example 1: Basic reasoning

sthink start --name "query-diagnosis" --goal "定位查询性能下降的主因" --mode explore --totalSteps 5
sthink step --sessionPath "<session-path>" --content "先不要急着选优化手段。需要先把问题拆成几层：是单条 SQL 退化、接口级 N+1，还是更上层的调用放大。若根因没分清，后面的缓存、索引、重写都可能只是补丁。"
sthink step --sessionPath "<session-path>" --content "从查询日志看，用户详情接口在一次请求里触发了大量重复读取，已经出现明显的 N+1 信号。但还不能直接下结论，因为重复查询也可能只是症状；需要继续确认慢点究竟来自“查询次数过多”，还是“某条关键查询本身很慢”。因此总步数上调一档。"
sthink step --sessionPath "<session-path>" --content "结论可以收敛了：主因是列表页批量加载时触发的 N+1，次因是关联字段缺少索引放大了单次查询成本。优化顺序应该先消除 N+1，再补索引验证尾延迟；这样既先打掉主矛盾，也避免一上来引入缓存复杂度。"

Example 2: Revising premises

sthink step --sessionPath "<session-path>" --content "回看 profiling 结果后，前面的判断需要修正：真正拖垮接口的不是 N+1 本身，而是关联列缺少索引，导致每次关联查询都在放大全表扫描成本。也就是说，N+1 仍然存在，但它不是第一性瓶颈，优先级应该后移。"

Example 3: Decomposing complex changes

sthink start --name "change-impact-analysis" --goal "拆解复杂变更的影响与优先级" --mode explore --totalSteps 5
sthink step --sessionPath "<session-path>" --content "用户一次性提出了多项规则修改，不该把它们当成同一种改动处理。先拆开看：有的是机制原则调整，有的是数值平衡，有的是接口语义变化，还有的是文档与实现脱节。如果不先分型，后面会把“该改 ADR 的”“该改设计文档的”“该补代码契约的”混成一锅。"
sthink step --sessionPath "<session-path>" --content "先做影响矩阵。机制原则类改动通常会回流到 ADR 和 System Design；数值平衡会影响规则表、配置与测试基线；接口语义变化最危险，因为它会悄悄破坏调用方的假设。这里最该警惕的不是改动数量，而是有没有改到“被多个模块默认依赖、但文档里没写清楚”的隐性契约。"
sthink step --sessionPath "<session-path>" --content "可以收敛了：先处理那些会改变系统边界或调用语义的项，再处理数值与体验层面的项。顺序上应优先修正文档与契约，再讨论平衡性；否则后续所有实现和评审都会建立在漂移的前提上。结论不是“先改最显眼的”，而是“先修最容易污染系统认知的”。"

Example 4: Branch comparison

sthink start --name "performance-tradeoff" --goal "比较缓存止血与查询优化的优先级" --mode branch --totalSteps 5
sthink step --sessionPath "<session-path>" --content "方案 A：先引入缓存削峰。好处是见效快、对接口层侵入小，适合先止血；坏处是会把问题从“数据库慢”转成“缓存一致性与失效策略复杂”，如果根因其实是查询设计不合理，这条路容易把偶然复杂度永久留在系统里。与此同时，方案 B：直接做索引优化和查询重写。好处是从根上消除瓶颈，长期结构更干净；代价是需要更仔细验证写入放大、锁竞争和回归风险。这条路更慢，但如果业务模型稳定，通常比提前上缓存更符合简单优先的原则。"

Storage & Export Boundary

• the runtime automatically saves session state and step records
• once completed, a replay document can be generated
• replay supports exporting to the current directory, making it easy to review and reuse

Heuristic Reminders

The following reminders are heuristic questions, not hard constraints. What really matters is that they can help you reduce spinning your wheels and get closer to a conclusion.

• Problem definition reminder: Are you describing the phenomenon now, or locating the root cause?
• Evidence reminder: Is the current judgment based on facts and observations, or on guesses and assumptions?
• Boundary reminder: Does the current problem affect a local module, a single system, or a cross-system structure?
• Complexity reminder: Are you eliminating essential complexity, or adding accidental complexity?
• Convergence reminder: Is the current state already sufficient to form a conclusion, or are you still diverging ineffectively?

Tips

• Do not hand-write thought JSON again; let the CLI runtime handle pacing, persistence, and replay
• Do not treat sequential-thinking as the default mode; call it only when multi-step convergence is truly needed
• If you are not sure about the mode, first use explore
• step of content to express only the current advancing content; do not repeatedly fill in the system context
• If you find that a premise is wrong, revise it explicitly; do not force it through
• When reaching the convergence stage, you should clearly output the conclusion, risks, and next actions
• Only a completed session can execute replay