tk-pr-sweep

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Multi-PR cleanup

多PR清理

Start only through an explicit
/tk-pr-sweep
,
$tk-pr-sweep
, or host skill selection. Do not invoke automatically for a generic request to clean up open PRs, respond to one PR review, or fix ordinary CI failures.
Sweep is a controller that reads and organizes the fresh state of multiple PRs. Do not duplicate long-lived task state in a Markdown ledger. The current GitHub and Git state is the source of truth.
Keep the conversation natural and the state handling strict.
Do not expose
actionable
,
held
, backend details, routing state, or worker receipts by default. Brief the user in plain language about what can proceed, what must wait, why, and how. Batch plan approval은 host별 native structured question surface를 우선 사용합니다 (Claude Code: AskUserQuestion; Codex: request_user_input; Hermes: clarify). unavailable하면 plain chat으로 fallback하고 child마다 승인을 반복하지 않습니다.
仅通过显式的
/tk-pr-sweep
$tk-pr-sweep
或宿主技能选择启动。 请勿在收到清理开放PR的通用请求、单个PR评审回复或修复普通CI失败的请求时自动调用。
Sweep是一个控制器,用于读取并整理多个PR的最新状态。 请勿在Markdown台账中重复存储长期任务状态。当前GitHub和Git状态为唯一可信源。
保持对话自然,状态处理严格。
默认情况下,请勿暴露
actionable
held
、后端细节、路由状态或工作回执。 用通俗易懂的语言向用户简报哪些事项可以推进、哪些必须等待、原因及方式。批量计划批准优先使用各宿主原生的结构化提问界面(Claude Code:AskUserQuestion;Codex:request_user_input;Hermes:clarify)。若不可用,则回退至普通聊天,且无需为每个子任务重复请求批准。

Target repositories

目标仓库

Use the following user-level configuration as the default repository scope:
text
$XDG_CONFIG_HOME/tigerkit/pr-triage.json
This configuration owns only the long-lived repository list. Do not store model mappings, selectors, effort levels, worker routing, fan-out preferences, or task state there.
If the configuration does not exist, bootstrap it only in execution mode when the current checkout’s origin can be identified safely.
--report
must use the helper's no-bootstrap path and keep the origin-derived repository list in memory; an explicit
--repo owner/name
limits the scope of that run.
使用以下用户级配置作为默认仓库范围:
text
$XDG_CONFIG_HOME/tigerkit/pr-triage.json
该配置仅负责存储长期仓库列表。 请勿在此存储模型映射、选择器、工作级别、工作路由、扇出偏好或任务状态。
若配置不存在,仅在执行模式下、且能安全识别当前检出仓库的origin时自动生成配置。
--report
必须使用助手的非自动生成路径,并将基于origin的仓库列表保留在内存中;显式的
--repo owner/name
参数可限制本次运行的范围。

Deterministic triage

确定性分类

Use
skills/tk-pr-sweep/scripts/triage.mjs
as the canonical fresh inventory. Report-only runs use
--no-bootstrap
.
At minimum, inspect:
  • open PRs
  • author and requested reviews
  • exact base/head and SHA
  • mergeability and conflicts
  • GitHub Actions versus external checks
  • review decision
  • unresolved review threads
  • latest actionable feedback and author response
  • current re-review request for every active
    CHANGES_REQUESTED
    reviewer
  • exactly one current-head summary marker after actionable threads close
Do not treat a cached user-supplied list or a previous
.tigerkit/pr-sweep.md
as current truth.
skills/tk-pr-sweep/scripts/triage.mjs
作为标准的全新清单工具。仅报告模式运行时使用
--no-bootstrap
参数。
至少检查以下内容:
  • 开放PR
  • 作者与被请求的评审人
  • 精确的base/head分支与SHA
  • 可合并性与冲突情况
  • GitHub Actions与外部检查
  • 评审决策
  • 未解决的评审线程
  • 最新的可操作反馈与作者回复
  • 针对每个处于
    CHANGES_REQUESTED
    状态的活跃评审人的当前重新评审请求
  • 可操作线程关闭后,必须有且仅有一个当前head的总结标记
请勿将缓存的用户提供列表或之前的
.tigerkit/pr-sweep.md
视为当前可信状态。

--report

--report
模式

--report
is strictly read-only.
When the user-level config is missing, read the current checkout's origin for this run only. Do not create the config directory/file; use an explicit
--repo owner/name
when no safe origin exists.
Example:
text
지금 처리할 PR은 3개예요.
#121 — 리뷰 대응 필요
#124 — GitHub Actions 수정 필요
#128 — rebase 필요

#130, #132는 사람 리뷰 대기이고 #135는 외부 CI 대기라 지금 손댈 필요 없습니다.
Keep the default output to a short briefing. Do not create lifecycle Markdown, a Seed, worktree, commit, push, reply, or resolution. If a repository cannot be read, separate that failure from successful repository results and explain which state could not be retrieved.
--report
模式为严格只读模式。
当用户级配置缺失时,仅在本次运行中读取当前检出仓库的origin。请勿创建配置目录/文件;若无法安全识别origin,使用显式的
--repo owner/name
参数。
示例:
text
当前可处理的PR有3个。
#121 — 需要响应评审
#124 — 需要修复GitHub Actions
#128 — 需要rebase

#130、#132正在等待人工评审,#135正在等待外部CI,目前无需处理。
默认输出保持简短简报。请勿创建生命周期Markdown、Seed、工作树、提交、推送、回复或解决方案。 若无法读取某个仓库,将该失败与成功仓库的结果分开,并说明无法获取哪些状态。

Execution plan

执行计划

In execution mode, plan only PRs that are currently actionable according to fresh triage.
Explain each PR at the level the user needs to understand:
  • why it is actionable now
  • what kind of work it requires
  • whether code changes are required
  • what verification is required
  • whether it is risky or requires a user decision
  • whether it is independent of the other work
The execution model may recommend only broad capability classes such as “중간급 coding model” or “충돌은 더 강한 reasoning model”. Do not create a specific provider selector, tier, reasoning effort, or
session.md
. Do not mark the entire Sweep as
Blocked
merely because these controls are unavailable.
Once the user approves the batch plan, that approval grants authority only for the exact PRs, heads, work types, and publication scope in the plan. Do not request the same approval again for each child.
在执行模式下,仅规划经全新分类判定为当前可操作的PR。
以用户需要理解的粒度解释每个PR:
  • 为何当前可操作
  • 需要何种类型的工作
  • 是否需要代码变更
  • 需要何种验证
  • 是否存在风险或需要用户决策
  • 是否与其他工作相互独立
执行模型仅可推荐宽泛的能力类别,例如“中级编码模型”或“冲突处理需更强推理模型”。 请勿创建特定的提供商选择器、层级、推理工作量或
session.md
。 请勿仅因这些控制项不可用就将整个Sweep标记为
Blocked
一旦用户批准批量计划,该批准仅授予对计划中明确指定的PR、head分支、工作类型及发布范围的操作权限。 请勿为每个子任务重复请求相同的批准。

Execution isolation

执行隔离

--report
and pre-approval fresh triage are read-only and do not create worktrees. After batch approval, every PR child requires a newly created dedicated worktree before handling begins. The parent
main
or
develop
checkout is never used for child work and never branch-switched with
git switch
or
git checkout
. A subagent counts as isolation only when it receives and uses that fresh worktree. Do not reuse another PR's or a previous child's worktree. If a fresh worktree cannot be created or passed to the child, hold only that PR as
Held
or
Blocked
; do not fall back to sequential handling in the parent
main
/
develop
checkout. The absence of worker or model controls is not itself a blocker; inability to establish the worktree boundary is a PR-local blocker.
--report
模式与批准前的全新分类均为只读模式,不会创建工作树。 批量批准后,每个PR子任务在开始处理前都需要创建新的专属工作树。父级的
main
develop
检出仓库永远不会用于子任务工作,也永远不会通过
git switch
git checkout
切换分支。 仅当子代理接收并使用该全新工作树时,才算达到隔离要求。请勿复用其他PR或之前子任务的工作树。 若无法创建或传递全新工作树给子任务,仅将该PR标记为
Held
Blocked
;请勿回退至在父级
main
/
develop
检出仓库中按顺序处理的方式。缺少工作器或模型控制项本身并非阻塞因素;无法建立工作树边界才是PR级别的阻塞因素。

Per-PR handling

单个PR处理

Immediately before handling each PR, reread fresh triage and the exact PR state. Before any mutating child route, verify the fresh dedicated worktree path for that PR and pass it to the child. If it is absent, hold or block before mutation.
Representative routes:
  • review feedback or repository-caused GitHub Actions failure → follow the
    tk-pr-respond
    procedure
  • merge conflict or base drift → follow the
    tk-pr-rebase
    procedure
  • external CI, queued/flaky/infrastructure failures, or pending human review → wait
  • unsupported state → report-only
If the parent-approved exact PR/head and resolution direction remain unchanged, the child must not ask for the same decision again. Return that PR to the user only when there is a material change, such as new feedback, head drift, or scope drift.
在处理每个PR之前,立即重新读取全新分类结果与该PR的精确状态。 在执行任何会修改状态的子路由之前,验证该PR的全新专属工作树路径并传递给子任务。若路径不存在,在执行修改操作前将其标记为暂停或阻塞。
典型路由:
  • 评审反馈或仓库导致的GitHub Actions失败 → 遵循
    tk-pr-respond
    流程
  • 合并冲突或base分支漂移 → 遵循
    tk-pr-rebase
    流程
  • 外部CI、排队/不稳定/基础设施失败或等待人工评审 → 等待
  • 不支持的状态 → 仅报告
若父级批准的精确PR/head分支与解决方向未发生变化,子任务不得再次请求相同的决策。 仅当出现实质性变化(如新反馈、head分支漂移或范围漂移)时,才将该PR反馈给用户。

Per-PR Seed

单个PR的Seed

Do not create one giant Seed for the entire Sweep.
Each PR child must use its own newly created dedicated worktree. Code-changing PRs use
.tigerkit/seed.md
there; reply-only or pure rebase work still uses the worktree but does not require a Seed solely for that reason. The Seed must be self-contained and include that PR’s feedback, objective, decisions, approach, AC, verification, and publication boundary.
Do not force a Seed onto reply-only work or a pure rebase that does not require separate implementation context.
Do not create
pr-sweep.md
,
pr-respond.md
, or worker receipt Markdown.
请勿为整个Sweep创建一个大型Seed。
每个PR子任务必须使用自己新创建的专属工作树。涉及代码变更的PR需在工作树中使用
.tigerkit/seed.md
;仅回复或纯rebase的工作仍需使用工作树,但无需为此单独创建Seed。 Seed必须是自包含的,需包含该PR的反馈、目标、决策、方法、验收标准(AC)、验证及发布边界。
请勿在仅回复或纯rebase的工作中强制创建Seed,除非这些工作需要单独的实现上下文。
请勿创建
pr-sweep.md
pr-respond.md
或工作回执Markdown。

Publication

发布

Before every child remote write, fresh-read and verify the exact repository, PR, head, identity, refspec, thread, and check. Permit only push, reply, resolve, and re-review actions within the parent-approved scope.
After all actionable review threads are closed, the publication contract additionally requires:
  • For every reviewer whose current review decision is
    CHANGES_REQUESTED
    , fresh verification that a re-review request was sent to that exact reviewer for the current head.
  • When a re-review is required or actionable feedback was answered with no outstanding request, exactly one current-head summary comment containing the marker
    <!-- tigerkit:pr-summary:<HEAD_SHA> -->
    , where
    <HEAD_SHA>
    is the exact current head SHA.
  • When that summary is required, fresh verification must prove it exists on the exact PR/current head and has no duplicate marker.
  • The summary comment, when required, must be published only after actionable threads are closed.
Do not report a PR as complete when evidence is missing for any required
CHANGES_REQUESTED
reviewer re-review request, actionable-thread closure, or required current-head summary comment.
If publication is partially blocked by permissions, preserve and report the already verified local commit and exact remote state. A retry in the same run is allowed only after re-verifying the exact target and refspec. A later-session
--recover-publication
is allowed only when the local commit, remote head, approved target, required re-review requests, actionable-thread state, and current-head summary-comment state can all be reconstructed from fresh evidence. Otherwise stop as
Unverifiable
. Never use plain force or a guessed refspec.
在每个子任务执行远程写入操作之前,重新读取并验证精确的仓库、PR、head分支、身份、refspec、线程及检查项。 仅允许在父级批准的范围内执行推送、回复、解决及重新评审操作。
在所有可操作评审线程关闭后,发布协议额外要求:
  • 对于每个当前评审决策为
    CHANGES_REQUESTED
    的评审人,需重新验证是否已向该精确评审人发送针对当前head分支的重新评审请求。
  • 当需要重新评审或已回复可操作反馈但未发出请求时,需发布一条包含标记
    <!-- tigerkit:pr-summary:<HEAD_SHA> -->
    的当前head分支总结评论,其中
    <HEAD_SHA>
    为当前head分支的精确SHA。
  • 当需要该总结评论时,需重新验证它是否存在于精确的PR/当前head分支上,且无重复标记。
  • 当需要该总结评论时,仅可在可操作线程关闭后发布。
若缺少任何针对
CHANGES_REQUESTED
评审人的重新评审请求、可操作线程关闭或所需当前head分支总结评论的证据,请勿将PR标记为已完成。
若因权限问题导致发布部分受阻,需保留并报告已验证的本地提交及精确远程状态。 仅在重新验证精确目标与refspec后,才可在本次运行中重试。 仅当能从全新证据中重构本地提交、远程head分支、批准目标、所需重新评审请求、可操作线程状态及当前head分支总结评论状态时,才可在后续会话中使用
--recover-publication
参数。 否则,标记为
Unverifiable
并停止操作。 切勿使用普通强制推送或猜测的refspec。

Queue progress

队列进度

A local failure in one PR does not automatically stop other independent PRs. Stop the entire Sweep only for a systemic failure, such as identity or permission contamination, ambiguous repository scope, or untrustworthy triage.
After each PR succeeds or fails, triage that PR again to confirm that its actual state changed. After every planned row finishes, run final fresh triage across all configured repositories.
A PR is not complete unless final fresh triage confirms the required checks, publication state, all required
CHANGES_REQUESTED
reviewer re-review requests, closed actionable threads, and any required current-head summary comment marked
<!-- tigerkit:pr-summary:<HEAD_SHA> -->
.
单个PR的本地失败不会自动停止其他独立PR的处理。 仅当出现系统性失败(如身份或权限污染、仓库范围模糊或分类不可信)时,才停止整个Sweep。
每个PR成功或失败后,需再次对其进行分类以确认其实际状态已变更。 所有计划任务完成后,需对所有配置的仓库执行最终的全新分类。 只有当最终全新分类确认所需检查项、发布状态、所有针对
CHANGES_REQUESTED
评审人的重新评审请求、已关闭的可操作线程及任何所需的包含
<!-- tigerkit:pr-summary:<HEAD_SHA> -->
标记的当前head分支总结评论均已满足时,PR才算完成。

Completion response

完成响应

Do not dump internal categories or receipts.
Example:
text
이번 Sweep에서는 4개 중 3개를 처리했습니다.
#121과 #124는 수정·검증·push 완료, #130은 답변 완료입니다.
#128은 새 conflict가 확인돼 보류했고, 나머지는 사람/외부 CI 대기 상태입니다.
Keep successfully handled items brief and explain only problematic PRs in the necessary detail. Never describe an item as complete when required publication evidence is missing. Use exactly one final status based on the actual result:
Status: Pass | Pending | Blocked | Unverifiable | Fail
.
请勿输出内部类别或回执。
示例:
text
本次Sweep处理了4个PR中的3个。
#121与#124已完成修改、验证及推送,#130已完成回复。
#128因发现新冲突被暂停,其余PR处于等待人工/外部CI的状态。
成功处理的事项保持简短说明,仅对有问题的PR进行必要的详细解释。 当缺少所需发布证据时,切勿将事项描述为已完成。 根据实际结果使用唯一的最终状态:
Status: Pass | Pending | Blocked | Unverifiable | Fail