Skip to content

Commit 8a8316e

Browse files
GiggleLiuclaude
GiggleLiu
and
claude
committed
docs: improve issue templates and issue-to-pr workflow
- Problem template: add schema (fields table), complexity, variables count; require defining symbols before use - Rule template: add size overhead table, validation method; connect code metric names to math symbols - issue-to-pr skill: replace brainstorming with completeness check, add reference research step via web search Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent ea322d0 commit 8a8316e

3 files changed

Lines changed: 116 additions & 63 deletions

File tree

‎.claude/skills/issue-to-pr.md‎

Lines changed: 26 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,17 @@ digraph issue_to_pr {
2020
"Receive issue number" [shape=box];
2121
"Fetch issue with gh" [shape=box];
2222
"Check the rules to follow" [shape=box];
23-
"Brainstorm with user" [shape=box];
23+
"Verify completeness" [shape=box];
24+
"Research references" [shape=box];
2425
"Write plan file" [shape=box];
2526
"Create branch and PR" [shape=box];
2627
"PR triggers [action]" [shape=doublecircle];
2728
2829
"Receive issue number" -> "Fetch issue with gh";
2930
"Fetch issue with gh" -> "Check the rules to follow";
30-
"Check the rules to follow" -> "Brainstorm with user";
31-
"Brainstorm with user" -> "Write plan file";
31+
"Check the rules to follow" -> "Verify completeness";
32+
"Verify completeness" -> "Research references";
33+
"Research references" -> "Write plan file";
3234
"Write plan file" -> "Create branch and PR";
3335
"Create branch and PR" -> "PR triggers [action]";
3436
}
@@ -51,24 +53,28 @@ gh issue view <number> --json title,body,labels,assignees
5153

5254
Present issue summary to user.
5355

54-
### 3. Brainstorm Solutions
56+
### 3. Verify Issue Completeness
5557

56-
**REQUIRED:** Invoke `superpowers:brainstorming` skill with the issue context (if superpowers plugin is available). Otherwise, conduct a manual brainstorming discussion with the user.
58+
Check that the issue template is fully filled out:
59+
- For **[Model]** issues: Definition, Variables, Instance Data, Objective, Type Parameters, Example
60+
- For **[Rule]** issues: Source, Target, Reference, Reduction mapping, Solution Extraction, Size Overhead, Example
5761

58-
Brainstorming must cover:
59-
- **User intent** — clarify what the issue is asking for
60-
- **Multiple approaches** — explore 2-3 different implementation strategies
61-
- **Implementation details** — discuss the mathematical formulation, data structures, variable mappings, constraint encodings, and any non-obvious design choices
62-
- **Existing patterns** — read reference implementations in the codebase (e.g., `spinglass_qubo.rs` for reductions) to understand the conventions
63-
- **Scope** — agree on which variants to implement (e.g., unweighted only, specific K values)
62+
If any section is missing or unclear, comment on the issue via `gh issue comment <number> --body "..."` asking the contributor to fill in the missing sections. Then stop and wait — do NOT proceed until the issue is complete.
6463

65-
Do NOT skip brainstorming. Do NOT write a plan without user discussion.
64+
### 4. Research References
6665

67-
### 4. Write Plan
66+
Use `WebSearch` and `WebFetch` to look up the reference URL provided in the issue. This helps:
67+
- Clarify the formal problem definition and notation
68+
- Understand the reduction algorithm in detail (variable mapping, penalty terms, proof of correctness)
69+
- Resolve any ambiguities in the issue description without bothering the contributor
6870

69-
After brainstorming concludes, write plan to `docs/plans/YYYY-MM-DD-<slug>.md` using `superpowers:writing-plans`:
71+
If the reference is a paper or textbook, search for accessible summaries, lecture notes, or Wikipedia articles on the same reduction.
7072

71-
### 5. Create PR
73+
### 5. Write Plan
74+
75+
Write plan to `docs/plans/YYYY-MM-DD-<slug>.md` using `superpowers:writing-plans`:
76+
77+
### 6. Create PR
7278

7379
```bash
7480
# Create branch
@@ -101,13 +107,10 @@ User: /issue-to-pr 42
101107
102108
Claude: Let me fetch issue #42...
103109
104-
[Fetches issue: "Add IndependentSet → QUBO reduction"]
105-
106-
I'll read the rules to follow in .claude/rules/adding-reductions.md and use superpowers:brainstorming to explore this with you.
107-
108-
[Invokes brainstorming - discusses approaches, user preferences, scope]
110+
[Fetches issue: "[Rule] IndependentSet to QUBO"]
111+
[Verifies all template sections are filled out]
109112
110-
Based on our discussion, I'll create the plan with superpowers:writing-plans...
113+
All required info is present. I'll create the plan...
111114
112115
[Writes docs/plans/2026-02-09-independentset-to-qubo.md]
113116
[Creates branch, commits, pushes]
@@ -121,7 +124,7 @@ The [action] trigger will automatically execute the plan.
121124

122125
| Mistake | Fix |
123126
|---------|-----|
124-
| Skipping brainstorming | Always use superpowers:brainstorming (or manual discussion) first |
127+
| Issue template incomplete | Ask contributor to fill in missing sections before proceeding |
125128
| `[action]` not at start | PR body must BEGIN with `[action]` |
126129
| Including implementation code in initial PR | First PR: plan only |
127-
| Generic plan | Use specifics from brainstorming |
130+
| Generic plan | Use specifics from the issue |

‎.github/ISSUE_TEMPLATE/problem.md‎

Lines changed: 44 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,56 @@
11
---
22
name: Problem
3-
about: Contributors to propose a new model problem
3+
about: Propose a new problem type
44
title: "[Model] Problem name"
55
labels: model
66
assignees: ''
77

88
---
99

10-
## Description
11-
[Problem name, e.g. Maximum Independent Set]
10+
## Definition
1211

13-
[Description, with clear annotation of information source. e.g.
14-
Given a Graph G=(V,E), an independent set of vertices, i.e. a subset of V such that no two vertices in it are joined by an edge in E. To goal is to find the the independent set with maximum cardinality.
12+
**Name:** <!-- e.g. MaximumIndependentSet. Use Maximum/Minimum prefix for optimization problems -->
13+
**Category:** <!-- graph / satisfiability / set / optimization / specialized -->
14+
**Reference:** <!-- URL or citation for the formal definition -->
1515

16-
Ref: https://www.csc.kth.se/~viggo/wwwcompendium/node34.html
17-
]
16+
<!-- Formal definition: input, feasibility constraints, and objective.
17+
Define all symbols (e.g. G, V, E, S, K) before using them.
18+
19+
E.g. "Given an undirected graph G=(V,E) where V is the vertex set and E is the edge set,
20+
find S ⊆ V such that no two vertices in S are adjacent, maximizing |S|."
21+
-->
22+
23+
## Variables
24+
25+
<!-- How the problem maps to a configuration vector x = (x_0, ..., x_{n-1}).
26+
Use symbols defined above. -->
27+
28+
- **Count:** <!-- e.g. n = |V| (one variable per vertex) -->
29+
- **Per-variable domain:** <!-- e.g. binary {0,1}, or {0,...,K-1} for K colors -->
30+
- **Meaning:** <!-- e.g. x_i = 1 if vertex i ∈ S (selected in independent set) -->
1831

1932
## Schema
20-
[JSON Schema description, e.g.
21-
Type name: MaximumIndependentSet
22-
Vartiants: Different graph topolofy, weighted or unweighted (implemented as type parameters)
23-
Fields:
24-
- `graph`, a graph description
25-
- `weights`, a vector of numbers, for weights on vertices
26-
]
33+
34+
<!-- Describe the data fields that define a problem instance.
35+
Connect fields to the symbols defined above. -->
36+
37+
**Type name:** <!-- e.g. MaximumIndependentSet -->
38+
**Variants:** <!-- e.g. graph topology (SimpleGraph, GridGraph, UnitDiskGraph), weighted or unweighted -->
39+
40+
| Field | Type | Description |
41+
|-------|------|-------------|
42+
| <!-- e.g. graph --> | <!-- e.g. SimpleGraph --> | <!-- e.g. the graph G=(V,E) --> |
43+
| <!-- e.g. weights --> | <!-- e.g. Vec<W> --> | <!-- e.g. vertex weights w_i for each i ∈ V (weighted variant only) --> |
44+
45+
## Complexity
46+
47+
- **Decision complexity:** <!-- e.g. NP-complete, NP-hard, P, etc. -->
48+
- **Best known exact algorithm:** <!-- e.g. O(1.1996^n) by Xiao & Nagamochi (2017), where n = |V| -->
49+
- **Best known approximation:** <!-- e.g. no PTAS unless P=NP; or 2-approximation via greedy -->
50+
51+
## Example Instance
52+
53+
<!-- A small but non-trivial instance with known optimal solution, for testing and the paper.
54+
Should be large enough to exercise the problem's constraints meaningfully (avoid trivial cases like triangle graphs).
55+
E.g. "Petersen graph: |V|=10, |E|=15, 3-regular. Optimal IS size = 4."
56+
-->

‎.github/ISSUE_TEMPLATE/rule.md‎

Lines changed: 46 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,53 @@
11
---
22
name: Rule
3-
about: Contributors to propose a new reduction rule
4-
title: "[Rule] Source problem to target problem"
3+
about: Propose a new reduction rule
4+
title: "[Rule] Source to Target"
55
labels: rule
66
assignees: ''
77

88
---
99

10-
Source problem: [source problem type name A, e.g. MaximumIndependentSet, find problems we already have here: https://codingthrust.github.io/problem-reductions/]
11-
Target problem: [target problem type name B]
12-
13-
## Algorithm
14-
[
15-
You can show a detailed math decription here, it will be used for coding implementation and the typst manual (for human) writing.
16-
]
17-
18-
## Validation method
19-
[
20-
Proposed method for developing a test dataset (in json) to verify correctness. It is usually by round trip tests. e.g. map an instance A to B, solve B
21-
e.g.1
22-
Generate test dataset from an existing library: https://github.com/GiggleLiu/ProblemReductions.jl
23-
e.g.2
24-
- Source problem instance 1, expected target problem instance 1
25-
- Source problem instance 2, expected target problem instance 2
26-
]
27-
28-
## Round trip example to show
29-
[
30-
The example shown in the typst manual, focus on human verifiability. It usually includes
31-
- a short description to what it is about
32-
- the proposed source problem instance
33-
]
10+
**Source:** <!-- e.g. MaximumIndependentSet. Browse existing problems: https://codingthrust.github.io/problem-reductions/ -->
11+
**Target:** <!-- e.g. QUBO -->
12+
**Reference:** <!-- URL, paper, or textbook citation for this reduction -->
13+
14+
## Reduction Algorithm
15+
16+
<!-- How to construct a Target instance from a Source instance.
17+
18+
1. Define notation: list all symbols for the source instance (e.g. G=(V,E), n=|V|, m=|E|)
19+
and the target instance (e.g. Q ∈ R^{n×n}).
20+
2. Variable mapping: how source variables map to target variables.
21+
3. Constraint/objective transformation: formulas, penalty terms, etc.
22+
23+
Solution extraction follows from the variable mapping, no need to describe separately.
24+
-->
25+
26+
## Size Overhead
27+
28+
<!-- How large is the target instance as a polynomial of the source size?
29+
Use the symbols defined in the Reduction Algorithm above.
30+
Also provide the code-level metric name (from the problem's `problem_size()` method). -->
31+
32+
| Target metric (code name) | Polynomial (using symbols above) |
33+
|----------------------------|----------------------------------|
34+
| <!-- e.g. num_vars --> | <!-- e.g. n = |V| --> |
35+
| <!-- e.g. num_edges --> | <!-- e.g. m = |E| --> |
36+
37+
## Validation Method
38+
39+
<!-- How to verify the reduction is correct beyond closed-loop testing?
40+
E.g.
41+
- Generate ground truth from ProblemReductions.jl: https://github.com/GiggleLiu/ProblemReductions.jl
42+
- Compare source/target instance pairs against known results
43+
- Use external solver to cross-check
44+
-->
45+
46+
## Example Source Instance
47+
48+
<!-- A small but non-trivial source instance for the paper illustration.
49+
Must be small enough for brute-force solving, but large enough to exercise the reduction meaningfully.
50+
Only provide the source — the example code auto-generates the target instance, solutions, and JSON.
51+
52+
E.g. "Petersen graph: |V|=10, |E|=15, 3-regular"
53+
-->

0 commit comments

Comments
 (0)