Keep The Pool Full Agent Skill

keep-the-pool-full

Once implementation, review and merging are automated, the bottleneck moves upstream to supply. Agents with nothing well-defined to pick up either sit idle or invent work. This skill keeps a pool of issues that an agent can take, finish and land on its own: each one is real, independently mergeable, small, checkable and not a duplicate. The human job shifts from "build X" to setting the pool's target and its sources.

When to use

• The count of ready issues is below the target, or will be within a day at current throughput.
• A delivery loop or a set of worker automations reports NOOP(no eligible work) repeatedly.
• On a schedule (daily, or every few hours during an active run).

When not to use

• No one or nothing is consuming the pool. Filing issues nobody picks up is noise.
• The work needs product decisions that haven't been made. File one decision issue for a human instead.
• The repo's maintainers haven't agreed to agent-filed issues. Ask once; on other people's repos default to DRY_RUN.

Steps

• Measure the pool. Count open issues matching POOL_QUERY (default is:open is:issue label:ready no:assignee). Measure consumption: ready issues closed or assigned per day over the last 7 days. Pool coverage = pool size / daily consumption, in days.
• Decide whether to file. If coverage ≥ TARGET_DAYS, end NOOP(pool healthy: N issues, C days) and post nothing. Otherwise the deficit is ceil(TARGET_DAYS × consumption) − pool, capped at MAX_FILED_PER_RUN.
• Mine sources, in SOURCES order. Each candidate must cite evidence a reader can check:
• failing or quarantined tests, and flake-tracking issues;
• TODO/FIXME with an owner-free, local fix;
• gaps between a spec, doc or reference implementation and the code;
• audit and report outputs (perf, accessibility, security, dependency) already in the repo or its issues;
• user reports that are confirmed but lack an actionable task;
• follow-ups promised in merged PR descriptions or review replies.
• Shape each candidate into an issue using the checklist below. Split anything over SIZE_CAP into independent issues, not a dependency chain. If a candidate can't be made independently mergeable, drop it or file it as one human-decision issue.
• Deduplicate. Search open and recently closed issues and open PRs for the same file, symbol, test name or error string. Embed a source fingerprint in the body (<!-- pool-source: <kind>:<path-or-test>:<hash> -->) and search for it before filing. If a match exists, comment the new evidence on it once (if allowed) instead of filing.
• File and label. Create the issue with READY_LABEL and the area label. Never assign it; consumers claim work by assignment or linked PR.
• Report. One line per run: pool: before → after (target T, coverage C days), filed n, skipped-duplicate d, dropped k. Silent when nothing was filed.

Issue-quality checklist

• Title says the change, not the symptom ("Make X cache key include Y", not "X is slow").
• Why: one sentence plus the source evidence link (test run, file and line, report, user issue).
• Done when: an observable acceptance check, ideally a command or test that fails now and passes after. If you can't write one, the issue isn't ready.
• Loop: how the implementer verifies it (see find-the-loop).
• Scope hint: the files or area likely touched, and what is out of scope.
• Size: expected diff under SIZE_CAP; one PR; no ordering dependency on other open issues.
• Safety: no secrets, credentials, internal links or personal data copied from the source.

Dials

| Dial | Default | Options |

|---|---|---|

| POOL_QUERY | is:open is:issue label:ready no:assignee | Any issue search |

| TARGET_DAYS | 2 days of consumption | Integer; or a fixed count |

| MAX_FILED_PER_RUN | 5 | Integer; keep low until the invalid rate is known |

| SIZE_CAP | One PR, about 200 changed lines | Lines or files |

| SOURCES | tests, todos, gaps, audits, reports, follow-ups | Any subset, in priority order |

| READY_LABEL | ready | Repo label |

| Mode | file on repos you own; dry_run elsewhere | dry_run (write a candidate list only), file |

| Autonomy | L0 (issues only) | This skill never writes code; see docs/autonomy.md |

Running it as an automation

Use automate-it. Trigger: interval: daily (or hourly during an active delivery run). Tools: github/search_issues, github/search_pull_requests, github/issue_read, github/get_file_contents, github/search_code, github/actions_list, github/get_job_logs, github/list_label, github/create_issue, github/update_issue_labels, plus github/add_issue_comment if dedupe-comments are on. write_scope: repository (there is no triggering resource). Create it paused and dry-run it once; read the candidate list before enabling.

Outputs

• New issues labeled ready, each with evidence, acceptance check, loop and size.
• A per-run line in the run summary or ledger.

This skill's own feedback loop

Track weekly, per source:

• Pick-up rate: filed issues claimed within TARGET_DAYS.
• Merged-per-filed: filed issues closed by a merged PR.
• Invalid rate: filed issues closed as not planned, duplicate or invalid. Above 20% for a source → tighten or drop that source.
• Pool coverage over time. If the pool drains to zero every day, raise TARGET_DAYS or MAX_FILED_PER_RUN; if issues age past 14 days unclaimed, lower them.

Failure modes it prevents

• Idle workers, or workers inventing their own work.
• Big, coupled issues that stall review and CI.
• Duplicate issues from multiple agents mining the same failure.
• "Ready" issues with no way to tell when they're done.

Why this exists

• In one unattended delivery loop, once implement, review and merge were automated, supply became the bottleneck. The human's prompts shifted from "build X" to "file real, independently mergeable issues and keep the pool full."
• "The answer can never be that we have nothing to do": idle was fixed with a standing backlog, not with more agents.
• Small, independently mergeable units are what let review, CI and merge keep up without a human; large units stalled.
• A backlog curation job run every 30–60 minutes also served as recovery memory when the coordinating session went down.