issue-plan

name	issue-plan
description	Read a GitHub issue, develop a resolution plan via sequential thinking, rate difficulty/complexity/priority, label low-priority when warranted.

Issue Plan & Assessment

Read a GitHub issue, build a confirmed resolution plan via sequential thinking, append a ratings table to the issue body, apply the low-priority label when warranted.

Argument: $ARGUMENTS — a GitHub issue number (e.g. 42 or #42).

---

Step 1: Read the issue

gh issue view "$ISSUE_NUMBER" --json number,title,body,labels

Record number, title, body, current labels. Read the full body — do not rely on the title alone.

---

Step 2: Investigate

1. Check whether already resolved on main. If so: comment with the resolving commit/PR, apply resolved label (create with gh label create resolved --description "Already resolved" --color 0E8A16 if missing), stop. Do NOT close — leave that for a human.
2. Identify the affected component:
   • grammar.js — grammar rule
   • src/scanner.c — external scanner
   • queries/groovy/*.scm — highlights / folds / indents / injections
   • bindings/<lang>/ — language binding
   • test/corpus/ or test/highlight/ — tests
   • SPECIFICATION.md — design document (rare; only when the issue calls out a spec inconsistency or missing decision)
3. Use Grep / Glob to locate relevant code paths. Re-read the relevant SPECIFICATION.md section before proposing a fix that changes grammar shape.
4. Note scope: how many files, public-API impact (bindings/rust/lib.rs re-exports), test churn expected.

---

Step 3: Resolution plan via sequential thinking

Use sequential-thinking:sequentialthinking. The thinking MUST:

1. Start with thoughtNumber: 1, totalThoughts ~5–8, nextThoughtNeeded: true.
2. Analyze: root cause, affected code, candidate approaches.
3. Evaluate trade-offs: simplicity, correctness, scope, risk to bindings or downstream consumers (dekobon/big-code-analysis, editor plugins).
4. Propose concrete numbered steps.
5. Verify edge cases, tests (corpus + highlight), and docs are covered.
6. Conclude with nextThoughtNeeded: false and a final summary.

Distill into a clean numbered resolution plan.

---

Step 4: Rate the issue

Difficulty

• Low: single rule / single query / single test addition; obvious fix.
• Medium: grammar + queries + tests across 2–3 files; careful but bounded.
• High: scanner changes, ambiguity resolution, breaking AST shape, or cross-binding work.

Complexity

• Low: isolated change; no AST shape churn; no binding fan-out.
• Medium: AST shape changes; corpus tests need to be updated; one binding affected.
• High: AST shape change cascades through every binding; many corpus tests need to move; downstream consumers (e.g. nvim-treesitter configs, dekobon/big-code-analysis metric impls) must update.

Priority

• Low: cosmetic, rare path, stylistic.
• Medium: affects correctness in some inputs but workarounds exist.
• High: affects correctness on common Groovy / Jenkinsfile / Gradle patterns, blocks downstream consumers, security.

---

Step 5: Update issue body

Append — do not replace.

---

## Resolution Plan

<!-- Generated by issue-plan skill -->

1. Step one...
2. Step two...
3. ...

## Assessment

| Dimension  | Rating |
|------------|--------|
| Difficulty | Low / Medium / High |
| Complexity | Low / Medium / High |
| Priority   | Low / Medium / High |

Use --body-file:

cat > /tmp/issue-body.md <<'ISSUE_EOF'
... full updated body ...
ISSUE_EOF
gh issue edit "$ISSUE_NUMBER" --body-file /tmp/issue-body.md
gh issue comment "$ISSUE_NUMBER" --body "Added resolution plan and assessment ratings."

---

Step 6: Apply low-priority if warranted

If either condition: Priority Low; or both Difficulty and Complexity Low AND Priority not High:

ensure_label() {
  local name="$1" color="$2" desc="$3"
  if ! gh label list --limit 200 --json name --jq '.[].name' | grep -qx "$name"; then
    gh label create "$name" --color "$color" --description "$desc"
  fi
}
ensure_label low-priority "fef2c0" "Low priority issue"
gh issue edit "$ISSUE_NUMBER" --add-label "low-priority"

Mention in the Step 5 comment instead of posting separately.

---

Guardrails

• Always sequential-think — do not skip Step 3.
• Append to body, never replace.
• Use --body-file for any non-trivial edit.
• Never close the issue — that is a human decision.
• Be conservative with low-priority — when in doubt, do not apply.