Cawplan Plan Track

CawPlan Plan Track

Bootstrap

cawplan skill check

Important CLI constraint — read before writing any ticket-fetch command

cawplan tickets search requires --time_range or --start_date+--end_date unless you're doing an exact --unique_ids/--display_ids/--parent_ids lookup — --version_ids/--product_ids/--priority/--type alone do not satisfy this and the command exits with an error before it even calls the API (see references/CAWPLAN_OPEN_API.md's "Canonical workaround for 'every matching ticket regardless of age' queries" — this skill picks that section's option 2). Release tracking needs tickets regardless of how long ago they were touched, so this skill does not use tickets search for version-wide ticket lists — it uses tickets poll instead, which has no time window at all. tickets poll in turn does not accept --version_ids (only --product_ids/--product_line_ids) — filter down to the target version client-side from its response's version_id field. Don't reintroduce a bare tickets search --version_ids ... call anywhere in this skill; it will fail.

Workflow

Required product-access gate

Before querying any product-, version-, release-, or ticket-scoped data, verify that the caller can see the product through products list. This applies even when the user supplied a product_id directly or it came from an earlier conversation — never treat a known ID as proof of access.

cawplan products list --search "<product name or product_id>"

Continue only when the response contains one intended product (product_id / unique_id). Match a supplied product name exactly (case-insensitively, after trimming whitespace), or accept a unique short-form/token-prefix match; a non-unique similarly named result is only a candidate, never an automatic replacement. If no unique accessible product matches, do not call versions, tickets, product-lines statuses, or any other product-scoped endpoint. If candidates were returned, list their names and ask the user to confirm which product they mean. If no candidates were returned, state that the named product either does not exist or is not accessible to the caller; do not report ticket counts or imply that its ticket list is empty. Return NO_PERMISSION only when the API explicitly reports denied access.

NO_PERMISSION: You do not have access to product "CawCut Cloud".

Never convert an unavailable product into an empty result such as Open Tickets: 0; an empty ticket list is meaningful only after this access gate succeeds.

1. Resolve product name to product_id and complete the required product-access gate:

   cawplan products list --search "<product name>"
   

If no exact or unique short-form product match exists, list any candidates (name + product_id) and ask the user to confirm which product they mean; do not guess. If the lookup returns no candidates, say: 未找到可访问的 product “<name>”：该 product 可能不存在，或你当前没有访问权限，因此无法查询其 tickets。 If more than one match exists, ask the user to pick. Keep the product_line_id (or nested product_line.unique_id — check the actual field name in the response) from the confirmed record.

2. Resolve version name to version_id (skip if already known):

   cawplan versions list <product_id>
   

3. Fetch progress and release history in one call:

   cawplan versions track <product_id> <version_id>
   

   This returns:

   • detail.data.progress — complete_percent, status_counts (COMPLETE / UNSTARTED / STARTED / TESTING / CANCELED)
   • detail.data.risk — LOW / MEDIUM / HIGH
   • detail.data.risk_reason
   • detail.data.extra.target_release — channel name and release_at timestamp
   • detail.data.status — NOT_STARTED / INPROGRESS / RELEASED
   • release.data — release history events (status changes, risk changes)

4. Resolve the product line's status keys (needed by every step below except a plain progress check — run this once, before step 5):

   cawplan product-lines statuses <product_line_id>
   

   This returns each status key with a category (UNSTARTED / STARTED / TESTING / COMPLETE / CANCELED). Build a key→category map, and keep the full list of keys — step 5 needs it.

5. Fetch every ticket for this version in one shared dataset (skip only for a plain progress check with no ticket-level detail requested):

   cawplan tickets poll --product_ids <product_id> --status <every key from step 4, comma-separated> --page_size 200 --page_num 1
   

   --status accepts status keys, not category names. Include every key returned in step 4 — for example, a MONITORING key in the STARTED category must be included; never substitute category names such as UNSTARTED,STARTED,TESTING for this argument. Page through with --page_num if the product has more tickets than one page. This returns tickets across every version of the product (poll has no version filter) — filter the results client-side to version_id == <target version_id> to get this version's set (per the API reference, poll's response includes version_id per ticket precisely so this filtering is possible). Keep both the version-filtered set and the full unfiltered set in memory: steps 6-12 work off the version-filtered set, but step 10 (blocking check) can save a lookup by checking the unfiltered set first when a blocking ticket belongs to a different version. Each result already carries status, priority, type, assignees, updated_at, version_id, parent_id — steps 6-12 are pure filters over this one dataset, no further ticket-list fetches needed except step 10's relation calls.

   This set includes sub-issues (parent_id set) alongside top-level tickets — verified live (a version with versions get-reported progress of 6 top-level COMPLETE tickets out of ~60 top-level had 136 tickets total in poll once sub-issues were counted in). Keep sub-issues in every list below (steps 6-13) — a CRITICAL sub-issue bug is still a real, independently typed/prioritized/assigned ticket someone needs to see. But don't be surprised if a ticket count you report (e.g. "31 unstarted tickets") looks larger than what versions get's progress.status_counts shows for the same version — that field counts top-level tickets only, so the two numbers aren't measuring the same set and shouldn't be presented as if they must reconcile.

5a. Open Tickets (when the user asks for current Version's Open Tickets): from step 5's version-filtered set, include every Ticket whose status key maps to a category other than COMPLETE or CANCELED. UNSTARTED, STARTED, and TESTING are all open categories. Do not use a hard-coded status-key whitelist or infer terminal state from a key/display name: a custom status named Testing in category TESTING is an Open Ticket and must be returned. Group results by resolved status display name/category.

6. Unresolved Critical bugs (only when the user asks about release risk / blockers — skip for a plain progress check): CawPlan tickets have no separate "Blocker" priority; treat priority=CRITICAL as the "Blocker" tier. From step 5's version-filtered set: type=BUGFIX, priority=CRITICAL, status category (step 4's map) not COMPLETE/CANCELED.

7. Features not yet at QA Testing (same trigger as step 6): from step 5's set, type=FEATURE whose status category maps to UNSTARTED or STARTED.

8. Ready for QA / QA Testing ticket list (only when asked — e.g. "what's ready for QA", "what's in QA testing"): from step 5's set, any type, status category TESTING. Steps 10 and 12 reuse this exact list — don't refilter step 5 for it again.

9. Descope suggestions (only when the user explicitly asks what to descope or how to reduce delay risk — never suggest this unprompted):

   • Candidate pool: step 5's version-filtered set. Do not suggest a ticket outside this pool, and do not guess a priority that wasn't returned; if a candidate's priority is genuinely missing, leave it out rather than invent one.
   • Only suggest descoping tickets whose status category is UNSTARTED (work not yet started) — never suggest descoping STARTED, TESTING, or COMPLETE work.
   • Order suggestions LOW priority first, then MEDIUM; never suggest descoping HIGH or CRITICAL priority tickets.
   • Ground every suggestion in risk_reason and step 5's actual ticket list — do not invent a reason not present in risk_reason.

10. What's blocking QA testing (only when asked): for each ticket in step 8's Ready-for-QA/TESTING list, check its blocking relations:

    cawplan tickets relate list <product_id> <version_id> <ticket_id>
    

    For each relation_type=BLOCKED_BY relation, resolve the blocking ticket's own status: check step 5's unfiltered (all-versions) set first, then step 5's version-filtered set if somehow not there, otherwise look it up with cawplan tickets get <product_id> <version_id_of_that_ticket> <ticket_id> — don't assume it's resolved just because you haven't seen it yet. Report only the ones whose status category (step 4's map) is not COMPLETE/CANCELED. This is one relate list call per in-testing ticket — if there are many, tell the user you're scoping to in-testing tickets only rather than silently sampling.

11. Assignee overload (only when asked — "is anyone overloaded", "who has too many high-priority issues"): from step 5's set, priority in CRITICAL/HIGH, status category not COMPLETE/CANCELED. A ticket can have multiple assignees; count it once per assignee, not once total. If a ticket has no assignees at all, don't drop it — report it separately as "unassigned"; an open high-priority ticket nobody owns is worth surfacing on its own. Group by assignee and sort by count descending. If two or more assignees tie for the highest count, report all of them as joint-top — don't arbitrarily pick one. Don't invent a "this counts as overloaded" cutoff (e.g. "3+ is too many") — team capacity norms aren't something you know; report the actual counts per assignee and let the user judge, calling out the top of the ranking (all tied entries, if any) as the most likely answer to "who."

12. Per-QA pending count (only when asked — "how many does each QA still have to verify"): reuse step 8's Ready-for-QA/QA-Testing list. Group by assignees the same way as step 11 (count once per assignee on multi-assignee tickets) and report a count per person. If a ticket in this list has no assignee, report it separately as unassigned rather than dropping it or attributing it to nobody silently.

13. Tickets stale for more than N days (only when asked — "what hasn't been touched in N days"): if the user didn't give N, ask what they mean by "a long time" rather than picking a default — there's no universal norm for what counts as stale. Once you have N: from step 5's set, exclude COMPLETE/CANCELED-category tickets (a resolved ticket that hasn't been touched since isn't "unfixed"), compute (now - updated_at) in days for the rest, and list those exceeding N, oldest first.

Output

Report, scoped to what the user actually asked (don't run steps 4-13 for a plain "track this release" ask):

• Version name, status, and risk level (with reason if MEDIUM or HIGH).
• Completion: X% complete (N done / M total) (round X to a whole number).
• Target release date per channel (convert release_at Unix timestamp to a readable date).
• If step 5a ran: Open Tickets — display ID, type, priority, assignee, short description, grouped by resolved status. Include every non-terminal category, including TESTING.
• Blockers: any CRITICAL or HIGH priority open tickets.
• If step 6/7 ran: unresolved Critical bugs and features not yet at QA Testing, each as its own list (display ID, title, assignee).
• If step 8 ran: the Ready for QA / QA Testing list — display ID, type, title, assignee.
• If step 9 ran: descope suggestions as a ranked list, each with the ticket and the one-line reason it's eligible (priority + status category) — not a restated risk_reason.
• If step 10 ran: which in-testing tickets are blocked, by what, and the blocker's own status — or state explicitly that no in-testing ticket has an unresolved blocker.
• If step 11 ran: assignees ranked by open high-priority ticket count, most first (all tied-for-top assignees called out together) — no "overloaded" verdict, just the ranked counts — plus an "unassigned" count if any qualifying ticket has no assignee.
• If step 12 ran: pending-verification count per QA assignee, plus an "unassigned" bucket if any Ready-for-QA ticket has no assignee.
• If step 13 ran: tickets older than N days (display ID, title, assignee, days since update), oldest first — or state explicitly that none exceed N days.

If all tickets are complete, say so explicitly.

References

• references/CAWPLAN_OPEN_API.md