ticket_poll
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
02 资源文件 8
- 脚本__init__.py13.0 KB
- 脚本_internal.py10.1 KB
- 脚本cache.py3.4 KB
- 脚本helpers.py12.0 KB
- 脚本mill_states.py3.6 KB
- 脚本ticket_poll_queue.py21.9 KB
- 脚本ticket_poll_read.py16.4 KB
- 脚本ticket_poll_write.py34.2 KB
03 SKILL.md 正文
Ticket Poll — ticket-state lookup, PR merging, and ticket filing via the component roster
You have ticket_poll, ticket_poll_batch, merge_pull_request, mark_ticket_done,
file_ticket, find_ticket_by_pr, prioritize_all_open_tickets, and list_stale_ready_tickets
tools that interact with the mill board API. These tools route through component_request
(roster-based connectivity) when available, falling back to the direct board API when the roster is
unavailable — they are reliable as the primary path for checking ticket state, merging approved PRs,
and filing new tickets.
When to use it
-
Primary ticket-state check —
ticket_pollis your go-to tool for checking a ticket's current state. It uses the same roster-based connectivity ascomponent_requestand is always preferred for single-ticket lookups. -
Independent verification — use
ticket_pollas a second source (alongsidecomponent_request) to satisfy the terminal-state double-check requirement. -
Periodic monitoring — every monitor tick, call
ticket_poll(orcomponent_request) to live-GET the ticket state before reporting any change. -
Bulk triage — use
ticket_poll_batchto fetch full details (state, history, events, comments) for many tickets in one call, then classify them by failure signature. -
Merge approved PRs — use
merge_pull_requestwhen a ticket is inwaiting_auto_mergeorhuman_mr_approvalstate and its associated PR has been approved. This directly calls the mill board's merge-now endpoint, bypassing the need for auto-merge to be enabled on the target repository. -
Find ticket by PR — use
find_ticket_by_prwhen you know a PR URL (e.g.https://github.com/owner/repo/pull/656) but not the associated ticket ID. This is a direct lookup — one API round-trip instead of enumerating all tickets and filtering client-side. -
File a new ticket — use
file_ticketto create a new ticket on the mill board. Use this when you identify a deferred improvement, follow-up task, or actionable item during a session — especially when the user has granted autonomy and the improvement would prevent recurring manual decisions. Always mention the filed ticket in your final summary so the user is aware. -
Route to an external repo — when a user request belongs in a different repository (e.g. a model-routing or provider change belongs in
robotsix-llmio, notrobotsix-chat), usefile_ticketwith the appropriaterepo_idto dispatch the ticket to that repo's board. This is the primary mechanism for routing out-of-scope requests to the correct team — do not tell the user "I can't do that because it's in a different repo" when you can file the ticket for them. Known external repo ids includerobotsix-llmio,robotsix-mill,robotsix-standards, androbotsix-central-deploy. -
Resolve a repo id to GitHub — use
resolve_repo(repo_id)before calling any GitHub tool (list_open_prs,fetch_repo_for_study, PR inspection) with a repository you only know by its millrepo_id(e.g.robotsix-central-deploy). It reads the mill registry (GET /repos) and parsesowner/repofrom the remote URL. The GitHub account is a personal account, not an organisation named after the fleet — never guess<fleet>/<repo>. -
Queue health monitoring — use
list_stale_ready_ticketsto detect tickets that have been sitting in thereadystate without being picked up by a worker. This surfaces queue stalls so the agent can escalate or notify the operator rather than silently waiting. -
Close a superseded or duplicate ticket — use
mark_ticket_doneto transition a ticket to the terminaldonestate. Use this when a ticket is superseded by another ticket that is alreadyDONEorCLOSED, or when work is confirmed complete. Do NOT ask the operator to close tickets manually on the UI when this tool is available.
Allowed operations
| Tool | Description |
|---|---|
ticket_poll |
HTTP GET to the board API; returns the ticket's current state. |
resolve_repo |
Map a mill repo_id to its GitHub owner/repo via GET /repos. |
ticket_poll_batch |
Concurrent HTTP GETs for multiple tickets; returns full details for triage. |
merge_pull_request |
HTTP POST to merge the approved PR associated with a ticket. |
mark_ticket_ready |
HTTP POST to force a stalled draft/human_issue_approval ticket to ready. |
mark_ticket_done |
HTTP POST to close a ticket by transitioning it to the terminal done state. |
find_ticket_by_pr |
HTTP GET to find the ticket linked to a given PR URL. |
prioritize_all_open_tickets |
Lists all open, unflagged tickets and sets priority on every one in a batch. |
list_stale_ready_tickets |
Lists tickets stuck in ready beyond the staleness threshold. |
file_ticket |
HTTP POST to /tickets/ingest to file a new ticket on the board. |
The tool signatures are:
ticket_poll(ticket_id: str) -> str
ticket_poll_batch(ticket_ids: list[str]) -> str
merge_pull_request(ticket_id: str) -> str
mark_ticket_ready(ticket_id: str, justification: str = "") -> str
mark_ticket_done(ticket_id: str, justification: str = "") -> str
find_ticket_by_pr(pr_url: str) -> str
prioritize_all_open_tickets() -> str
list_stale_ready_tickets() -> str
file_ticket(title: str, description: str = "", kind: str = "task", repo_id: str = "") -> str
Lifecycle and priority mutation endpoints (via component_request)
When you need to change a ticket's state or priority, use component_request with the correct HTTP
method and path below. Never guess or fabricate paths — every mutating operation on a ticket has
a documented endpoint. Guessing a wrong method (e.g. PATCH) or a wrong path (e.g. /prioritize)
causes 4xx errors and wastes turns.
| Operation | Method | Path | Notes |
|---|---|---|---|
| Toggle priority | POST | /tickets/{id}/priority |
Set or clear a ticket's priority flag. |
| Resume blocked | POST | /tickets/{id}/resume-blocked |
Body: {"justification": "why this ticket can safely resume now"}. |
| Force to ready | POST | /tickets/{id}/mark-ready |
Transition a stalled draft / human_issue_approval ticket to ready. Body (optional): {"justification": "why this ticket can move to ready"}. Prefer the dedicated mark_ticket_ready tool. |
| Mark done | POST | /tickets/{id}/mark-done |
Transition a ticket to the terminal done state. Prefer the dedicated mark_ticket_done tool. |
| Merge PR | POST | /tickets/{id}/merge-now |
Prefer the dedicated merge_pull_request tool. |
| File a new ticket | POST | /tickets/ingest |
Submit a ticket spec for ingestion into the board. Prefer the dedicated file_ticket tool. |
| Read ticket state | GET | /tickets/{id} |
Prefer the dedicated ticket_poll / ticket_poll_batch tools. |
| List tickets | GET | /tickets |
Query parameters: state, limit, etc. |
All mutation endpoints require authorization — the component_request tool applies the correct auth
headers from the roster automatically. However, mutations must still be authorized by the
operator before you call them (see the main prompt's MUTATION AUTHORIZATION section).
Anti-patterns — do NOT do these:
PATCH /tickets/{id}— there is no PATCH endpoint for tickets; use POST with the specific path.POST /prioritizeorPOST /tickets/prioritize— the correct path is/tickets/{id}/priority.- Guessing a path from an operation name — always consult this table first.
Return values
ticket_poll
A JSON string with these fields:
ticket_id— the ticket identifier you suppliedstate— the ticket's current state string, one of the real mill states:draft,human_issue_approval,ready,code_review,documenting,deliverable,implement_complete,human_mr_approval,waiting_auto_merge,rebasing,fixing_ci,addressing_review,done,closed,blocked,errored,awaiting_user_reply,epic_open,epic_closed(there is NOin_progress,approvedorreviewstate);nullwhen the state could not be determinederror— empty string on success, or a diagnostic message on failurepr_url— the ticket's pull-request URL, ornulldelivered—truewhen adone/closedticket has apr_urlor passed through a merge state (implement_complete,human_mr_approval,waiting_auto_merge,done). Aclosedticket with a PR is delivered, not dropped —closedfollowsdonewhen the retrospect finishes.delivery_note— e.g."closed after delivery (retrospect): PR <url>", ornullunexpected_terminal— a human-readable diagnostic string ONLY when the ticket reachedclosed/donewith no PR and without ever entering an active-work or merge state (thedraft → closed/ready → closedshape);nullotherwise. Before telling the operator that work was dropped, quotestate,pr_urlanddeliveredfrom this tool — never infer "dropped" fromclosedalone.cache_caveat— (present only when the board API was unreachable and the response was served from the ticket-state cache) a human-readable staleness note, e.g.[last-known state — board API unreachable; showing cached state from 120s ago]. Entries older than 1 hour are flagged asstale.
resolve_repo
A JSON string:
{"repo_id", "full_name": "owner/repo", "owner", "repo", "forge_remote_url", "error": ""}. When the
id is unknown: full_name: null, an error, and known_repo_ids listing the registered ids — pick
one of those or pass an explicit owner/repo.
ticket_poll_batch
A JSON string with a tickets array. Each element has:
ticket_id— the ticket identifierstate— the ticket's current state string (ornull)data— the full JSON response fromGET /tickets/{id}(includes events, history, comments, cycle metadata)error— empty string on success, or a diagnostic message on failureunexpected_terminal— same semantics as inticket_pollabove
merge_pull_request
A status message string from the mill API — either a success confirmation or an error describing why the merge failed (e.g. the PR is not approved, conflicts exist, or required status checks have not passed). The tool routes through the component roster when available, falling back to the direct board API on any failure.
find_ticket_by_pr
A JSON string with these fields:
ticket_id— the full ticket ID of the matching ticket, ornullwhen no match was foundstate— the ticket's current state string, ornullpr_url— the PR URL that was looked up (echoed back)error— empty string on success, or a diagnostic message when no matching ticket was found or the board API was unreachable
list_stale_ready_tickets
A JSON string with these fields:
stale_ready_count— number of tickets inreadystate whose last-update timestamp exceeds the staleness thresholdtotal_ready— total number of tickets currently inreadystate (for context)threshold_minutes— the configured staleness threshold (fromautonomous.ready_staleness_minutes)stale_tickets— an array of stale ticket objects, each with:ticket_id— the ticket's full identifiertitle— the ticket's titlestate— always"READY"(only ready-state tickets are returned)staleness— human-readable duration since the ticket's last update (e.g."15m","2.1h")staleness_seconds— the staleness duration as a float (seconds), ornullwhen the ticket has no timestampupdated_at— the ticket'supdated_attimestamp (raw, as returned by the API)created_at— the ticket'screated_attimestamp (raw, as returned by the API)
error— (present only on a listing failure) a diagnostic message when the board ticket list could not be fetched
Tickets are sorted by staleness descending (most stale first). Tickets with no timestamp are
included at the top with staleness: "unknown (no timestamp)" so they are not silently ignored.
Use this tool to detect queue stalls — tickets sitting in ready without being picked up by a
worker — and to decide whether the queue needs operator attention.
prioritize_all_open_tickets
A JSON string with these fields:
prioritized— number of tickets whose priority was successfully setskipped— number of tickets already prioritized (no action taken)errors— number of tickets where the priority toggle failedtotal_open— total number of open tickets considered (prioritized + skipped)results— an array of per-ticket outcome objects, each withticket_id,state,ok(boolean), anderror(empty on success)note— (present when there were no tickets to prioritize) a human-readable message (e.g. "No open, unflagged tickets to prioritize.")error— (present only on a listing failure) a diagnostic message when the board ticket list could not be fetched
This tool replaces the manual sequence of listing tickets, identifying unflagged ones, and toggling priority on each individually. Call it when the user asks to "prioritize tickets" or "prioritize all open tickets."
file_ticket
A JSON string with these fields:
ticket_id— the created ticket's ID on success (e.g."20260816T161602Z-my-ticket-a3f2")error— empty on success, or a diagnostic message on failure
repo_id pre-validation. When a repo_id is provided, the tool validates it against the
board's registered repo list before calling the ingest API. If the repo_id is not in the list,
the tool returns early with an empty ticket_id and an error of the form:
{"ticket_id": "", "error": "repo_id '<value>' is not registered on this board. Available repos: <list>. Verify the repo_id matches one listed by GET /repos on the target board, or check that the agent is connected to the correct board."}
Validation is best-effort: when the repo list is unreachable (network error, timeout), the check is skipped and filing proceeds without validation — the board API's own 404 is the fallback guard.
ID resolution
Both ticket_poll and ticket_poll_batch resolve paraphrased / abbreviated ticket IDs against the
live board before making any per-ticket request. This means you can pass an ID derived from
narrative text (e.g. ...-my-ticket-a3f2) and it will be mapped to the full ticket ID on the board.
Resolution tries, in order:
- Exact match — the candidate ID appears verbatim on the board.
- Hash-suffix match — the last 4 hex chars (e.g.
a3f2) uniquely match one ticket. - Slug-substring match — the non-timestamp portion appears as a substring of exactly one ticket's full ID.
When resolution succeeds, the resolved full ID is used for the request and returned in the response. When it fails — the candidate is ambiguous or the board is unreachable — the original ID is still attempted (which may surface a 404).
Safety
ticket_poll/ticket_poll_batch/list_stale_ready_ticketsare read-only — GET only; no state mutation is possible through these tools.merge_pull_requestandprioritize_all_open_ticketsare mutating — they issue POST requests that alter ticket state. Only call them when the preconditions are met:merge_pull_requestrequires an approved PR inwaiting_auto_mergeorhuman_mr_approvalstate;prioritize_all_open_ticketsshould be called when the operator asks to prioritize tickets. Do not call either speculatively.- Roster-first routing — prefers the component roster (
component_request) when available; falls back to the direct board API when the roster is absent. This means the tools share the same connectivity path ascomponent_requestand are equally reliable. - Timeout — each request has a short timeout; failures are per-ticket (one down ticket won't break the batch).
- Connectivity vs. state. A tool call failure (timeout, unreachable, HTTP 5xx, DNS error) is a transient I/O error — it tells you nothing about the ticket's actual state. Do not conflate "the API returned an error" with "the ticket is closed," "the ticket is being tracked by a monitor," or any other conclusion about the ticket. When a call fails, report the failure honestly (e.g. "could not reach the board API — will retry") and do not fabricate state from the absence of data. Only state facts about a ticket when you have a successful response containing those facts.
- Graceful degradation via ticket-state cache. When the board API is unreachable,
ticket_pollfalls back to the last-known state from an in-memory cache (populated by mill push events and prior successful polls). The cached response includes acache_caveatfield with a staleness note (e.g.[last-known state — board API unreachable; showing cached state from 120s ago]). Use this to surface last-known state with an honest caveat rather than saying "I can't confirm." Entries older than 1 hour are flagged asstale. Only state facts about a ticket when you have a successful response containing those facts.
Example calls
# Basic state check
ticket_poll("20250101T120000Z-my-ticket-a1b2")
# Bulk triage of blocked tickets — fetch all at once, then classify
ticket_poll_batch(
[
"20250101T120000Z-ticket-a-a1b2",
"20250102T090000Z-ticket-b-c3d4",
"20250102T150000Z-ticket-c-e5f6",
]
)
# → inspect each ticket's data.events history to identify failure signatures:
# "implement-loop/3of3", "git-failure", "capability-gap", ...
# Combined with component_request for double-check (terminal-state verification)
# 1. ticket_poll("20250101T120000Z-my-ticket-a1b2") → state: "DONE"
# 2. component_request("mill", "GET", "/tickets/...") → confirm: "DONE"
# Merge an approved PR when a ticket is in waiting_auto_merge or human_mr_approval
merge_pull_request("20250101T120000Z-my-ticket-a1b2")
# → "HTTP 200\n{\"status\": \"merged\", ...}"
# Prioritize all open, unflagged tickets in a single call
prioritize_all_open_tickets()
# → {"prioritized": 5, "skipped": 2, "errors": 0, "total_open": 7, "results": [...]}
# Detect tickets stuck in the ready queue
list_stale_ready_tickets()
# → {"stale_ready_count": 2, "total_ready": 5, "threshold_minutes": 10,
# "stale_tickets": [{"ticket_id": "...", "staleness": "15m", ...}, ...]}