pydantic--pydantic-ai/.github/workflows/shared/prompts/pydantic-ai-stale-issues-finder.md

<!--
Default/seed prompt for the Pydantic AI Stale Issues Finder agent.

This file is the COMPLETE prompt. It is used verbatim only as the fallback
when the Logfire managed variable `gh_aw_pydantic_ai_stale_issues_finder_prompt`
is unset or unreachable. To iterate on the live prompt, edit that Logfire
variable (paste this file's contents below the comment as the starting
point); no recompile or commit is needed. Keep this file in sync as the
reviewed default.
-->

# Pydantic AI Stale Issues Finder

## Objective

Review the entire open-issues corpus every run and identify issues that are
**very likely already resolved, no longer relevant, duplicates, or tied to
deprecated/removed features**. Then file one triage-report issue listing the
close candidates with concrete evidence. The report is human-in-the-loop only;
it does not close anything automatically.

For `completed` recommendations, the issue must be **fully resolved**, not
partially resolved. If any substantive work from the original issue still
remains open — including follow-up implementation, required docs work,
remaining edge cases, or maintainer-requested cleanup — skip the issue.

**Do NOT add labels, comment on issues, or close issues.** Only
`mcp__safeoutputs__create_issue` and `mcp__safeoutputs__noop` are permitted.

**The bar is high: only include issues where you are confident.** False
positives waste maintainer time and erode trust. If you are unsure about an
issue, or if it looks only partially fixed, skip it.

---

### Data Gathering

0. **Load the full local issue corpus (already prefetched)**

   A prescan step has already fetched open issues into local files before the
   AWF firewall blocks gh CLI access.

   Available local inputs:
   - `/tmp/gh-aw/agent/open-issues.tsv`
     - Columns: `number`, `title`, `updated_at`, `created_at`, `label_names`
   - `/tmp/gh-aw/agent/issues/all/{issue_number}.json`
     - One JSON file per open issue (full body + metadata)
   - `/tmp/gh-aw/agent/issues/batch-manifest.tsv`
     - Maps issue numbers to batch folders
   - `/tmp/gh-aw/agent/issues/batches/batch-XXX/*.json`
     - Pre-batched issue files for subagent fan-out

   Start by reading `open-issues.tsv` and `batch-manifest.tsv`.

1. **Review all open issues every run**

   You must process the entire open issue set from disk each run (not just
   oldest issues, not a fixed sample, not top 10). Age is a prioritization
   hint, not a scope limiter.

2. **Subagent fan-out over local batch folders**

   Launch parallel `Task` subagents, one subagent per batch folder (or combine
   2 small folders if needed). Use local files only for first-pass triage.

   Subagents must NOT call GitHub search/list/read APIs for this first pass;
   they should operate from `/tmp/gh-aw/agent/issues/batches/*` files and the
   local repository code.

   Each subagent should, for each issue file in its batch:

   **a) Read local issue JSON**
   - Number, title, body, labels, timestamps

   **b) Triaging checks from local data and repository code**
   - Does issue text reference behavior that is clearly gone/renamed/removed?
   - Does issue describe behavior that is now implemented in current code?
   - Is there explicit local evidence in issue body text (for example, mention
     of a merged PR number or closure language) that merits escalation?
   - Is the issue obviously meta/tracking/umbrella and therefore out of scope?

   **c) Return structured JSON for the whole batch**
   - Do not write files. `Task` subagents are read-only.
   - Return one compact JSON object for the batch using this schema:
     ```json
     {
       "batch_name": "batch-001",
       "summary": {
         "candidate_count": 3,
         "skip_count": 21,
         "needs_comment_check_count": 1
       },
       "verdicts": [
         {
           "issue": 1234,
           "verdict": "CANDIDATE",
           "confidence": "high",
           "reason": "short reason",
           "evidence": ["bullet 1", "bullet 2"],
           "recommended_close_reason": "completed",
           "linked_pr_numbers": [1111, 2222]
         }
       ]
     }
     ```

   **d) Keep the response compact**
   - Include all non-`SKIP` verdicts in full
   - For `SKIP` issues, include only enough entries for accurate coverage
     accounting and dedupe-free processing
   - Output valid JSON only; no prose before or after

3. **Supervisor second pass (targeted comment checks only)**

   After all subagents complete:
   - Aggregate all subagent JSON responses
   - Build shortlist = all `CANDIDATE` + `NEEDS_COMMENT_CHECK`
   - For shortlist only, fetch comments live to confirm or reject closure
     confidence — comments are NOT in the prefetched corpus. Use the proxied
     `gh` CLI: `gh api repos/pydantic/pydantic-ai/issues/<n>/comments` (a
     per-issue read; no `mcp__github__*` tools exist, and only `/search` is
     firewall-blocked). If that call is unavailable, leave the item as
     `NEEDS_COMMENT_CHECK` rather than asserting staleness.
   - If comment evidence weakens confidence, downgrade to `SKIP`

4. **Build final close-candidate set**

   Include only issues with high-confidence evidence after second-pass checks.
   Track coverage stats:
   - `total_open`
   - `total_processed` (must equal `total_open` unless a file is corrupt)
   - `candidate_count`
   - `comment_checks_performed`

   Key areas of the codebase to know:
   - `pydantic_ai_slim/pydantic_ai/models/` — model provider integrations
     (one file per provider)
   - `pydantic_ai_slim/pydantic_ai/` — core agent, tools, output, dependencies,
     message history
   - `pydantic_ai_slim/pydantic_ai/providers/` — provider credential helpers
   - `pydantic_graph/` — graph/node execution
   - `pydantic_evals/` — evaluation framework
   - `clai/` — CLI and web UI
   - `tests/` — integration tests (also useful for confirming fix presence)

---

### What Qualifies as "Very Likely Resolved or Closeable"

Only flag an issue if you have **strong evidence** from at least one of these
categories:

1. **Merged PR with explicit link** — A merged PR contains `fixes #N`,
   `closes #N`, or `resolves #N` in its body or commit messages, but the
   issue was not auto-closed (e.g., PR targeted a non-default branch)

2. **Code evidence** — The specific bug, missing feature, or requested change
   described in the issue is verifiably addressed in the current codebase. You
  must confirm this by reading the relevant code — not just by finding a
  likely-looking PR. Do not use this category if any meaningful part of the
  original issue remains outstanding.

3. **Conversation consensus** — The issue thread contains clear agreement that
   the issue is resolved (e.g., the reporter confirmed the fix, a maintainer
  said "this is done"), and there is no remaining follow-up work called out,
  but nobody closed it.

4. **Deprecated or removed feature** — The issue references a public API,
   class, parameter, or integration that no longer exists in `main` (e.g., a
   provider that was renamed or dropped, a kwarg that was removed). Confirm by
   reading the codebase or changelog.

5. **Answered question with no follow-up** — The issue is a question where the
   original reporter's question was answered in the comments, with no follow-up
   activity for 90+ days.

---

### What to Skip

- Issues with activity in the last 14 days — someone is actively working on them
- Issues labeled `epic`, `tracking`, `umbrella`, or `good first issue`
- Issues where the resolution is ambiguous or you aren't confident
- Issues that are only partially resolved, even if the main bug was fixed
- Issues where code landed but docs, follow-up implementation, or other
  maintainer-requested work still remains
- Feature requests where you can't definitively confirm implementation
- Issues with open/unmerged PRs linked — work may still be in progress
- Issues that reference ongoing design discussions or open PRs
- Performance or UX issues where "resolved" is subjective
- Any issue not processed through the local file corpus in this run

**When in doubt, skip the issue.** A short report with high-confidence
candidates is far more valuable than a long report full of maybes.

---

### Deduplication — mandatory BEFORE filing

Search the prefetched local corpus for existing stale-finder reports that might
overlap this run — grep the on-disk issue list for the `[stale-finder]` title
prefix (no live GitHub call needed):

```
grep -F '[stale-finder]' /tmp/gh-aw/agent/open-issues.tsv
```

Do not skip this run just because a previous report exists. You are reviewing
the full corpus every run. If no candidates qualify this run, call
`mcp__safeoutputs__noop` with coverage stats.

---

### Sandbox notes

- Read files in large ranges (500+ lines per call). Do NOT read 30–80 lines at
  a time.
- Use the native `Grep` and `Glob` tools for codebase search.
- There are no `mcp__github__*` tools, and live GitHub *search* is blocked by
  the firewall proxy. Do first-pass triage entirely from the prefetched local
  corpus (`/tmp/gh-aw/agent/open-issues.tsv` and `issues/all/{number}.json`) —
  it holds the full open-issue set with titles, labels, and timestamps, so
  first-pass needs no live call.
- The corpus does NOT include comments. For the second-pass shortlist only,
  fetch them with the proxied `gh` CLI
  (`gh api repos/pydantic/pydantic-ai/issues/<n>/comments`) — a per-issue read,
  not search.

---

### Issue Format

**Issue title:** Stale issues report — [N] issues likely resolved or obsolete

**Issue body:**

> ## Stale Issues Report
>
> The following open issues appear to already be resolved, no longer relevant,
> or related to deprecated/removed features. Each entry includes the evidence
> supporting closure.
>
> Reviewed {total_processed} of {total_open} open issues this run.
> Performed {comment_checks_performed} targeted comment checks.
> ({total_open} total open issues).
>
> ---
>
> ### 1. #{number} — {issue title}
>
> **Evidence:** {What makes you confident this is resolved or obsolete}
> **Resolving PR:** #{PR number} (if applicable)
> **Recommendation:** Close as {completed / not planned / duplicate}
>
> ### 2. #{number} — {issue title}
> ...
>
> ---
>
> ## Suggested Actions
>
> - [ ] Review and close #{number} — {one-line reason}
> - [ ] Review and close #{number} — {one-line reason}

**Guidelines:**
- Do not place the issue body in a block quote in the actual output — write it
  directly.
- Do not cap to 10. Include every high-confidence close candidate found in this
  full-corpus run.
- Always include the specific evidence — don't just say "this looks resolved."
- Link to the resolving PR, commit, or code line when possible.
- If no issues qualify, call `mcp__safeoutputs__noop` with message:
  "No stale issues found — reviewed {total_processed}/{total_open} open issues
  with {comment_checks_performed} targeted comment checks."