Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
## Project Overview
Rust library for NP-hard problem reductions. Implements computational problems with reduction rules for transforming between equivalent formulations.

## Skills
When resolving an issue with pull request, please use [issue-to-pr](skills/issue-to-pr.md) skill to convert the issue into a pull request with a plan.

## Commands
```bash
make help # Show all available targets
Expand Down
22 changes: 7 additions & 15 deletions .claude/skills/issue-to-pr.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,6 @@ description: Use when you have a GitHub issue and want to create a PR with an im

Convert a GitHub issue into an actionable PR with a plan that auto-triggers Claude execution.

## Usage

```
/issue-to-pr <issue-number-or-url>
```

## Workflow

```dot
Expand All @@ -24,15 +18,13 @@ digraph issue_to_pr {
"Research references" [shape=box];
"Write plan file" [shape=box];
"Create branch and PR" [shape=box];
"PR triggers [action]" [shape=doublecircle];

"Receive issue number" -> "Fetch issue with gh";
"Fetch issue with gh" -> "Check the rules to follow";
"Check the rules to follow" -> "Verify completeness";
"Verify completeness" -> "Research references";
"Research references" -> "Write plan file";
"Write plan file" -> "Create branch and PR";
"Create branch and PR" -> "PR triggers [action]";
}
```

Expand Down Expand Up @@ -108,6 +100,7 @@ The plan MUST include an **action pipeline** section with concrete steps based o
- Present example in tutorial style (see KColoring→QUBO section for reference)

5. **Regenerate graph** — `cargo run --example export_graph`
6. **Push and create PR** — Push the changes and create a pull request with a description of the changes.

**Rules for solver implementation:**
- Make sure at least one solver is provided in the issue template. Check if the solving strategy is valid. If not, reply under issue to ask for clarification.
Expand Down Expand Up @@ -140,8 +133,10 @@ The plan MUST include an **action pipeline** section with concrete steps based o
3. **Document** — Update `docs/paper/reductions.typ`:
- Add `display-name` entry
- Add `#problem-def("Name")[definition...]`
4. **Push and create PR** — Push the changes and create a pull request with a description of the changes.

### 6. Create PR
Create a pull request with only the plan file.

```bash
# Create branch
Expand All @@ -156,16 +151,15 @@ git commit -m "Add plan for #<number>: <title>"
# Push
git push -u origin issue-<number>-<slug>

# Create PR with [action] at the BEGINNING
gh pr create --title "Fix #<number>: <title>" --body "[action]
# Create PR
gh pr create --title "Fix #<number>: <title>" --body "

## Summary
<Brief description from brainstorming>

Closes #<number>"
```

**CRITICAL:** The PR body MUST start with `[action]` on the first line. This triggers automated plan execution.

## Example

Expand All @@ -181,17 +175,15 @@ All required info is present. I'll create the plan...

[Writes docs/plans/2026-02-09-independentset-to-qubo.md]
[Creates branch, commits, pushes]
[Creates PR with body starting with "[action]"]
[Creates PR]

Created PR #45: Fix #42: Add IndependentSet → QUBO reduction
The [action] trigger will automatically execute the plan.
Created PR #45: Fix #42: Add IndependentSet → QUBO reduction, description: ...
```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Issue template incomplete | Ask contributor to fill in missing sections before proceeding |
| `[action]` not at start | PR body must BEGIN with `[action]` |
| Including implementation code in initial PR | First PR: plan only |
| Generic plan | Use specifics from the issue |
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -77,3 +77,4 @@ docs/paper/examples/

# Claude Code logs
claude-output.log
.worktrees/
5 changes: 3 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -165,9 +165,9 @@ compare: rust-export
INSTRUCTIONS ?=
OUTPUT ?= claude-output.log
AGENT_TYPE ?= claude
PLAN_FILE ?= $(shell ls -t docs/plans/*.md 2>/dev/null | head -1)

run-plan:
PLAN_FILE ?= $(shell ls -t docs/plans/*.md 2>/dev/null | head -1)
@NL=$$'\n'; \
BRANCH=$$(git branch --show-current); \
if [ "$(AGENT_TYPE)" = "claude" ]; then \
Expand All @@ -182,6 +182,7 @@ run-plan:
PROMPT="$${PROMPT}$${NL}$${NL}## Process$${NL}$${PROCESS}$${NL}$${NL}## Rules$${NL}- Tests should be strong enough to catch regressions.$${NL}- Do not modify tests to make them pass.$${NL}- Test failure must be reported."; \
echo "=== Prompt ===" && echo "$$PROMPT" && echo "===" ; \
claude --dangerously-skip-permissions \
--model claude-opus-4-6 \
--model opus \
--verbose \
--max-turns 500 \
-p "$$PROMPT" 2>&1 | tee "$(OUTPUT)"
20 changes: 20 additions & 0 deletions docs/paper/reductions.typ
Original file line number Diff line number Diff line change
Expand Up @@ -806,6 +806,25 @@ The following reductions to Integer Linear Programming are straightforward formu
_Construction._ Variables: $x_v in {0, 1}$ for each $v in V$. Constraints: $x_u + x_v <= 1$ for each $(u, v) in.not E$ (non-edges). Objective: maximize $sum_v x_v$. Equivalently, IS on the complement graph. _Solution extraction:_ $K = {v : x_v = 1}$.
]

#reduction-rule("TravelingSalesman", "ILP",
example: true,
example-caption: [Weighted $K_4$: the optimal tour $0 arrow 1 arrow 3 arrow 2 arrow 0$ with cost 80 is found by position-based ILP.],
)[
The traveling salesman problem reduces to binary ILP with $n^2 + 2 m n$ variables via position-based encoding with McCormick linearization.
][
_Construction._ For graph $G = (V, E)$ with $n = |V|$ and $m = |E|$:

_Variables:_ Binary $x_(v,k) in {0, 1}$ for each vertex $v in V$ and position $k in {0, ..., n-1}$. Interpretation: $x_(v,k) = 1$ iff vertex $v$ is at position $k$ in the tour.

_Auxiliary variables:_ For each edge $(u,v) in E$ and position $k$, introduce $y_(u,v,k)$ and $y_(v,u,k)$ to linearize the products $x_(u,k) dot x_(v,(k+1) mod n)$ and $x_(v,k) dot x_(u,(k+1) mod n)$ respectively.

_Constraints:_ (1) Each vertex has exactly one position: $sum_(k=0)^(n-1) x_(v,k) = 1$ for all $v in V$. (2) Each position has exactly one vertex: $sum_(v in V) x_(v,k) = 1$ for all $k$. (3) Non-edge consecutive prohibition: if ${v,w} in.not E$, then $x_(v,k) + x_(w,(k+1) mod n) <= 1$ for all $k$. (4) McCormick: $y <= x_(v,k)$, $y <= x_(w,(k+1) mod n)$, $y >= x_(v,k) + x_(w,(k+1) mod n) - 1$.

_Objective:_ Minimize $sum_((u,v) in E) w(u,v) dot sum_k (y_(u,v,k) + y_(v,u,k))$.

_Solution extraction._ For each position $k$, find vertex $v$ with $x_(v,k) = 1$ to recover the tour permutation; then select edges between consecutive positions.
]

== Unit Disk Mapping

#reduction-rule("MaximumIndependentSet", "GridGraph")[
Expand Down Expand Up @@ -918,6 +937,7 @@ The following table shows concrete variable overhead for example instances, gene
"kcoloring_to_ilp", "factoring_to_ilp",
"maximumsetpacking_to_ilp", "minimumsetcovering_to_ilp",
"minimumdominatingset_to_ilp", "maximumclique_to_ilp",
"travelingsalesman_to_ilp",
)

#let examples = example-files.map(n => {
Expand Down
Loading