| 1 | # Issue Triage |
| 2 | |
| 3 | Triage aims issues at the agent-ready standard defined in |
| 4 | [AGENT_READY_ISSUES.md](./AGENT_READY_ISSUES.md): bodies that a fresh agent |
| 5 | can execute without extra context. This page covers the stale/`needs-info` |
| 6 | lifecycle that runs alongside that standard. |
| 7 | |
| 8 | ## Stale `needs-info` cleanup |
| 9 | |
| 10 | The stale workflow only acts on issues that a maintainer has explicitly labeled |
| 11 | `needs-info`. This keeps old roadmap, release, security, and current milestone |
| 12 | work out of automatic cleanup unless a maintainer first marks the issue as |
| 13 | waiting on reporter input. |
| 14 | |
| 15 | Required labels: |
| 16 | |
| 17 | - `needs-info`: waiting on reporter information or current-version reproduction details. |
| 18 | - `stale`: inactive `needs-info` issue pending automatic closure. |
| 19 | - `keep-open`: protected because maintainers intentionally keep it open. |
| 20 | - `pinned`: protected maintainer issue. |
| 21 | |
| 22 | Protected labels for stale cleanup: |
| 23 | |
| 24 | - `pinned` |
| 25 | - `keep-open` |
| 26 | - `release-blocker` |
| 27 | - `security` |
| 28 | |
| 29 | A `bug` issue is not protected just because it is a bug. If a maintainer has |
| 30 | also labeled it `needs-info`, it is eligible for stale warning and closure |
| 31 | unless one of the protected labels above is present. |
| 32 | |
| 33 | ## Dry-run queries |
| 34 | |
| 35 | Run these before changing stale policy or doing a manual cleanup pass: |
| 36 | |
| 37 | ```sh |
| 38 | STALE_CUTOFF=$(python3 -c 'from datetime import date, timedelta; print(date.today() - timedelta(days=45))') |
| 39 | NEEDS_INFO_CUTOFF=$(python3 -c 'from datetime import date, timedelta; print(date.today() - timedelta(days=30))') |
| 40 | |
| 41 | gh issue list --repo Hmbown/CodeWhale --state open \ |
| 42 | --search "updated:<${STALE_CUTOFF}" \ |
| 43 | --limit 100 \ |
| 44 | --json number,title,updatedAt,labels,url |
| 45 | |
| 46 | gh issue list --repo Hmbown/CodeWhale --state open \ |
| 47 | --search "label:needs-info updated:<${NEEDS_INFO_CUTOFF}" \ |
| 48 | --limit 100 \ |
| 49 | --json number,title,updatedAt,labels,url |
| 50 | |
| 51 | gh issue list --repo Hmbown/CodeWhale --state open \ |
| 52 | --search "created:<${STALE_CUTOFF} comments:0 -label:keep-open -label:release-blocker -label:security" \ |
| 53 | --limit 100 \ |
| 54 | --json number,title,createdAt,updatedAt,labels,url |
| 55 | ``` |
| 56 | |
| 57 | Use `updatedAt`, labels, and current release relevance as the closure basis. |
| 58 | Creation date alone is too aggressive. |
| 59 | |
| 60 | ## First cleanup pass |
| 61 | |
| 62 | Before relying on automation, perform one manual pass: |
| 63 | |
| 64 | - Label unresolved old bug reports as `needs-info` only after asking for |
| 65 | current-version reproduction details. |
| 66 | - Close obvious GUI, VS Code, and web UI duplicates with links to canonical |
| 67 | desktop/runtime issues. |
| 68 | - Close old brand-discussion issues as superseded when the CodeWhale rebrand |
| 69 | and README/history work already covers them. |
| 70 | - Protect intentional v0.9.0 roadmap shards with `keep-open` or close them as |
| 71 | superseded by a canonical epic. |
| 72 | |
| 73 | Do not close release blockers, security issues, or active milestone work from |
| 74 | stale automation alone. |
| 75 |