From b614f70361914e85fd2a00dceb7fa2ffcafabe0c Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Mon, 10 Aug 2026 12:50:47 -0700 Subject: [PATCH] feat(kanban): teach workers to flag collision hotspots instead of piling on MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the comment-based hotspot convention (no new primitives) across three guidance surfaces: - KANBAN_GUIDANCE worker lifecycle: new step 7 — when a file keeps colliding with siblings or appears in other cards' recent comments, leave a 'hotspot: — ' kanban_comment and repeat it in completion metadata so the orchestrator can decompose the file first. - kanban.md (en + zh-Hans): 'Collision hotspots in parallel campaigns' subsection — the convention, the orchestrator response (2+ flags on one path => dedicated decomposition card before queuing more work touching it), and the cross-link to merge-reconciler for conflicts that already happened. - merge-reconciler SKILL.md Pitfalls: repeated conflicts on the same file across rounds are a hotspot signal — flag for decomposition rather than serially reconciling. Live-verified: guidance renders once via real import (6152 chars); hotspot comment round-trips through add_comment -> list_comments -> worker context on an isolated HERMES_KANBAN_DB; kanban tools, review-surfaces, and merge-reconciler skill tests green (45 passed). --- agent/prompt_builder.py | 6 +++++ .../merge-reconciler/SKILL.md | 4 ++++ website/docs/user-guide/features/kanban.md | 23 +++++++++++++++++++ .../current/user-guide/features/kanban.md | 10 ++++++++ 4 files changed, 43 insertions(+) diff --git a/agent/prompt_builder.py b/agent/prompt_builder.py index 666c620f721a9..f234c98c02da9 100644 --- a/agent/prompt_builder.py +++ b/agent/prompt_builder.py @@ -258,6 +258,12 @@ KANBAN_GUIDANCE = ( "`kanban_create(title=..., assignee=, parents=[your-task-id])` " "to spawn a child task for the appropriate specialist profile instead of " "scope-creeping into the next thing.\n" + "7. **Flag collision hotspots; don't pile on.** If your change keeps " + "colliding with sibling branches in one file, or a file your diff touches " + "shows up in other cards' recent comments, do not silently add more to it: " + "leave a `kanban_comment` starting with `hotspot: — ` " + "on your card and repeat the flag in your completion metadata, so the " + "orchestrator can decompose that file before more work lands on it.\n" "\n" "## Orchestrator mode\n" "\n" diff --git a/skills/autonomous-ai-agents/merge-reconciler/SKILL.md b/skills/autonomous-ai-agents/merge-reconciler/SKILL.md index f81cb4c1680a2..9e5a3270e336a 100644 --- a/skills/autonomous-ai-agents/merge-reconciler/SKILL.md +++ b/skills/autonomous-ai-agents/merge-reconciler/SKILL.md @@ -144,6 +144,10 @@ explicitly in the hand-back summary. - **Missing intents**: commit messages alone can be thin; prefer kanban completion summaries or PR bodies. If neither side's intent is recoverable, escalate instead of guessing. +- **Repeat offenders**: repeated conflicts on the SAME file across rounds are + a hotspot signal, not routine reconciliation work — flag it (e.g. a + `hotspot: — ` kanban comment) so the orchestrator decomposes + that file, rather than serially reconciling every new collision on it. ## Verification diff --git a/website/docs/user-guide/features/kanban.md b/website/docs/user-guide/features/kanban.md index 1cc7194b43e85..7ee2942d2b2f5 100644 --- a/website/docs/user-guide/features/kanban.md +++ b/website/docs/user-guide/features/kanban.md @@ -958,6 +958,29 @@ it receives both diffs *and* both intents. The bundled gives that worker the full procedure: classify each conflicted hunk, resolve impartially, verify, and hand back a summary naming every decision. +### Collision hotspots in parallel campaigns + +In wide campaigns some files become collision magnets: many workers each add a +little to the same file, nobody owns keeping it small, and it turns into the +site of constant merge conflicts. The mitigation is a comment convention, not a +new primitive. A worker that notices its diff keeps colliding with siblings in +one file — or that a file it touches keeps appearing in other cards' recent +comments — should not silently pile on. Instead it leaves a comment on its own +card with a recognizable prefix: + +``` +hotspot: hermes_cli/kanban_db.py — third conflicting edit to the dispatch loop this wave +``` + +and repeats the flag in its completion `metadata`. Orchestrators (or humans +reviewing the board) who see **two or more `hotspot:` comments naming the same +path** should create a dedicated refactor/decomposition card for that file +**before** queuing more work that touches it — splitting the magnet file is +cheaper than reconciling every future collision it would cause. For conflicts +that have *already* happened, use the reconciliation-card pattern above with +the `merge-reconciler` skill; hotspot flagging is the upstream fix that keeps +the reconciler from becoming a standing lane. + ## Multi-tenant usage When one specialist fleet serves multiple businesses, tag each task with a tenant: diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban.md index e7f417ec5c23a..b570fd98db757 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/kanban.md @@ -703,6 +703,16 @@ EOF 在工程流水线（使用 worktree 的 P1/P2）中，两个 worker 的分支合并时可能发生冲突。不要让任一 worker 自行裁决 —— 发生冲突的 agent 缺乏对方的上下文，往往会覆盖对方的改动或放弃自己的改动。正确做法是：创建一张调解卡片，指派给**第三个中立配置文件**，并把**两张**冲突卡片都链接为其父任务：父任务链接会把双方的完成摘要带入调解者的上下文，使其同时获得双方的 diff *和*双方的意图。内置的 [`merge-reconciler` 技能](https://github.com/NousResearch/hermes-agent/blob/main/skills/autonomous-ai-agents/merge-reconciler/SKILL.md) 为该 worker 提供完整流程：对每个冲突块分类、公正地解决、验证，并在交回摘要中说明每一项决定。 +### 并行战役中的碰撞热点（Collision hotspots） + +在大规模并行战役中，某些文件会成为碰撞磁石：许多 worker 各自往同一个文件里添加一点内容，没有人负责保持它精简，它于是成为持续合并冲突的发生地。缓解方式是一种注释约定，而非新原语。当 worker 发现自己的 diff 在某个文件上不断与兄弟分支冲突，或它触碰的某个文件反复出现在其他卡片最近的评论中时，不应默默继续叠加改动，而应在自己的卡片上留下带有可识别前缀的评论： + +``` +hotspot: hermes_cli/kanban_db.py — 本轮对 dispatch 循环的第三次冲突性编辑 +``` + +并在完成时的 `metadata` 中重复该标记。编排者（或查看看板的人类）如果看到**两条或更多 `hotspot:` 评论指向同一路径**，应在继续排入任何触碰该文件的工作**之前**，为该文件创建一张专门的重构/分解卡片 —— 拆分磁石文件比调解它未来引发的每一次冲突更便宜。对于*已经*发生的冲突，请使用上文的调解卡片模式配合 `merge-reconciler` 技能；hotspot 标记是上游修复，能避免调解者变成一条常设车道。 + ## 多租户使用 当一个专家团队为多个业务提供服务时，为每个任务添加租户标签：