problem-solving-pro · diff
git:20261008.1df99d6 to git:20261008.a03a4fa
52 added, 13 removed. Audit A to A.
---
name: problem-solving-pro
description: |
Systematic problem-solving toolkit: root cause analysis, hypothesis testing,
debugging strategies, critical thinking frameworks. Use when user says "solve",
"analyze", "diagnose", "figure out", "what's wrong", "root cause",
"why is this happening", "I'm stuck", "break down", "decompose", "structure",
"tại sao bị vậy", "tìm nguyên nhân", "phân tích", "giải quyết", "bị kẹt",
- "không biết làm sao", or describes any problem that needs structured decomposition.
+ "không biết làm sao", "làm tiếp", or describes any problem that needs structured decomposition.
For bugs and other changes to a codebase, use code-solving instead.
---
# Goal
Help users solve complex problems systematically using proven frameworks — turning vague issues into structured analyses with actionable recommendations.
# problem-solving-pro
- Comprehensive structured problem-solving framework for tackling any complex challenge. Contains a 7-step methodology, 15 decomposition frameworks, 8 prioritization techniques, 12 analysis tools, 12 cognitive biases with debiasing strategies, 10 communication patterns, 12 mental models, and 10 team dynamics patterns. Searchable database with reasoning-based recommendations that adapts to your specific problem type.
+ Comprehensive structured problem-solving framework for tackling any complex challenge. Contains a 7-step methodology, 18 decomposition frameworks, 8 prioritization techniques, 15 analysis tools, 12 cognitive biases with debiasing strategies, 10 communication patterns, 13 mental models, and 10 team dynamics patterns. Searchable database with reasoning-based recommendations that adapts to your specific problem type. Requests can be in English or Vietnamese (with or without accents).
## Prerequisites
**IMPORTANT: Detect the correct Python command first.** Some systems use `python3`, others use `python`. Run:
```bash
python3 --version 2>/dev/null || python --version
```
Use whichever command succeeds (`python3` or `python`) for ALL script calls below. If the system only has `python` (common on Windows), substitute `python` everywhere you see `python3` in this document.
If Python is not installed at all, install it based on user's OS:
**macOS:**
```bash
brew install python3
```
**Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install python3
```
**Windows:**
```powershell
winget install Python.Python.3.12
```
> **Note:** On Windows, Python 3 is typically available as `python` (not `python3`).
---
## Running the Scripts
Run every command from the **project root** with the path shown, e.g.
`python3 .agents/skills/problem-solving-pro/scripts/search.py ...` (the installer adjusts this path for
your AI tool). Saved plans and journals are written to the project, never inside the skill folder.
Saving again never overwrites files that already exist (they hold your notes); add `--force`
to replace them.
### Passing the user's text
When the query is the user's own words (a request, an error message, a pasted log), pass it on
stdin with `--stdin` instead of quoting it, so quotes, backticks and `$` never reach the shell:
```bash
python3 .agents/skills/problem-solving-pro/scripts/search.py --stdin --plan <<'TASK'
<the user's text, unchanged>
TASK
```
In PowerShell (keep `'@` at the start of its line):
```powershell
$OutputEncoding = [Text.UTF8Encoding]::new()
@'
<the user's text, unchanged>
'@ | python .agents/skills/problem-solving-pro/scripts/search.py --stdin --plan
```
---
## How to Use This Workflow
When user requests problem-solving help (analyze, solve, diagnose, decide, structure, decompose, plan, strategy, recommendation), follow this workflow:
### Step 1: Understand the Problem
Extract key information from user's problem description:
- **Context** (→ `--category`): Business performance, market entry, organizational change, product, cost reduction, innovation, crisis, data/analytics, partnership/M&A, policy
- **Type** (→ `--type`): Diagnostic, opportunity, design, prediction, negotiation — or by complexity: well-structured, ill-structured, wicked
- **Keywords**: revenue, growth, decline, entry, change, innovation, cost, crisis, etc.
- **Context**: Industry, scale, time pressure, stakeholder dynamics
### Step 2: Generate Problem-Solving Plan (REQUIRED)
**Always start with `--plan`** to get comprehensive recommendations with reasoning:
```bash
python3 .agents/skills/problem-solving-pro/scripts/search.py "<problem_description>" --plan [-p "Project Name"]
```
**Classify it yourself when you can** — you understand the problem better than keyword matching:
- `--type <type>` — how the problem is shaped: Well-Structured, Ill-Structured, Wicked, Diagnostic, Opportunity, Design, Prediction, Negotiation
- `--category "<context>"` — selects the reasoning rule (decomposition, analyses, communication style): Business Performance, Market Entry Strategy, Organizational Change, Product Development, Cost Reduction, Innovation / Disruption, Crisis / Turnaround, Data / Analytics Problem, Partnership / M&A, Policy / Public Sector
- Omit either flag to auto-detect. The plan reports what it used as **Type** and **Context**.
+ Omit either flag to auto-detect (English and Vietnamese keywords). The plan reports what it used as
+ **Type** and **Context** and whether each was set by you, auto-detected, a weak guess or no match.
+ When nothing matched, the plan starts with a note such as "No problem type matched clearly. Re-run
+ with `--type` (...)" listing the values: re-run with the flag instead of presenting generic defaults.
```bash
python3 .agents/skills/problem-solving-pro/scripts/search.py "revenue down 20% despite market growth" --plan --type Diagnostic --category "Business Performance"
```
This command:
- 1. Classifies the problem type automatically
- 2. Searches across all 9 knowledge domains in parallel
- 3. Applies reasoning rules to select best frameworks and tools
- 4. Returns a complete solving plan: methodology, decomposition, analysis, communication, mental models, bias warnings
- 5. Includes anti-patterns to avoid and a problem-solving checklist
+ 1. Classifies the problem type and context (or uses `--type` / `--category`)
+ 2. Applies the context's reasoning rule: decomposition, analyses, communication style, decision rules
+ 3. Picks the mental models and bias warnings named for this context and problem type, then fills up from search
+ 4. Returns a solving plan: the 7 steps with their quality gates, decomposition, prioritization, analysis,
+ decision rules, communication, mental models, bias warnings, anti-patterns and a checklist
+ 5. Ends with a **Next Steps** table for the depth used: present it once, do not add another
+ **Depth** (`--depth`) changes what the plan contains:
+
+ | Depth | Contents |
+ |-------|----------|
+ | `quick` | One screen: classification, process, decomposition, main analysis, 2 mental models, 2 biases, anti-patterns, first move |
+ | `standard` (default) | Adds the 7 steps with quality gates, prioritization, decision rules, communication, 3 models, 3 biases, team, checklist |
+ | `deep` | Adds more alternatives, 5 mental models with danger zones, 4 biases with warning signs, pitfalls per step, strengths and limits of the analysis |
+ | `executive` | Everything in `deep` plus an **Executive Summary (SCR)**, **Key Risks** and **Decision Needed** |
+
+ `--json` with `--plan` prints the plan as JSON (with `--persist`, a `saved` entry lists the files).
+
**Example:**
```bash
python3 .agents/skills/problem-solving-pro/scripts/search.py "revenue declining 20% despite market growth" --plan -p "Revenue Recovery"
```
### Step 2b: Persist Problem-Solving Plan
To save the plan for reference:
```bash
python3 .agents/skills/problem-solving-pro/scripts/search.py "<problem>" --plan --persist -p "Project Name"
```
This creates:
- - `solving-plans/project-name/PLAN.md` — Complete problem-solving plan
+ - `solving-plans/project-name/PLAN.md` — Complete problem-solving plan (with the original request)
+ Add `--step-docs` for a workspace with one file per step (`00-OVERVIEW.md` with a **Done?** column,
+ `01-PROBLEM-DEFINITION.md` pre-filled with the request, ... `07-RECOMMENDATION.md`, `BIAS-WARNINGS.md`,
+ `DECISION-LOG.md`). Each step file starts with what to do and its **Done when** quality gate.
+
+ ### Step 2c: Resume Later
+
+ A saved workspace is how work continues in a new session (`/solve.resume`):
+
+ ```bash
+ python3 .agents/skills/problem-solving-pro/scripts/search.py --status [-p "<short-name>"]
+ python3 .agents/skills/problem-solving-pro/scripts/search.py --done <step> -p "<short-name>"
+ ```
+
+ `--status` shows each step's file, whether it was filled in and whether it is done, then the **next**
+ step with what to do, its quality gate and pitfalls. Without `-p`, it picks the workspace whose name or
+ request matches the text given on stdin, else the most recently changed one. `--done <step>` (1-7 or a
+ name: define, decompose, prioritize, plan, analyze, synthesize, communicate) ticks the step in
+ `00-OVERVIEW.md`; `--undone <step>` reopens it. Read the files of finished steps before continuing, and
+ tick a step only when its file shows the work.
+
### Step 3: Deep-Dive Domain Searches
Use when the plan's recommendation needs more detail, OR when user asks about a specific topic (e.g., "how do I do a root cause analysis?"):
```bash
python3 .agents/skills/problem-solving-pro/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
```
**When to use domain searches:**
| Need | Domain | Example |
|------|--------|---------|
| Understand the methodology steps | `steps` | `--domain steps "define problem"` |
| Classify the problem | `problem-types` | `--domain problem-types "wicked systemic"` |
| Choose decomposition framework | `decomposition` | `--domain decomposition "MECE logic tree"` |
| Pick prioritization technique | `prioritization` | `--domain prioritization "impact feasibility"` |
| Select analysis tools | `analysis` | `--domain analysis "root cause benchmark"` |
| Identify cognitive biases | `biases` | `--domain biases "confirmation anchoring"` |
| Structure communication | `communication` | `--domain communication "pyramid executive"` |
| Apply mental models | `heuristics` | `--domain heuristics "first principles inversion"` |
| Improve team dynamics | `team` | `--domain team "red team brainstorm"` |
### Step 4: Apply the Framework
Guide the user through the recommended process:
1. **Define**: Help craft a precise problem statement
2. **Decompose**: Build the recommended logic tree (MECE)
3. **Prioritize**: Apply 80/20 to focus on what matters
4. **Plan**: Design specific analyses for priority issues
5. **Analyze**: Guide data gathering and hypothesis testing
6. **Synthesize**: Extract 'so what' insights and build the argument
7. **Communicate**: Structure the recommendation for the audience
---
## Search Reference
### Available Domains
| Domain | Records | Use For | Example Keywords |
|--------|---------|---------|------------------|
| `steps` | 7 | Understanding each step of the methodology | define, disaggregate, prioritize, analyze, synthesize, communicate |
| `problem-types` | 8 | Classifying the type of problem | diagnostic, opportunity, wicked, prediction, negotiation, design |
- | `decomposition` | 15 | Choosing how to break down the problem | issue tree, hypothesis tree, MECE, profitability, process, scenario |
+ | `decomposition` | 18 | Choosing how to break down the problem | issue tree, hypothesis tree, MECE, profitability, process, scenario |
| `prioritization` | 8 | Deciding where to focus effort | pareto, impact-feasibility, sensitivity, dot-voting, MoSCoW, weighted |
- | `analysis` | 12 | Selecting analytical methods | benchmark, root cause, regression, scenario, fermi, A/B test, pre-mortem |
+ | `analysis` | 15 | Selecting analytical methods | benchmark, root cause, regression, scenario, fermi, A/B test, pre-mortem |
| `biases` | 12 | Identifying thinking errors to avoid | confirmation, anchoring, sunk cost, groupthink, overconfidence, framing |
| `communication` | 10 | Structuring findings and recommendations | pyramid, SCR, action titles, BLUF, one-page, storytelling, day-1 answer |
- | `heuristics` | 12 | Applying mental models to the problem | first principles, inversion, second-order, Bayesian, Occam, leverage |
+ | `heuristics` | 13 | Applying mental models to the problem | first principles, inversion, second-order, Bayesian, Occam, leverage |
| `team` | 10 | Improving team problem-solving effectiveness | red team, brainstorm, psychological safety, hypothesis-driven, workplan |
---
## Example Workflow
**User request:** "Our company's revenue has declined 20% this year despite the market growing. Help me figure out what's going on and what to do about it."
### Step 1: Understand the Problem
- Problem type: Business Performance / Diagnostic
- Complexity: Ill-structured (multiple potential causes)
- Keywords: revenue, decline, market growth, performance gap
- Context: Company underperforming vs market
### Step 2: Generate Problem-Solving Plan (REQUIRED)
```bash
python3 .agents/skills/problem-solving-pro/scripts/search.py "revenue declining 20% despite market growth" --plan -p "Revenue Diagnosis"
```
**Output:** Complete plan with profitability tree decomposition, Pareto prioritization, benchmarking + root cause analysis toolkit, pyramid principle communication, and bias warnings (confirmation bias, anchoring).
### Step 3: Deep-Dive Searches
```bash
# Get decomposition framework details
python3 .agents/skills/problem-solving-pro/scripts/search.py "profitability revenue cost" --domain decomposition
# Get root cause analysis methodology
python3 .agents/skills/problem-solving-pro/scripts/search.py "root cause 5 whys diagnostic" --domain analysis
# Check for relevant biases
python3 .agents/skills/problem-solving-pro/scripts/search.py "confirmation bias anchoring" --domain biases
```
### Step 4: Apply the Framework
Walk the user through:
1. **Define**: "Revenue declined 20% YoY (vs market +5%) — identify root drivers and recommend recovery actions within 90 days"
2. **Decompose**: Profitability tree → Revenue (Price × Volume) → Costs (Fixed + Variable)
3. **Prioritize**: Which branches explain >80% of the decline?
4. **Analyze**: Benchmark against competitors, test hypotheses on each priority branch
5. **Synthesize**: Group findings into themes, extract 'so what' for each
6. **Communicate**: Start with the recommendation (pyramid), support with evidence
**Then:** Synthesize the plan + domain searches into a structured problem-solving approach for the user.
---
## Output Formats
The `--plan` flag supports two output formats:
```bash
# ASCII box (default) - best for terminal display
python3 .agents/skills/problem-solving-pro/scripts/search.py "market entry strategy" --plan
# Markdown - best for documentation
python3 .agents/skills/problem-solving-pro/scripts/search.py "market entry strategy" --plan -f markdown
+
+ # JSON - the plan as data
+ python3 .agents/skills/problem-solving-pro/scripts/search.py "market entry strategy" --plan --json
```
---
## Key Principles
1. **Start with the problem, not the solution** — Invest time in defining and framing before solving
2. **Disaggregate before analyzing** — Break it down MECE before diving into any branch
3. **Prioritize ruthlessly** — 80/20: focus on the vital few issues that drive the answer
4. **Be hypothesis-driven** — State your best guess early, then test it (Day 1 Answer)
5. **So what?** — Every finding must pass the 'so what' test to matter
6. **Answer first** — Lead with the recommendation, support with evidence (Pyramid Principle)
7. **Watch for biases** — Confirmation bias, anchoring, and groupthink are the most dangerous
8. **Iterate** — Update your answer as evidence comes in (Bayesian updating)
9. **Simple first** — Use the simplest analysis that answers the question (Occam's Razor)
10. **Communication is the final product** — The best analysis is worthless if you can't drive action
11. **What you'd have to believe** — When stuck or attached to an idea, ask "what would have to be true for this to be the right answer?" to break framing ruts and rigorously test assumptions.
---
## Constraints
- **Always start with Step 2** (`--plan`) before doing domain searches — the plan provides context for everything else
- **Problem statement must be specific** — reject vague statements; ask for measurable outcomes
- **Keep the logic tree to 3 levels max** — deeper than 3 loses clarity
- **Limit to top 3 priority branches** — 80/20 rule; don't analyze everything
- **When user is vague, ask** — if the problem type is unclear, ask: "What would success look like?" before running the plan
---
## Error Handling
If the Python scripts fail or are unavailable:
1. **Check Python**: Run `python3 --version` or `python --version` — if neither is found, guide the user to install it
2. **Manual fallback**: If scripts cannot run, apply the Key Principles above manually:
- Ask the user to describe the problem → classify the type yourself
- Suggest a decomposition framework (e.g., Issue Tree for diagnostic, Hypothesis Tree for uncertain causes)
- Walk through the 7-step methodology: Define → Decompose → Prioritize → Plan → Analyze → Synthesize → Communicate
- Warn about the 3 most common biases for that problem type
3. **Script errors**: If `search.py` returns no results, try broader keywords or search a different domain
- 4. **Non-English queries**: The knowledge base is English-only. Translate the user's key terms to English before calling `search.py` — this ensures rich results for any language
+ 4. **Non-English queries**: Classification understands English and Vietnamese (with or without accents); the framework content is in English. For other languages, translate the user's key terms to English, or pass `--type` and `--category` yourself
+ 5. **"No ... matched clearly"**: the plan used generic defaults. Re-run with `--type` and `--category` (the note lists the values)