umputun avatar

thinking-tools

Analytical thinking tools - dialectic analysis, bias elimination, codex consultation

GitHub stars
497

Install

/plugin install thinking-tools@umputun-cc-thingz

Run it inside Claude Code after adding the marketplace with /plugin marketplace add umputun/cc-thingz.

Contents

Discovered from source

Skills 3

Ask Codex

Consult OpenAI Codex as a second opinion for investigation, debugging, or review tasks.

Activation Triggers

Explicit:

  • "ask codex", "check with codex", "codex review"
  • "what does codex think", "get codex opinion"
  • "consult codex", "run codex on this"

Automatic (last resort — stuck detection):

  • 4+ failed attempts at the same bug fix or investigation
  • completely out of ideas, all reasonable approaches exhausted
  • going in circles with no progress despite multiple different strategies

Workflow

Step 1: Check Availability

Run which codex to verify the CLI is installed. If not found, inform the user and stop.

Step 2: Build Context

Gather context from the current conversation:

  1. What's the problem/question — summarize in 2-3 sentences
  2. What we know — relevant files, error messages, behavior observed
  3. What we tried — approaches attempted and why they failed (if applicable)
  4. Specific question — what exactly codex should analyze or answer

Codex does NOT auto-load Claude Code's memory files — it only reads AGENTS.md. To give Codex the same project context Claude follows, prepend the memory-load preamble described in Step 3.

Step 3: Construct Prompt

Build a focused prompt. Do NOT dump entire files — codex has full project access and can read them itself. Provide file paths and line references so codex knows where to look.

Prepend a memory-load preamble. Codex auto-loads only AGENTS.md; it does NOT read Claude Code's memory files (CLAUDE.md, CLAUDE.local.md, .claude/rules/, ~/.claude/CLAUDE.md), so the project conventions Claude follows are invisible to Codex unless you tell it to read them. Prepend this line to the prompt:

First read these project guidance files if present: <ABS_HOME>/.claude/CLAUDE.md, CLAUDE.md, CLAUDE.local.md, .claude/rules/
  • Resolve <ABS_HOME> to the absolute home path (run echo $HOME, e.g. /home/<user>) and write the literal path — do NOT leave the string $HOME in the prompt. Whether $HOME expands depends on how the prompt is passed to Codex, and Codex may open the file with a non-shell tool that never expands it, so only a literal absolute path is reliable.
  • No @ prefix — @file is inert in codex exec (literal text, not an import).
  • The project-relative paths resolve against Codex's working directory; Codex skips any that don't exist.

Template for investigation/debug:

# [Investigation/Debug] Request

## Problem
[2-3 sentence description]

## Context
- Files: [path/to/file.go:lineNumber, ...]
- Observed: [what's happening]
- Expected: [what should happen]

## What We Tried
[List approaches and outcomes, or "First consultation" if fresh question]

## Question
[Specific, focused question for codex to answer]

Provide:
1. Root cause analysis (if debugging)
2. Concrete recommendation with file:line references
3. Why previous approaches failed (if applicable)

Keep response focused and actionable.

Template for code review (adversarial):

When asked for a code review, use this adversarial prompt that requires structured JSON output:

<role>
You are performing an adversarial code review.
Your job is to break confidence in the change, not to validate it.
</role>

<task>
Review the provided changes as if you are trying to find the strongest reasons
this change should not ship yet.
Scope: [files and changes to review — paths, branch diff, or description]
Focus: [specific area if user specified one, otherwise "general"]
</task>

<operating_stance>
Default to skepticism.
Assume the change can fail in subtle, high-cost, or user-visible ways until
the evidence says otherwise. Do not give credit for good intent or partial fixes.
If something only works on the happy path, treat that as a real weakness.
</operating_stance>

<attack_surfaces>
Prioritize failures that are expensive, dangerous, or hard to detect:
- auth, permissions, tenant isolation, and trust boundaries
- data loss, corruption, duplication, and irreversible state changes
- rollback safety, retries, partial failure, and idempotency gaps
- race conditions, ordering assumptions, stale state, and re-entrancy
- empty-state, nil, timeout, and degraded dependency behavior
- version skew, schema drift, migration hazards, and compatibility regressions
- observability gaps that would hide failure or make recovery harder
</attack_surfaces>

<finding_bar>
Report only material findings. No style feedback, naming nitpicks, or speculative
concerns without evidence. Each finding must answer:
1. What can go wrong?
2. Why is this code path vulnerable?
3. What is the likely impact?
4. What concrete change would reduce the risk?
Prefer one strong finding over several weak ones.
</finding_bar>

<grounding_rules>
Every finding must be defensible from actual code you can see.
Do not invent files, lines, code paths, or runtime behavior you cannot support.
If a conclusion depends on an inference, state that explicitly and keep the
confidence score honest.
</grounding_rules>

<structured_output>
Return ONLY valid JSON. Example with concrete values:
{
  "verdict": "needs-attention",
  "summary": "auth middleware skips token validation on retry paths",
  "findings": [
    {
      "severity": "high",
      "title": "token validation bypassed on retry",
      "body": "retryHandler re-enters serveHTTP without revalidating the bearer token, allowing expired tokens through on transient failures",
      "file": "internal/auth/middleware.go",
      "line_start": 42,
      "line_end": 55,
      "confidence": 0.85,
      "recommendation": "move token validation before the retry loop entry point"
    }
  ],
  "next_steps": ["add test for expired-token retry scenario"]
}

Allowed values:
- verdict: "approve" or "needs-attention"
- severity: "critical", "high", "medium", or "low"
- confidence: 0.0 to 1.0

Use "needs-attention" if there is any material risk worth blocking on.
Use "approve" only if you cannot support any substantive finding.
</structured_output>

Step 4: Execute Codex

Run codex in background (it takes 2-5 minutes for complex analysis):

codex exec ${CODEX_MODEL:+--model=$CODEX_MODEL} \
  --sandbox read-only \
  -c model_reasoning_effort="xhigh" \
  -c stream_idle_timeout_ms=600000 \
  "prompt here" < /dev/null

Execution rules:

  • Always end the invocation with < /dev/null (as shown). codex exec reads stdin to append a <stdin> block even when the prompt is a positional arg, so an inherited open pipe (common under a background launch) never closes and codex blocks forever on "Reading additional input from stdin…"; /dev/null gives immediate EOF.
  • Always use run_in_background: true in Bash tool
  • Monitor with BashOutput every 15-20 seconds
  • Be patient during reasoning phase (1-3 minutes of silence is normal)
  • Total timeout: 10 minutes for standard, 15 for complex

Flags:

  • --sandbox read-only — codex can read all project files but cannot modify anything
  • ${CODEX_MODEL:+--model=$CODEX_MODEL} — the model comes from the user's ~/.codex/config.toml; it is overridden only when CODEX_MODEL is set. Keep this expansion unquoted so it disappears when the variable is unset
  • model_reasoning_effort="xhigh" — deepest reasoning tier

Step 5: Present Results

  1. Extract codex's analysis — skip session info, token counts, prompt echo
  2. Parse structured output — for reviews, codex returns JSON; parse and present as structured findings
  3. Add your assessment — agree, disagree, or note caveats
  4. STOP and ask — do NOT apply any fixes or changes without explicit user approval

For investigation/debug responses (unstructured):

**Codex Analysis:**

[Codex's response — cleaned up and formatted]

---

**Assessment:** [Your 2-3 sentence evaluation]

**Proposed action:** [What codex suggests — awaiting approval]

For review responses (structured JSON):

Parse the JSON output and present findings sorted by severity, filtered by confidence:

**Codex Review: [verdict]**
[summary]

**Findings** (N issues):

1. **[critical]** title (confidence: 0.9)
   file.go:42-55
   [body]
   → [recommendation]

2. **[high]** title (confidence: 0.8)
   ...

**Next steps:** [list]

---

**Assessment:** [Your evaluation — which findings are valid, which are false positives]
  • skip findings with confidence < 0.3 (likely noise)
  • group by severity: critical → high → medium → low
  • if verdict is "approve" and no findings, just say "codex found no material issues"

CRITICAL: After presenting findings, STOP. Do not apply fixes, do not touch files, do not start implementing suggestions. Explicitly ask the user what to do next. Codex findings are input for discussion, not automatic work orders.

Important Rules

  • Read-only always — codex analyzes, we implement. Never let codex edit files.
  • Don't duplicate files — codex has full project access. Provide paths, not content.
  • Focused prompts — specific questions get better answers than broad "review everything".
  • Background execution — always run in background to avoid timeout issues.
  • One question at a time — if multiple concerns, run separate codex queries.
  • Critical thinking — codex can be wrong. Evaluate its suggestions before implementing.

When NOT to Use

  • Simple questions you already know the answer to
  • Tasks where the solution is clear and just needs implementation
  • File searches or codebase navigation (use Grep/Glob instead)

Troubleshooting

  • Codex not found: which codex — install via npm install -g @openai/codex
  • Authentication: codex login if getting auth errors
  • Timeout: increase stream_idle_timeout_ms for complex analyses
  • Off-target response: refine prompt with more specific file:line references
  • Hangs on "Reading additional input from stdin…": the invocation is missing the < /dev/null stdin redirect — add it (see Step 4).

Dialectic Analysis

Objective analysis of a statement by running two agents with opposing goals in parallel, then synthesizing findings.

Process

Step 1: Launch Parallel Agents

CRITICAL: Both Task tool calls MUST be in a single message for true parallel execution. Do NOT use run_in_background. Do NOT launch sequentially. Foreground agents in the same message run in parallel and block until both complete.

Agent 1 (Thesis) — find all POSITIVE evidence:

  • what works well, improvements, correct patterns
  • supporting facts, proof the statement is TRUE
  • benefits, strengths, successful outcomes

Agent 2 (Antithesis) — find all NEGATIVE evidence:

  • what's problematic, issues, risks, anti-patterns
  • edge cases, proof the statement is FALSE
  • weaknesses, failure modes, hidden costs

Both agents must provide specific file paths and line numbers when analyzing code.

Step 2: Synthesize

After both agents complete, synthesize findings into an objective conclusion:

  • weigh evidence from both sides
  • identify where thesis and antithesis agree (strongest signal)
  • note unresolved tensions

Step 3: Verify

CRITICAL — after presenting the synthesis, verify it against actual implementation:

  • read the specific files and line numbers referenced by both agents
  • confirm the evidence cited actually exists in the codebase
  • check the implementation flow matches the claims made
  • verify the synthesis accurately reflects the actual code context
  • identify any misinterpretations or missing context from agent reports
  • revise synthesis if verification reveals inaccuracies

Use Cases

Architecture decisions:

/thinking-tools:dialectic this microservice split improves maintainability

Bug analysis:

/thinking-tools:dialectic the connection pool fixes the timeout issue

Performance claims:

/thinking-tools:dialectic caching reduced database load by 80%

Refactoring safety:

/thinking-tools:dialectic extracting this interface simplifies testing

Code review:

/thinking-tools:dialectic this implementation is thread-safe

Review changes:

/thinking-tools:dialectic review the changes in server.go

Key Principles

  • Eliminate confirmation bias — examining both sides simultaneously prevents anchoring on the first conclusion
  • Evidence-based — agents must cite specific files, lines, and facts, not general claims
  • Verification required — synthesis must be checked against actual code before presenting
  • Objective conclusion — the goal is truth, not winning either side

Root Cause Investigator

Apply systematic 5-Why methodology to identify fundamental root causes of issues rather than treating symptoms. Guide thorough investigation through structured evidence gathering and analysis.

Activation Triggers

  • errors, bugs, or unexpected behavior
  • build failures or test failures
  • performance issues or degradation
  • integration problems
  • any "it's not working" scenarios

The 5-Why Methodology

Systematically ask "why" five times to drill down to root cause:

  1. Why #1: identify immediate cause (symptoms)
  2. Why #2: uncover process/workflow issues
  3. Why #3: find system-level problems
  4. Why #4: discover design/architecture issues
  5. Why #5: reveal fundamental root cause

Investigation Workflow

1. Gather Initial Context

Collect information about the issue:

## Issue Summary
[brief description of reported problem]

## Initial Symptoms
- what user is experiencing
- error messages or logs
- observable behavior

## Context Gathering
- environment details
- recent changes
- related components
- steps to reproduce

2. Apply 5-Why Analysis

Structure the investigation with progressive depth:

## 5-Why Analysis

### Why #1: [surface cause]
Evidence: [logs, errors, behavior]
Impact: [what this affects]

### Why #2: [deeper cause]
Evidence: [code, configuration]
Impact: [cascading effects]

### Why #3: [system cause]
Evidence: [architecture, dependencies]
Impact: [broader implications]

### Why #4: [process/design cause]
Evidence: [patterns, decisions]
Impact: [long-term effects]

### Why #5: [root cause]
Evidence: [fundamental issue]
Impact: [core problem]

3. Identify Root Cause

Document the fundamental issue requiring attention:

## Root Cause Identified
[the fundamental issue that needs addressing]

## Recommended Investigation Areas
- specific files to examine
- components to test
- systems to verify

Investigation Principles

  1. Avoid solution bias - focus on understanding before fixing
  2. Gather evidence - don't assume, verify with data
  3. Consider multiple causes - issues often have multiple contributing factors
  4. Document findings - clear documentation prevents repeat issues
  5. Think systemically - consider broader implications
  6. Question assumptions - challenge "it should work" thinking
  7. Use version control - check when issue was introduced

Using Reference Materials

Load reference files as needed during investigation:

  • references/patterns.md - common root cause patterns by category (configuration, race conditions, resource exhaustion, integration failures, build/deployment issues)
  • references/techniques.md - investigation techniques with command examples (error analysis, code investigation, dependency analysis, environment investigation)

Best Practices

  • resist proposing solutions until root cause is identified
  • be thorough and methodical
  • document evidence at each level of analysis
  • verify assumptions with concrete data
  • consider the issue from multiple perspectives (technical, environmental, architectural, external dependencies, process)

The goal is to find the fundamental cause, not just fix symptoms.

Sponsors

Details

Marketplace
umputun/cc-thingz
Source
plugins/thinking-tools
Category
Community

More from umputun/cc-thingz

All 7