pm-improve

What this skill does

# PM Improve

Enrich an issue with the context that makes it actionable — repo references, prior-art links, best-practice pointers, and clarifying questions. Distinct from `pm-review` (which is **structural**) and `pm-issues` (which is **lifecycle**). This skill answers: *"if a teammate picked this up tomorrow, what would they need to know that's not in the body?"*

The enrichment is suggestive, not authoritative. It's a *draft set of additions* for the operator to evaluate — they decide what's worth pasting into the issue body or posting as a comment.

## When to run this

- After `pm-review` returned a "needs more information" verdict and the gap is **context** (not "fill the acceptance criteria").
- When grooming an issue before assigning it to someone unfamiliar with the area.
- When the issue was filed by a stakeholder who lacks repo-level context (PM, designer, support engineer).
- **Not** for issues that are already detailed and clear — running this on a well-written issue produces noise.

### Safe to re-run

`pm-improve` is **deliberately non-idempotent** — re-running it after time has passed surfaces new commits, new related issues, and new clarifying questions as the repo and tracker evolve. That's a feature, not a bug: an issue that sat in the backlog for a month genuinely has more context around it now than it did when filed.

To prevent comment stacking, the `--apply` path embeds a marker (`<!-- pm-improve: … -->`) and detects prior pm-improve comments on the issue — the operator chooses whether to **replace** the old enrichment or **add** a new one. The marker is matched by prefix (not version), so upgrades don't break recognition.

## Four enrichment streams

The skill produces up to four blocks. Each is optional — if a stream returns nothing useful, omit it (do not pad).

### 1. Repo context

Find the files, modules, and recent changes most likely relevant to this issue.

Heuristics that have worked in practice:
- **Title/body keywords → file matches.** Run `grep -r -l` for the most specific nouns in the title against the repo. Filter out vendored / build directories. Aim for **3-7 file hits**, not 50.
- **Recent commits.** `git log --since="3 months ago" -i --grep="<keyword>" --oneline` for each of the top keywords. Cap at 5 commits per keyword.
- **Owners.** If `CODEOWNERS` exists and any matched file falls under a codeowner block, surface the owner(s).
- **Related symbol definitions.** For bugs especially, if a function/class name appears in the body, locate where it's defined.

Output as a tight list — file paths with one-line "why" annotations:

```
**Repo context**
- `src/auth/middleware.ts:42` — session-validation logic, mentioned in body
- `src/auth/__tests__/middleware.test.ts` — existing tests near the affected area
- Recent change: 8a1f3d2 (3 weeks ago) "fix: handle expired JWT in refresh path"
- CODEOWNERS: @auth-team
```

If the repo isn't accessible or grep returns nothing, omit the block entirely — do not write "No repo context found."

### 2. Best-practice / domain references

If the issue touches a topic with established best practices, point at the canonical reference. **Only when it's actually useful** — citing a Wikipedia page on "what is a bug" is not useful.

Selection rule: would a senior engineer in this area actually paste this link in code review? If not, skip it.

When the project has registered SME repos via the `repo-sme` plugin, prefer those — they're already curated:

```bash
# Check for SME registrations
ls ~/.claude/repo-sme/repos/ 2>/dev/null
```

If a registered SME repo plausibly applies (e.g., issue is about Obsidian plugin API, and `obsidian-api` is registered), suggest the operator delegate the question to the SME agent rather than padding the issue with links:

```
**Suggested next step:** Run `repo-sme query obsidian-api "<question>"` for grounded API context before posting links.
```

### 3. Related issues / prior art

Search the tracker for issues that share keywords with this one. The goal is to surface **dupes, prerequisites, and follow-ups** — not the top-10 most-recent issues:

```bash
# Linear
linear issue query --json --search "<top 2-3 keywords>" --team <team_key> --limit 10 --no-pager

# GitHub
gh issue list --repo <org/repo> --search "<keywords>" --state all --limit 10 --json number,title,state,url
```

Filter aggressively. For each candidate, decide: is this a duplicate, a parent, a child, a peer, or unrelated? Drop "unrelated". Cap the surfaced list at **5 entries**.

```
**Related issues**
- ENG-31 (closed): "JWT refresh fails on Safari" — likely related; same auth surface
- ENG-58 (open):  "session middleware refactor" — possible prerequisite, check ordering
```

### 4. Clarifying questions (Q&A)

The hardest stream, and the most valuable. Generate questions whose answers would unblock implementation. **Each question must be specific enough that the operator can answer it in one sentence.**

Bad questions to avoid:
- *"What are the acceptance criteria?"* — that's the operator's job, not yours to ask.
- *"How should this work?"* — too open.
- *"Have you considered ...?"* — leading, condescending.

Good questions:
- *"Should expired refresh tokens trigger a full re-login, or fall through to the session-renewal endpoint? Existing middleware at `src/auth/middleware.ts:42` does the latter."*
- *"Is this scoped to the web client only, or should the iOS app also be updated? The mobile auth flow is separate."*

Cap at **3-5 questions**. If you can't generate genuinely useful ones, omit the block.

### Stuck-aware enrichment

When enriching an issue, check whether the issue ID appears in the `stuck` lens output (via `pm-cache.js lens --slug <slug> --lens stuck`). If yes, prepend the enrichment prompt with:

> "This issue is flagged stuck for: `<reasons>`. Propose the specific unblock action the assignee needs to take, in addition to any general enrichment."

This makes enrichment unblock-aware. The lens result's `byIssue` map (now plain object from the `lens` verb) lets you look up `<issue_id>` → reasons array (e.g., `['stale', 'no_update']`).

## Workflow

### Step 1: Fetch and parse the issue

Same fetch logic as `pm-review`. Cache the body, labels, and title.

### Step 2: Classify the tag

Use `pm-templates`' classifier. The tag biases which enrichment streams matter:
- **bug** → repo context (files near the failure) and related issues (likely dupes) are usually most valuable
- **feature** → best-practice references and clarifying questions
- **task** / **chore** → minimal enrichment usually — most context is in the title
- **spike** → clarifying questions about scope and time-box

### Step 3: Run the four streams in parallel

Each stream is independent. If any one fails (network error, missing CODEOWNERS), continue with the others — log the failure but don't block the rest.

### Step 4: Apply project conventions and compose the draft

**Conventions pass first.** If `<repo>/.claude/pm/conventions.md` exists, consult its `## Issue enrichment` section (and any tag-specific guidance) before composing. Examples of what conventions might dictate:

- *"Every bug must link to the failing test path."* → inject into the Repo context stream
- *"Don't link external docs unless they're from a registered SME repo."* → trim the Best-practice references stream
- *"Always include the parent issue ID for sub-issues."* → inject into Related issues

Apply convention rules as additional content for the relevant stream — do not invent a "Conventions" block in the draft (that's the reviewer's shape, not enrichment's).

**Then compose.**

Combine non-empty streams into a single markdown block, header `## Context (added by pm-improve)`:

```markdown
## Context (added by pm-improve)

**Repo context**
- `src/auth/middleware.ts:42` — session-validation logic, mentioned in body
- Recent change: 8a1f3d2 "fix: handle expired JWT in refresh path"

**Related issues**
- ENG-31 (closed): "JWT refresh fails on Safari