Skip to content
Closed
3 changes: 3 additions & 0 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ Rust library for NP-hard problem reductions. Implements computational problems w
- [write-rule-in-paper](skills/write-rule-in-paper/SKILL.md) -- Write or improve a reduction-rule entry in the Typst paper. Covers complexity citation, self-contained proof, detailed example, and verification.
- [release](skills/release/SKILL.md) -- Create a new crate release. Determines version bump from diff, verifies tests/clippy, then runs `make release`.
- [meta-power](skills/meta-power/SKILL.md) -- Batch-resolve all open `[Model]` and `[Rule]` issues autonomously: plan, implement, review, fix CI, merge — in dependency order (models first).
- [zero-to-infinity](skills/zero-to-infinity/SKILL.md) -- Discover and prioritize new problems and reduction rules based on user-ranked impact dimensions (academia, industry, cross-field, etc.), then file as GitHub issues.
- [add-issue-model](skills/add-issue-model/SKILL.md) -- File a well-formed `[Model]` GitHub issue with all 11 checklist items, citations, and repo verification.
- [add-issue-rule](skills/add-issue-rule/SKILL.md) -- File a well-formed `[Rule]` GitHub issue with all 9 checklist items, worked example, correctness argument, and nontriviality check.

## Commands
```bash
Expand Down
138 changes: 138 additions & 0 deletions .claude/skills/add-issue-model/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
---
name: add-issue-model
description: Use when filing a GitHub issue for a new problem model, ensuring all template sections are complete with citations
---

# Add Issue — Model

File a `[Model]` GitHub issue on CodingThrust/problem-reductions using the upstream "Problem" issue template. Ensures all sections are complete, cited, and verified against the repo.

## Input

The caller (zero-to-infinity or user) provides:
- Problem name
- Brief description / definition sketch
- Reference URLs (if available)

## Step 1: Verify Non-Existence

Before anything else, confirm the model doesn't already exist:

```bash
# Check implemented models
ls src/models/*/ | grep -i "<problem_name_lowercase>"

# Check open issues
gh issue list --state open --limit 200 --json title,number | grep -i "<problem_name>"

# Check closed issues
gh issue list --state closed --limit 200 --json title,number | grep -i "<problem_name>"
```

**If found:** STOP. Report to caller that this model already exists (with issue number or file path).

## Step 2: Research and Fill Template Sections

Use `WebSearch` and `WebFetch` to fill all sections from the upstream template (`.github/ISSUE_TEMPLATE/problem.md`):

| Section | What to fill | Guidance |
|---------|-------------|----------|
| **Motivation** | One sentence: why include this problem? | E.g. "Widely used in network design and has known reductions to QUBO." |
| **Definition — Name** | Use `Maximum*`/`Minimum*` prefix for optimization. Check CLAUDE.md "Problem Names" | E.g. `MaximumIndependentSet` |
| **Definition — Reference** | URL or citation for the formal definition | Must be a real, accessible URL |
| **Definition — Formal** | Input, feasibility constraints, and objective. Define ALL symbols before using them. Use LaTeX math (`$...$` inline, `$$...$$` display) | E.g. "Given $G=(V,E)$ where $V$ is vertex set and $E$ is edge set, find $S \subseteq V$ such that..." |
| **Variables — Count** | Number of variables in configuration vector | E.g. $n = |V|$ (one variable per vertex) |
| **Variables — Domain** | Per-variable domain | E.g. binary $\{0,1\}$ or $\{0,\ldots,K-1\}$ for $K$ colors |
| **Variables — Meaning** | What each variable represents | E.g. $x_i = 1$ if vertex $i \in S$ |
| **Schema — Type name** | Rust struct name | Must match the Definition Name |
| **Schema — Variants** | Graph topology variants, weighted/unweighted | E.g. `SimpleGraph, GridGraph; weighted or unweighted` |
| **Schema — Fields table** | `\| Field \| Type \| Description \|` for each struct field | Connect fields to symbols defined in Definition |
| **Complexity** | Best known exact algorithm with concrete numbers | E.g. $O(1.1996^n)$ by Xiao & Nagamochi (2017). **No symbolic constants.** |
| **Complexity — References** | URL for complexity results | Must be citable |
| **Extra Remark** | Optional: historical context, applications, relationships | Can be brief or empty |
| **How to solve** | Check applicable boxes | BruteForce / ILP reduction / Other |
| **Example Instance** | Small but non-trivial instance with known optimal solution | Must be large enough to exercise constraints (avoid trivial cases). Will appear in paper. |

**Citation rule:** Every complexity claim and reference MUST include a URL.

**Formatting rule:** All mathematical expressions MUST use GitHub LaTeX rendering: `$...$` for inline math (e.g., $G=(V,E)$, $x_i$, $O(1.1996^n)$) and `$$...$$` for display equations. Never use plain text for math.

## Step 3: Verify Algorithm Correctness

For the Complexity section:
- Cross-check the complexity claim against at least 2 independent sources
- Ensure the complexity uses concrete numeric values (e.g., $1.1996^n$), not symbolic constants
- Verify the variable in the complexity expression maps to a natural size getter (e.g., $n = |V|$ → `num_vertices`)

## Step 4: Draft and File Issue

Draft the issue body matching the upstream template format exactly:

```bash
gh issue create --repo CodingThrust/problem-reductions \
--title "[Model] ProblemName" \
--label "model" \
--body "$(cat <<'ISSUE_EOF'
## Motivation

<one sentence>

## Definition

**Name:** ProblemName
**Reference:** [citation](url)

<formal definition with all symbols defined, using LaTeX: $G=(V,E)$, $S \subseteq V$, etc.>

## Variables

- **Count:** $n = |V|$ (one variable per vertex)
- **Per-variable domain:** binary $\{0,1\}$
- **Meaning:** $x_i = 1$ if vertex $i$ is selected

## Schema (data type)

**Type name:** ProblemName
**Variants:** graph topology (SimpleGraph, ...), weighted or unweighted

| Field | Type | Description |
|-------|------|-------------|
| graph | SimpleGraph | the graph $G=(V,E)$ |
| weights | Vec<W> | vertex weights $w_i$ (weighted variant only) |

## Complexity

- **Best known exact algorithm:** $O(1.1996^n)$ by Author (Year), where $n = |V|$
- **References:** [paper](url)

## Extra Remark

<optional notes>

## How to solve

- [x] It can be solved by (existing) bruteforce.
- [ ] It can be solved by reducing the integer programming, through #issue-number.
- [ ] Other, refer to ...

## Example Instance

<small but non-trivial instance with known optimal solution, for testing and the paper>
ISSUE_EOF
)"
```

Report the created issue number and URL.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Using custom format instead of template | Must match `.github/ISSUE_TEMPLATE/problem.md` sections exactly |
| Missing complexity citation | Every algorithm claim needs author + year + URL |
| Symbolic constants in complexity | Use concrete numbers: $1.1996^n$ not $(2-\epsilon)^n$ |
| Plain text math | Use LaTeX: `$G=(V,E)$` not `G=(V,E)` |
| Undefined symbols in definition | Define ALL symbols (G, V, E, S, etc.) before using them |
| Trivial example instance | Use non-trivial instance (e.g., Petersen graph, not triangle) |
| Not checking repo first | Always run Step 1 before researching |
| Missing label | Use `--label "model"` to match template metadata |
142 changes: 142 additions & 0 deletions .claude/skills/add-issue-rule/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
---
name: add-issue-rule
description: Use when filing a GitHub issue for a new reduction rule, ensuring all template sections are complete with citations, worked examples, and correctness verification
---

# Add Issue — Rule

File a `[Rule]` GitHub issue on CodingThrust/problem-reductions using the upstream "Rule" issue template. Ensures all sections are complete, with citations, a worked example, and a validation method.

## Input

The caller (zero-to-infinity or user) provides:
- Source problem name
- Target problem name
- Reference URLs (if available)

## Step 1: Verify Non-Existence

Before anything else, confirm the rule doesn't already exist:

```bash
# Check implemented rules (filename pattern: source_target.rs)
ls src/rules/ | grep -i "<source_lowercase>.*<target_lowercase>"

# Check open issues
gh issue list --state open --limit 200 --json title,number | grep -i "<source>.*<target>"

# Check closed issues
gh issue list --state closed --limit 200 --json title,number | grep -i "<source>.*<target>"
```

**If found:** STOP. Report to caller that this rule already exists.

**Also verify both source and target models exist or have open issues:**
```bash
ls src/models/*/ | grep -i "<source_lowercase>"
ls src/models/*/ | grep -i "<target_lowercase>"
```

If a model doesn't exist and has no open issue, report it. The caller should file model issues first.

## Step 2: Research and Fill Template Sections

Use `WebSearch` and `WebFetch` to fill all sections from the upstream template (`.github/ISSUE_TEMPLATE/rule.md`):

| Section | What to fill | Guidance |
|---------|-------------|----------|
| **Source** | Source problem name | Must exist in repo or have open issue. Browse: https://codingthrust.github.io/problem-reductions/ |
| **Target** | Target problem name | Must exist in repo or have open issue |
| **Motivation** | One sentence: why is this reduction useful? | E.g. "Enables solving MIS on quantum annealers via QUBO formulation." |
| **Reference** | URL, paper, or textbook citation | Must be a real, accessible reference |
| **Reduction Algorithm** | Three parts: (1) Define notation — list ALL symbols for source and target instances. (2) Variable mapping — how source variables map to target variables. (3) Constraint/objective transformation — formulas, penalty terms, etc. Use LaTeX math (`$...$` inline, `$$...$$` display). | Solution extraction follows from variable mapping, no need to describe separately |
| **Size Overhead** | Table: `\| Target metric (code name) \| Polynomial (using symbols) \|` | Code names must match the target problem's getter methods (e.g., `num_vertices`, `num_edges`) |
| **Validation Method** | How to verify correctness beyond closed-loop testing | E.g. compare with ProblemReductions.jl, external solver, known results |
| **Example** | Small but non-trivial source instance for the paper illustration | Must be small enough for brute-force but large enough to exercise the reduction meaningfully. Provide as many details as possible — this appears in the paper and is used by AI to generate example code. |

**Citation rule:** Every claim MUST include a URL.

**Formatting rule:** All mathematical expressions MUST use GitHub LaTeX rendering: `$...$` for inline math (e.g., $G=(V,E)$, $x_i$, $Q_{ij}$) and `$$...$$` for display equations. Never use plain text for math.

## Step 3: Verify Example Correctness

For the Example section:
- Walk through the reduction step-by-step
- Show: source instance → apply reduction → target instance → solve target → verify solution maps back
- The example must be small enough to verify by hand (e.g., Petersen graph for graph problems)
- Provide concrete numbers, not just descriptions

## Step 4: Verify Nontriviality

The rule must be **nontrivial** (per issue #127 standards):
- NOT a simple identity mapping or type cast
- NOT a trivial embedding (just copying data)
- NOT a weight type conversion (i32 → f64)
- MUST involve meaningful structural transformation

If the rule is trivial, STOP and report to caller.

## Step 5: Draft and File Issue

Draft the issue body matching the upstream template format exactly:

```bash
gh issue create --repo CodingThrust/problem-reductions \
--title "[Rule] Source to Target" \
--label "rule" \
--body "$(cat <<'ISSUE_EOF'
**Source:** SourceProblem
**Target:** TargetProblem
**Motivation:** <one sentence>
**Reference:** [citation](url)

## Reduction Algorithm

**Notation:**
- Source instance: $G=(V,E)$, $n=|V|$, $m=|E|$
- Target instance: ...

**Variable mapping:**
<how source variables map to target variables, using LaTeX: $x_i$, $Q_{ij}$, etc.>

**Constraint/objective transformation:**
<formulas in LaTeX, penalty terms, proof of correctness>

## Size Overhead

| Target metric (code name) | Polynomial (using symbols above) |
|----------------------------|----------------------------------|
| `num_vertices` | $n = |V|$ |
| `num_edges` | $m + \ldots$ |

## Validation Method

<how to verify correctness beyond closed-loop testing>

## Example

<small but non-trivial source instance, worked step-by-step>

Source: <describe instance>
Reduction: <show transformation>
Target: <describe resulting instance>
Solution: <solve and verify>
ISSUE_EOF
)"
```

Report the created issue number and URL.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Using custom format instead of template | Must match `.github/ISSUE_TEMPLATE/rule.md` sections exactly |
| Filing trivial reductions | Check nontriviality in Step 4 |
| Missing model dependency | Verify both source and target exist in Step 1 |
| Example too complex or too trivial | Small enough for brute-force, large enough to be meaningful (e.g., Petersen graph) |
| Undefined symbols in algorithm | Define ALL notation before using it |
| Missing validation method | Must describe how to cross-check beyond closed-loop |
| Wrong overhead code names | Must match actual getter methods on target type |
| Missing label | Use `--label "rule"` to match template metadata |
| Plain text math | Use LaTeX: `$G=(V,E)$` not `G=(V,E)`, `$\sum w_{ij}$` not `sum w_ij` |
Loading