issue-plan

name	issue-plan
description	Read a GitHub issue, develop a detailed resolution plan using sequential thinking, rate difficulty/complexity/priority, and label low-priority issues. Use when asked to plan or assess an issue.

Issue Plan & Assessment Workflow

Read a GitHub issue, build a confirmed resolution plan via sequential thinking, append a ratings table to the issue body, and 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 the issue number, title, body, and current labels. You need the full body text — do not rely on the title alone.

---

Step 2: Investigate the codebase

Before planning, understand the relevant code:

1. Check whether the issue is already resolved (the fix is merged on main and the described behavior no longer applies). If so, add a comment explaining what resolved it (commit, PR, or code reference), apply the label resolved (create it first if needed: gh label create resolved --description "Issue already resolved" --color 0E8A16), and stop. Do NOT close the issue — leave that for a human.
2. Identify which crate(s), modules, or files the issue relates to. The workspace contains big-code-analysis (root library), big-code-analysis-cli, big-code-analysis-web, big-code-analysis-py (PyO3 bindings), xtask (man-page generation), and enums (language-enum codegen). Per-language logic lives under src/languages/ (one language_<lang>.rs per supported language) and metric implementations under src/metrics/.
3. Use Serena LSP tools (find_symbol, get_symbols_overview, find_referencing_symbols) — or Grep / Glob if Serena is unavailable — to locate the relevant code paths.
4. Note the scope: how many files, which crate(s), which language modules, whether public API is affected, whether tree-sitter grammar versions are involved.
5. Cross-language sweep: if the issue is in src/languages/ or src/metrics/, check whether the same defect exists in sibling language modules. A bug in one usually exists in several.

---

Step 3: Develop a resolution plan using sequential thinking

Reason through the resolution step by step. If the sequential-thinking:sequentialthinking MCP tool is available, use it (start with thoughtNumber: 1, a totalThoughts estimate of typically 5–8, and nextThoughtNeeded: true); otherwise work through the same phases inline. The reasoning MUST:

1. Analyze the issue: root cause, affected code, potential approaches.
2. Evaluate trade-offs (simplicity, correctness, performance, scope, risk to public API, risk of cross-language inconsistency).
3. Propose a concrete step-by-step resolution plan.
4. Verify the plan covers edge cases, testing (including snapshot tests under tests/), and documentation needs.
5. Conclude with nextThoughtNeeded: false and a final plan summary.

Adjust totalThoughts up or down as understanding evolves. Use isRevision if earlier reasoning needs correction.

After sequential thinking completes, distill the output into a clean resolution plan with numbered steps.

---

Step 4: Rate the issue

Difficulty (how hard is the implementation?)

• Low: Single file change, obvious fix, < 50 lines.
• Medium: Multiple files or modules, requires careful thought, 50–200 lines. Cross-language fixes that mirror the same change in several language_*.rs files typically land here.
• High: Cross-crate changes, new abstractions, public-API modifications, tree-sitter grammar version bumps, > 200 lines.

Complexity (how many moving parts?)

• Low: Isolated change, single crate, single module.
• Medium: Touches 2–3 modules or coordinates between components.
• High: Systemic change, public-API impact, snapshot churn across many languages, risk of cascading breakage.

Priority (how important is this?)

• Low: Nice-to-have, cosmetic, or affects a rarely-used path.
• Medium: Affects correctness or developer experience but has workarounds.
• High: Blocks progress, causes incorrect metric values, security issue, or affects published API correctness.

---

Step 5: Update the issue body

Append to the bottom of the existing body — do NOT replace it.

---

## 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 to avoid shell escaping issues:

cat > /tmp/issue-body.md <<'ISSUE_EOF'
... full updated body ...
ISSUE_EOF
gh issue edit "$ISSUE_NUMBER" --body-file /tmp/issue-body.md

Add a comment summarizing what was done:

gh issue comment "$ISSUE_NUMBER" --body "Added resolution plan and assessment ratings (difficulty/complexity/priority)."

---

Step 6: Apply low-priority label if warranted

If either condition is true, add low-priority:

• Priority rating is Low
• Both Difficulty and Complexity are Low AND Priority is 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"

If applied, mention it in the comment from Step 5 instead of posting a separate comment.

---

Guardrails

• Always plan before rating: Do not skip Step 3 (use the sequential-thinking MCP tool when configured; otherwise reason through the same phases inline).
• Preserve the original body: Append only.
• Temp files for body updates: Always use --body-file.
• No premature closure: Do NOT close the issue. A human decides.
• Be conservative with low-priority: When in doubt, do NOT apply.