Skip to content

Commit f85865a

Browse files
GiggleLiuclaude
GiggleLiu
and
claude
authored
feat: add find-solver and find-problem skills, fix KColoring/KN serialization (#1040)
* docs: add solutions directory for find-solver skill output * feat(skill): add find-solver skill — interactive problem-to-solver guide * docs: register find-solver skill in CLAUDE.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat(skill): add find-problem skill — discover problems solvable via a given model Reverse of /find-solver: given a solver for a specific model, explore incoming reductions to discover what other problems the solver can handle, ranked by effective complexity. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * refactor(skill): find-solver Step 3 — auto-explore all hops instead of hop-by-hop Consistent with find-problem: use `pred to --hops 3` to discover all reachable targets at once, present ranked table, user picks path. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(skill+cli): correct pred direction in find-solver/find-problem, fix KColoring/KN serialization find-solver Step 3 used `pred to` (incoming) when it should use `pred from` (outgoing) to find solver-ready targets. find-problem Step 2 had the mirror bug: `pred from` (outgoing) instead of `pred to` (incoming) for discovering problems that reduce to the user's model. Also fix KColoring/KN schema-driven creation: inject `num_colors` from --k into JSON so the value round-trips correctly. Without this, KN instances deserialized with num_colors=0, causing all solvers to return no solution. Found via agentic skill tests with simulated expert users. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 0f9db3c commit f85865a

5 files changed

Lines changed: 503 additions & 0 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@ These repo-local skills live under `.claude/skills/*/SKILL.md`.
4040
- [verify-reduction](skills/verify-reduction/SKILL.md) -- Standalone mathematical verification of a reduction rule: Typst proof, constructor Python (≥5000 checks), adversary Python (≥5000 independent checks). Reports verdict, no artifacts saved. Also called as a subroutine by `/add-rule` (default behavior).
4141
- [tutorial](skills/tutorial/SKILL.md) -- Interactive tutorial — walk through the pred CLI to explore, reduce, and solve NP-hard problems. No Rust internals.
4242
- [update-papers](skills/update-papers/SKILL.md) -- Update research paper collection: download new papers from references.bib, retry failed downloads, sync to Google Drive, regenerate index.md.
43+
- [find-solver](skills/find-solver/SKILL.md) -- Interactive guide: match a real-world problem to a library model, explore reduction paths, recommend solvers (built-in + external), and generate a solution doc.
44+
- [find-problem](skills/find-problem/SKILL.md) -- Reverse of find-solver: given a solver for a model, discover what other problems it can handle via incoming reductions, ranked by effective complexity.
4345

4446
## Codex Compatibility
4547
- Claude slash commands such as `/issue-to-pr 42 --execute` are aliases for the matching repo-local skill files under `.claude/skills/`.

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

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
name: find-problem
3+
description: Reverse of find-solver — given a solver for a model, discover what other problems it can handle via incoming reductions, ranked by effective complexity
4+
---
5+
6+
# Find Problem
7+
8+
Given a solver for a specific model, discover what other problems it can handle by exploring the reduction graph in the incoming direction. Produces a solution doc ranking all reachable problems by effective complexity.
9+
10+
## Invocation
11+
12+
```
13+
/find-problem — start from Step 1 (identify solver)
14+
/find-problem <ModelName> — skip model identification, ask for complexity
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+
Users who have built or have access to a solver for a specific problem model and want to understand the full scope of problems their solver can handle through reductions.
26+
27+
## Flow Overview
28+
29+
```
30+
Step 1: Identify Solver (user provides model + complexity)
31+
Step 2: Discover Reachable Problems (pred from --hops 3, compute effective complexity)
32+
Step 3: Rank and Present (table ranked by effective complexity, web search for applications)
33+
Step 4: Generate Solution Doc (docs/solutions/<name>.md)
34+
```
35+
36+
## CRITICAL: Output Visibility
37+
38+
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:
39+
40+
1. Announce the command and why: "Let me run `pred to MIS --hops 3` to discover all problems that can reduce to MIS:"
41+
2. Run the command via the Bash tool
42+
3. Copy the COMPLETE output into your text response inside a fenced code block
43+
4. Then add your brief explanation
44+
45+
Never skip step 1 or 3.
46+
47+
---
48+
49+
## Step 1: Identify Solver
50+
51+
**Goal:** Get the user's model name and solver complexity.
52+
53+
**If invoked as `/find-problem <ModelName>`:** validate with `pred show <ModelName>`. If it exists, show the output (including size fields), then ask for solver complexity.
54+
55+
**If invoked as `/find-problem`:** ask using `AskUserQuestion`: "Which problem model does your solver handle?" Validate the answer with `pred show`.
56+
57+
**Ask for complexity** using `AskUserQuestion`: "What is your solver's time complexity? Use the size field names from the output above (e.g., `O(1.1996^num_vertices)`, `O(2^(num_variables/3))`)."
58+
59+
- Variable names should match the model's size fields shown in `pred show` output
60+
- If the user gives informal notation (e.g., "exponential in n"), help them formalize it using the model's actual size field names
61+
62+
**Exit condition:** Validated model name + complexity expression with variables matching the model's size fields. Proceed to Step 2.
63+
64+
---
65+
66+
## Step 2: Discover Reachable Problems
67+
68+
**Goal:** Find all problems that can reduce to the user's model and compute effective complexity for each.
69+
70+
**Actions:**
71+
72+
1. **Run `pred to <model> --hops 3`** to find all problems that can reduce to the user's model within 3 hops (incoming direction). Copy-paste the full output.
73+
74+
2. **For each discovered problem**, run:
75+
- `pred path <source> <model>` — get the cheapest witness-capable reduction path
76+
- `pred show <source>` — get best-known brute-force complexity
77+
78+
3. **Compute effective complexity** for each source problem:
79+
- Take the user's solver complexity expression (e.g., `O(1.1996^num_vertices)`)
80+
- Substitute the overhead expressions from the reduction path into the solver's variables
81+
- Example: if MVC→MIS has overhead `num_vertices = num_vertices`, then solving MVC via MIS costs `O(1.1996^num_vertices)` — same as MIS
82+
- Example: if overhead is `num_vertices = num_clauses * 3`, then effective complexity is `O(1.1996^(3 * num_clauses))`
83+
84+
4. **Compare to best-known**: for each source, compare effective complexity to the source's own best-known complexity from `pred show`. Classify as:
85+
- **Better** — effective complexity has a smaller base or exponent than best-known
86+
- **Similar** — comparable asymptotic behavior
87+
- **Worse** — effective complexity exceeds best-known (reduction overhead makes it impractical)
88+
89+
5. **Web search** each discovered source problem + "applications" or "real-world" to find practical use cases. Use `WebSearch` tool.
90+
91+
**If `--hops 3` returns more than 15 results:** present only the top 10 by effective complexity and mention the rest are available if the user wants to see them.
92+
93+
**Proceed to Step 3.**
94+
95+
---
96+
97+
## Step 3: Rank and Present
98+
99+
**Goal:** Show all discovered problems ranked by practical usefulness.
100+
101+
Present a ranked table (most practical first):
102+
103+
| # | Problem | Hops | Overhead | Effective Complexity | vs Best-Known | Applications |
104+
|---|---------|------|----------|---------------------|---------------|--------------|
105+
| 1 | MinimumVertexCover | 1 | same size | O(1.1996^n) | Better | Network monitoring |
106+
| 2 | MaximumClique | 2 | complement graph | O(1.1996^n) | Better | Social network cliques |
107+
| 3 | GraphColoring | 3 | n^2 vars | O(1.1996^(n^2)) | Worse | Register allocation |
108+
109+
Ask using `AskUserQuestion`: "Which problems would you like included in the solution doc? Pick numbers, or 'all practical' for only the Better/Similar ones."
110+
111+
**Proceed to Step 4 with the selected problems.**
112+
113+
---
114+
115+
## Step 4: Generate Solution Doc
116+
117+
**Goal:** Write a static reference document listing all selected problems and how to solve them via the user's model.
118+
119+
**File path:** `docs/solutions/problems-solvable-via-<Model>-<solver>.md`
120+
121+
Where:
122+
- `<Model>` is the library model name (e.g., `MIS`, `QUBO`)
123+
- `<solver>` is a short label for the user's solver (e.g., `custom-1.1996`, `ILP`)
124+
125+
Ask the user to confirm the filename before writing.
126+
127+
**Doc template — write all sections:**
128+
129+
```markdown
130+
# Problems Solvable via <Model> (<Solver Complexity>)
131+
132+
## Overview
133+
134+
<One paragraph: your solver for X can handle these Y problems via reductions. Brief explanation of the ranking methodology.>
135+
136+
## Summary Table
137+
138+
| Problem | Hops | Overhead | Effective Complexity | vs Best-Known | Applications |
139+
|---------|------|----------|---------------------|---------------|--------------|
140+
| ... | ... | ... | ... | ... | ... |
141+
142+
## <Problem 1> -> <Model>
143+
144+
- **What it is:** <brief description + real-world applications from web search>
145+
- **Reduction path:** <Source> -> ... -> <Model>
146+
- **Overhead:** <field-by-field>
147+
- **Effective complexity:** <composed expression>
148+
- **vs best-known:** <Better/Similar/Worse — with the source's brute-force complexity for comparison>
149+
150+
### CLI Commands
151+
152+
```bash
153+
# Create a source problem instance
154+
pred create <Source> <flags> -o input.json
155+
156+
# Reduce to your solver's model
157+
pred reduce input.json --to <Model> -o bundle.json
158+
159+
# Solve (built-in ILP or your external solver)
160+
pred solve bundle.json --solver ilp --timeout 60
161+
```
162+
163+
## <Problem 2> -> <Model>
164+
165+
...
166+
```
167+
168+
**After writing the doc:**
169+
170+
1. Show the user the generated filename and a brief summary of what's in it.
171+
2. Ask if they want to make any changes before finishing.
172+
173+
---
174+
175+
## Key Behaviors
176+
177+
- **One question at a time.** Never ask multiple questions in one message. Use `AskUserQuestion` for every decision point.
178+
- **Web search before presenting applications.** In Step 2, web search each discovered problem for real-world use cases. Never guess applications from internal knowledge alone.
179+
- **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.
180+
- **Announce every command.** Before running, say what command you're using and why.
181+
- **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.
182+
- **Conversational tone.** Guided consultation, not a lecture.
183+
- **Live execution.** Every `pred` command runs for real. No fake output.
184+
- **Graceful fallbacks.** If `pred to` returns no results (no incoming reductions), suggest trying with more hops or a different model. If `pred path` fails for a specific source, skip it and note it in the table.
185+
- **Help with complexity notation.** If the user gives informal complexity, show `pred show <model>` size fields and help them write a formal expression.
186+
- **Cap results at 10.** If discovery returns many problems, show top 10 by effective complexity and offer to show more.

0 commit comments

Comments
 (0)