reasoning-expert
Agent reasoning improvement via Chain-of-Thought (CoT), Tree-of-Thought (ToT) for path exploration, ReAct (Reasoning + Acting), reasoning trace auditing for fallacy detection (circular logic, confirmation bias, premature convergence), and inference traceability maintenance for decision debugging. Use when evaluating agent decision quality, auditing reasoning paths, debugging poor agent outputs, or comparing reasoning patterns across model tiers. Trigger: reasoning, CoT, ToT, ReAct, fallacy detection, evidence audit, agent decision quality. Do NOT trigger for: simple single-file edits, trivial reads, basic CRUD operations.
- License 许可
- MIT
- 最近更新
- 2026-08-27
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- reasoning-expert
- license
- MIT
- metadata
- { "author": "Community", "status": "stable", "version": "1.1", "category": "ai-agents" }
- description
- Agent reasoning improvement via Chain-of-Thought (CoT), Tree-of-Thought (ToT) for path exploration, ReAct (Reasoning + Acting), reasoning trace auditing for fallacy detection (circular logic, confirmation bias, premature convergence), and inference traceability maintenance for decision debugging. Use when evaluating agent decision quality, auditing reasoning paths, debugging poor agent outputs, or comparing reasoning patterns across model tiers. Trigger: reasoning, CoT, ToT, ReAct, fallacy detection, evidence audit, agent decision quality. Do NOT trigger for: simple single-file edits, trivial reads, basic CRUD operations.
02 资源文件 3
- 参考文档evals/evals.json2.9 KB
- 参考文档references/fallacy-reference.md832 B
- 参考文档references/react-pattern.md882 B
03 SKILL.md 正文
Reasoning Expert
CoT, ToT, ReAct patterns. Fallacy detection. Reasoning trace audits.
Reasoning Techniques
| Technique | Use Case |
|---|---|
| Chain-of-Thought (CoT) | Multi-step problems, debugging, analysis |
| Tree-of-Thought (ToT) | Multiple options, compare alternatives |
| ReAct | Tool-using agents (think -> act -> observe) |
Fallacy Detection
Circular Logic — "X is correct because X is standard"
Fix: Demand external evidence, not self-reference.
Confirmation Bias — reads 3 supporting files, skips contradicting one
Fix: "What would prove this wrong?"
Premature Convergence — locks on first solution, <=1 alternative
Fix: "List 3 approaches. Pick best. State why others rejected."
Authority Over-Reliance — "docs say X" without questioning recency
Fix: Cross-validate: docs vs code vs tests.
Causal Confusion — "correlation = causation" in debugging
Fix: Reproduce with suspected cause reverted.
Premise Acceptance — accepts user claims about third-party software capabilities without verification
Fix: Verify against official docs before planning. Flag unverified claims as [UNVERIFIED PREMISE].
- CLAIM: "Tool X has feature Y" → verify before accepting.
- REQUIREMENT: "We need feature Y from Tool X" → verify Tool X has it before planning.
- Both require verification. When ambiguous, treat as REQUIREMENT (verify + find alternatives if needed).
Reasoning Audit Report
## Reasoning Trace Audit
Agent: {id} | Model: {model}
### Fallacies Detected
- [{type}] at step {N}: {quote}
Impact: {effect on conclusion}
Fix: {correct approach}
### Evidence Score
- STATIC: {N} | EXECUTED: {N} | INFERRED: {N} | BLOCKED: {N}
- Quality: {A-F}
### Recommendations
- {actionable fix}
Constraints
- NEVER use CoT for trivial tasks (reads, single-file edits)
- NEVER skip evidence labeling (STATIC/EXECUTED/INFERRED)
- ALWAYS explore >=3 alternatives before converging
- NEVER accept "docs say X" without checking source freshness
- ALWAYS verify user claims about external tool capabilities before planning implementation
Overview
Structured reasoning patterns (Chain-of-Thought, Tree-of-Thought, ReAct) for AI agent decision quality. Covers fallacy detection (circular logic, confirmation bias, premature convergence), evidence labeling (STATIC/EXECUTED/INFERRED), reasoning trace auditing, and model-appropriate technique selection.
Quick Reference
| Scenario | Technique |
|---|---|
| Multi-step problem solving (debug, analysis) | Chain-of-Thought (CoT) — linear decomposition |
| Multiple approaches, need to compare | Tree-of-Thought (ToT) — branch exploration |
| Agent needs to use tools and observe results | ReAct — think → act → observe loop |
| Auditing why an agent made a bad decision | Reasoning trace audit with fallacy detection and evidence score |
| Simple read or single-file edit | No technique (CoT wastes tokens on trivial tasks) |
Workflow
- Classify task complexity — Trivial (0t), Simple (≤500t), Moderate (≤2000t), Complex (≤5000t).
- Select technique — CoT for linear multi-step, ToT for branching alternatives, ReAct for tool-using agents.
- Explore ≥3 alternatives — List approaches; pick best; document why others are rejected.
- Label evidence —
STATIC(read file),EXECUTED(ran command),INFERRED(logical deduction),BLOCKED(source missing). Seeoperating-protocolfor canonical labels. - Detect fallacies — Check for circular logic, confirmation bias, premature convergence, authority over-reliance, causal confusion.
- Generate reasoning audit — Record fallacies detected, evidence score (A-F), and actionable fixes.
- Verify solution — Does the conclusion follow from the evidence? Could a different conclusion be drawn from the same evidence?
References
| Resource | URL | Last verified |
|---|---|---|
| Chain-of-Thought Prompting (Wei et al.) | https://arxiv.org/abs/2201.11903 | 2025-05 |
| Tree-of-Thought (Yao et al.) | https://arxiv.org/abs/2305.10601 | 2025-05 |
| ReAct: Synergizing Reasoning and Acting (Yao et al.) | https://arxiv.org/abs/2210.03629 | 2025-05 |
| Cognitive Biases Cheatsheet | https://betterhumans.pub/cognitive-bias-cheat-sheet-55a472476b18 | 2025-05 |
Verification Checklist
- [ ] Task complexity classified before selecting technique (CoT/ToT/ReAct)
- [ ] At least 3 alternatives explored before converging on solution
- [ ] All claims labeled with evidence tier per operating-protocol:
STATIC,EXECUTED,INFERRED,BLOCKED - [ ] Reasoning trace checked for fallacies: circular logic, confirmation bias, premature convergence
- [ ] CoT not used for trivial tasks (reads, single-file edits) to avoid token waste
- [ ] Conclusion re-verified: could different evidence support a different conclusion?
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Agent converges on wrong approach too quickly | Premature convergence — only 1 alternative evaluated | Force ≥3 alternatives before selecting; document explicit rejection rationale |
| Reasoning trace contradicts actual code behavior | Evidence mislabeled: INFERRED used when code was not read |
Re-label evidence as V only after reading/running code; re-verify assumptions |
| Model applies CoT on trivial read task | Task complexity misclassified as complex | Skip CoT for tasks with <100 lines changed or single-file edits |
| Reasoning audit shows no fallacies but answer is still wrong (known issue: model hallucinates reasoning) | Model fabricates plausible-sounding intermediate steps | Add verification step: each CoT step must cite specific evidence (file:line); enforce evidence gate before conclusion |
| Agent accepts user claim about third-party tool capability without checking docs | Premise Acceptance fallacy — user stated capability as fact | Flag as [UNVERIFIED PREMISE]; verify against official docs before planning; BLOCK planning if capability does not exist |
| [WARN] Agent cites file:line evidence but the line was modified since read (staleness gotcha) | File changed between read and assertion; agent did not re-read before citing | Re-read file immediately before citing evidence; add "last_read_timestamp" to evidence claim |
04 同仓库更多 Skills
web-browsing-agent-expert
Web browsing for AI agents: driving a headless browser (Playwright, Puppeteer) from agent tooling, navigation and page-state grounding, DOM extraction and structured data capture, form interaction, session and cookie management, anti-bot mitigation awareness, and safe browsing rules (no PII exfiltration, respect robots and terms). Use when building a browsing tool or MCP server for an agent, teaching an agent to navigate and read web pages, extracting structured content from dynamic sites, or handling login walls and pagination in agent workflows. Trigger: web browsing agent, headless browser, Playwright MCP, Puppeteer, browser automation for agents, DOM extraction, page navigation, session management. Do NOT trigger for: end-to-end UI testing of an application (use playwright-expert); writing standalone scraping scripts for data pipelines (use python-expert); fetching a single public URL (use the fetch tool).
vector-databases
Design and operate vector databases for cloud-native AI features. Use when selecting between pgvector, Pinecone, or Weaviate for AI context layer or integration-hub; designing embedding schemas and index parameters; implementing ANN search with metadata filtering; managing embedding model versions; optimizing query latency; or debugging low retrieval quality. Pairs with rag-architecture for pipeline design and postgres-database-expert for pgvector specifics. Trigger: vector database, pgvector, Pinecone, Weaviate, embedding, ANN search, HNSW, cosine similarity. Do NOT trigger for: relational SQL optimization, standard PostgreSQL schema design, Redis caching.
typescript-expert
Full-stack TypeScript stack for modern projects: frontend SSR/CSR with Next.js 14 App Router and React, backend APIs with Node.js (Express/Fastify), state management with Zustand/Redux Toolkit, unit and integration testing with Vitest/Jest + React Testing Library + MSW, and static analysis with ESLint/Prettier/tsc. Use when building React components or hooks, implementing Next.js App Router or Server Components, writing Node.js REST API handlers, implementing middleware (auth, rate-limit, logging), managing client state (Zustand/RTK), writing frontend/backend tests, or running TypeScript linting/type checks. Trigger: TypeScript, Next.js, React, Zustand, Node.js, Express, Fastify, MSW, Vitest. Do NOT trigger for: Python backend development, Go microservices, iOS/mobile development.
tool-usage
Guide correct tool selection, design, and orchestration for AI agents. Use when choosing between dedicated vs Bash tools, designing MCP tool interfaces, naming tool parameters, handling tool response limits, orchestrating parallel vs sequential calls, evaluating tool accuracy, applying ACI design principles, selecting workflow patterns, or reading/filtering/transforming/generating structured data (JSON, YAML, CSV, TOML, XML). Trigger: tool selection, MCP tool design, orchestration, ACI, parallel execution, composite tool, structured data, jq, yq, dasel, mlr, csvkit. Do NOT trigger for: writing application business logic, domain-specific development (route to domain skill), database migrations.
token-efficiency
Enforce token-efficient output, compression, caching, and model routing. Use when calibrating response verbosity, applying compression strategies to logs or RAG chunks, routing tasks to the right model tier, setting thinking budgets, enforcing word limits, compressing context before reinitiation, applying KV-cache ordering, masking tool output observations, or applying clarification-first protocol before irreversible actions. Trigger: token efficiency, compression, model routing, thinking budget, KV-cache, clarification protocol. Do NOT trigger for: non-agent tooling, CI/CD pipeline scripting, infrastructure provisioning.
time-series-db
Time-series database patterns for cloud-native metrics and analytics: TimescaleDB, InfluxDB, and Amazon Timestream selection; continuous aggregates, retention policies, downsampling, and integration with Prometheus/Grafana. Use when storing business metrics over time, building custom business dashboards, designing high-frequency event storage, or querying time-bucketed aggregations. Trigger: time-series, TimescaleDB, InfluxDB, Prometheus, Grafana, hypertable, continuous aggregate, retention policy. Do NOT trigger for: relational PostgreSQL schema design, NoSQL document stores, Kafka event streaming.