Skip to content

Commit 06d74ff

Browse files
GiggleLiuGiggleLiu
committed
feat(skill): add find-solver skill — interactive problem-to-solver guide
1 parent f8e668b commit 06d74ff

1 file changed

Lines changed: 304 additions & 0 deletions

File tree

‎.claude/skills/find-solver/SKILL.md‎

Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
---
2+
name: find-solver
3+
description: Interactive guide — match a real-world problem to a library model, explore reduction paths, recommend solvers (built-in + external), and generate a solution doc
4+
---
5+
6+
# Find Solver
7+
8+
Guide users from a real-world algorithmic problem to a concrete solving strategy. Produces a static solution doc in `docs/solutions/`.
9+
10+
## Invocation
11+
12+
```
13+
/find-solver — start from Step 1 (clarify problem)
14+
/find-solver <ProblemName> — skip to Step 3 (explore reductions for a known model)
15+
```
16+
17+
<HARD-GATE>
18+
Do NOT modify project source files, write Rust code, or create PRs.
19+
Only outputs: `pred` CLI commands executed live, web searches, conversational commentary, and one solution doc in `docs/solutions/`.
20+
If the user asks about contributing code, point them to `/add-model`, `/add-rule`, or `/propose`.
21+
</HARD-GATE>
22+
23+
## Audience
24+
25+
This skill serves two types of users:
26+
27+
- **Practitioners** who have a fuzzy real-world problem (e.g., "I need to assign tasks to machines minimizing makespan") and need help identifying which NP-hard problem it maps to
28+
- **Researchers** who already know the formal problem name and want to find the best reduction path + solver
29+
30+
Adapt the flow: if the user provides a formal problem name, validate it with `pred show` and skip directly to Step 3.
31+
32+
## Flow Overview
33+
34+
```
35+
Step 1: Clarify Problem (skip if user knows the formal name)
36+
Step 2: Match to Library Models (web search + pred list)
37+
Step 3: Explore Reduction Paths (multi-hop guided via pred to)
38+
Step 4: Recommend Solvers (web search + pred solve options)
39+
Step 5: Generate Solution Doc (docs/solutions/<name>.md)
40+
```
41+
42+
## CRITICAL: Output Visibility
43+
44+
Bash tool results are hidden from the user in the Claude Code UI. **After every `pred` command, you MUST copy-paste the full stdout/stderr into your response as text.** The pattern for every command is:
45+
46+
1. Announce the command and why: "Let me run `pred to MIS` to see what MIS can be reduced to:"
47+
2. Run the command via the Bash tool
48+
3. Copy the COMPLETE output into your text response inside a fenced code block
49+
4. Then add your brief explanation
50+
51+
Never skip step 1 or 3.
52+
53+
---
54+
55+
## Step 1: Clarify Problem
56+
57+
**Goal:** Understand the user's problem well enough to form a search query for matching models.
58+
59+
**Researcher shortcut:** If the user invoked `/find-solver <ProblemName>` or describes their problem using a formal name (e.g., "maximum independent set", "graph coloring"), run `pred show <name>` to validate it exists. If it does, skip directly to Step 3 with that model. If it doesn't exist in the library, tell the user and fall through to Step 2.
60+
61+
**For practitioners, ask one question at a time:**
62+
63+
1. "Describe your problem in plain language — what are you trying to optimize, decide, or compute?"
64+
65+
2. Based on the answer, if the input structure is ambiguous, ask:
66+
"Is your input a graph/network? A set of items? A boolean formula? Numbers/matrices?"
67+
68+
3. If the objective is unclear:
69+
"What's the objective — minimize something, maximize something, or check feasibility?"
70+
71+
4. "Roughly how large are your instances? (e.g., 10 nodes, 1000 variables)"
72+
73+
Use `AskUserQuestion` for each question. Format options as **(a)**/**(b)**/**(c)** when multiple choice is natural.
74+
75+
**Exit condition:** You have enough context to form a search query like "task scheduling minimize makespan NP-hard" or "maximum weight independent set unit disk graph". Proceed to Step 2.
76+
77+
---
78+
79+
## Step 2: Match to Library Models
80+
81+
**Goal:** Identify which problem model(s) in the library match the user's problem.
82+
83+
**Key rule:** Web search happens BEFORE presenting options. Never guess model matches from internal knowledge alone.
84+
85+
**Actions:**
86+
87+
1. **Web search** the clarified problem description together with terms like "NP-hard", "computational complexity", or "reduction" to find formal problem names and known relationships in the literature. Use `WebSearch` tool.
88+
89+
2. **Run `pred list`** to get the full catalog of available models. Copy-paste the full output into your response.
90+
91+
3. **Cross-reference** the web search results against the `pred list` catalog. For each candidate model that exists in the library (3-5 max), present a table:
92+
93+
| # | Model | Why it might match | Caveat |
94+
|---|-------|--------------------|--------|
95+
| 1 | ... | ... | ... |
96+
| 2 | ... | ... | ... |
97+
| 3 | ... | ... | ... |
98+
99+
4. For each candidate, run `pred show <model>` and show the output — fields, complexity, available reductions. This helps the user see what data they would need to provide.
100+
101+
5. **Ask the user to pick one** using `AskUserQuestion`. If none fit, ask the user for more detail and re-run the web search with refined keywords.
102+
103+
**Proceed to Step 3 with the chosen model.**
104+
105+
---
106+
107+
## Step 3: Explore Reduction Paths
108+
109+
**Goal:** Guide the user through the reduction graph one hop at a time until they reach a solver-ready target.
110+
111+
**This is an interactive loop. Each iteration:**
112+
113+
1. **Run `pred to <current_model>`** to get 1-hop reduction targets. Copy-paste the full output.
114+
115+
2. **For each target**, gather additional info and present an annotated table:
116+
117+
- Run `pred show <target>` to get its best-known complexity
118+
- Run `pred path <target> ILP` to check if an ILP path exists (report step count or "No path")
119+
- Extract overhead from the `pred to` / `pred show` output
120+
121+
Present the table:
122+
123+
| # | Reduces To | Overhead | Complexity | Has ILP Path? |
124+
|---|------------|----------|------------|---------------|
125+
| 1 | ... | ... | ... | ... |
126+
| 2 | ... | ... | ... | ... |
127+
128+
3. **Show the running path summary:**
129+
130+
```
131+
Path so far: MIS -> MaximumSetPacking -> ???
132+
Accumulated overhead: num_sets = num_vertices, universe_size = num_edges
133+
```
134+
135+
4. **Ask the user** using `AskUserQuestion`:
136+
- Pick a target number to continue exploring
137+
- Or say "solve here" to stop at the current problem
138+
- Or say "go back" to revisit the previous step
139+
140+
5. **Repeat** with the chosen target as the new current model.
141+
142+
**Termination conditions:**
143+
- User reaches ILP or another solver-ready problem and says "solve here"
144+
- User explicitly chooses brute-force on the current problem
145+
- No outgoing reductions exist — inform the user this is a dead end and suggest backtracking
146+
147+
**Backtracking:** If the user says "go back" or "try a different target", re-run `pred to` on the previous model and present options again.
148+
149+
**Proceed to Step 4 with the final reduction path.**
150+
151+
---
152+
153+
## Step 4: Recommend Solvers
154+
155+
**Goal:** Find the best solver options — both built-in and external — for the target problem.
156+
157+
**Key rule:** Web search happens BEFORE presenting solver options. Do not recommend solvers from internal knowledge alone.
158+
159+
**Actions:**
160+
161+
1. **Web search** the final target problem + "solver" + "benchmark" + "library" to find state-of-the-art external tools. Use `WebSearch` tool. Example queries:
162+
- "QUBO solver open source benchmark"
163+
- "integer linear programming solver comparison"
164+
- "maximum independent set practical solver"
165+
166+
2. **Check built-in solver availability:**
167+
- Run `pred path <current_model> ILP` — if a path exists, `pred solve --solver ilp` is available
168+
- `pred solve --solver brute-force` is always available (feasible for small instances, ~25 variables)
169+
170+
3. **Present solver options** in a table:
171+
172+
| # | Solver | Type | How to Use | Notes |
173+
|---|--------|------|------------|-------|
174+
| 1 | pred solve --solver ilp | Built-in | pred solve reduced.json | HiGHS backend |
175+
| 2 | pred solve --solver brute-force | Built-in | pred solve problem.json --solver brute-force | Exact, small instances only |
176+
| 3 | (from web search) | External | (brief setup) | (strengths/limitations) |
177+
| 4 | (from web search) | External | (brief setup) | (strengths/limitations) |
178+
179+
4. **Ask the user** which solver(s) to include in the solution doc using `AskUserQuestion`.
180+
181+
**Proceed to Step 5 with the selected solver(s).**
182+
183+
---
184+
185+
## Step 5: Generate Solution Doc
186+
187+
**Goal:** Write a static reference document with everything the user needs to solve their problem.
188+
189+
**File path:** `docs/solutions/<problem>-via-<model>-<solver>.md`
190+
191+
Where:
192+
- `<problem>` is a short kebab-case description of the real-world problem
193+
- `<model>` is the library model name (e.g., `MIS`, `QUBO`)
194+
- `<solver>` is the primary solver (e.g., `ILP`, `brute-force`, `gurobi`)
195+
196+
Ask the user to confirm the filename before writing.
197+
198+
**Doc template — write all sections:**
199+
200+
```markdown
201+
# <Real-world Problem> via <Model> -> <Solver>
202+
203+
## Problem Description
204+
205+
<What the user described, formalized. One paragraph.>
206+
207+
## Matched Model
208+
209+
- **Name:** <ProblemType> {variant}
210+
- **Why this model:** <reasoning from Step 2>
211+
- **Best-known complexity:** O(...)
212+
213+
## Input Schema
214+
215+
<JSON schema from `pred show --json <model>`, with field explanations.>
216+
217+
Example instance:
218+
219+
```json
220+
<Run `pred create --example <model/variant>` and paste the JSON output>
221+
```
222+
223+
## Reduction Path
224+
225+
<For each step in the path chosen during Step 3:>
226+
227+
### Step N: <Source> -> <Target>
228+
229+
- **Overhead:** <field-by-field from pred show>
230+
231+
```bash
232+
pred reduce input.json --to <Target> -o step_N.json
233+
```
234+
235+
## Solving
236+
237+
```bash
238+
pred solve step_N.json --solver ilp --timeout 60
239+
```
240+
241+
<Explain what the output means for the user's original problem.
242+
E.g., "Max(3) means the maximum independent set has 3 vertices.">
243+
244+
## Solution Extraction
245+
246+
<Explain how the target solution maps back to the original problem.>
247+
248+
Using the reduction bundle workflow (recommended):
249+
250+
```bash
251+
pred reduce input.json --to <FinalTarget> -o bundle.json
252+
pred solve bundle.json --solver ilp --timeout 60
253+
```
254+
255+
The solver automatically extracts the solution back to the original problem space.
256+
257+
## External Solver Alternatives
258+
259+
<For each external solver chosen in Step 4:>
260+
261+
### <Solver Name>
262+
263+
- **What:** <one-line description>
264+
- **When to prefer:** <when this is better than built-in>
265+
- **How to use:** <brief setup or export instructions, if applicable>
266+
267+
## Quick Reference
268+
269+
All commands in sequence:
270+
271+
```bash
272+
# 1. Create your problem instance
273+
pred create <Model> <flags> -o input.json
274+
275+
# 2. Reduce to solver-ready form
276+
pred reduce input.json --to <FinalTarget> -o bundle.json
277+
278+
# 3. Solve
279+
pred solve bundle.json --solver ilp --timeout 60
280+
281+
# 4. Verify (optional)
282+
pred evaluate input.json --config <solution_vector>
283+
```
284+
```
285+
286+
**After writing the doc:**
287+
288+
1. Show the user the generated filename and a brief summary of what's in it.
289+
2. Ask if they want to make any changes before finishing.
290+
291+
---
292+
293+
## Key Behaviors
294+
295+
- **One question at a time.** Never ask multiple questions in one message. Use `AskUserQuestion` for every decision point.
296+
- **Web search before recommendations.** In Step 2 (model matching) and Step 4 (solver recommendation), always web search first. Never rely on internal knowledge alone.
297+
- **Show full output.** After every Bash tool call, copy-paste the COMPLETE output into your text response as a fenced code block. Bash tool results are hidden in the UI.
298+
- **Announce every command.** Before running, say what command you're using and why.
299+
- **Compact formatting.** Write explanations as plain paragraphs. Do not use blockquote `>` syntax for explanations. Keep tight: command announcement, code block output, 1-3 sentence explanation.
300+
- **Conversational tone.** Guided consultation, not a lecture.
301+
- **Live execution.** Every `pred` command runs for real. No fake output.
302+
- **Graceful fallbacks.** If a path doesn't exist or a command fails, explain what happened and suggest alternatives (try another model, use brute-force, backtrack).
303+
- **Adapt to user level.** If the user gives a formal problem name, skip clarification. If they describe a fuzzy real-world problem, ask follow-ups one at a time.
304+
- **Use `--timeout 30`** with `pred solve` in any live demos during the session.

0 commit comments

Comments
 (0)