What this proposes
Adopt the local /patch skill into TeamBrain and propagate it to every TeamAgent user, plus stand up a public GitHub Pages page so any coding agent (not just teamagent-initialized ones) can copy-paste the skill in.
The /patch skill formalizes a workflow this triage session just exercised end-to-end: a contributor fixes an upstream bug locally, then surfaces it to the maintainer as a candidate-patch comment (not a PR, not a force-merge) with reproduction steps + local verification + an explicit adopt-with-caution footer.
Track record — bugs surfaced this session
The /patch philosophy (local fix → structured candidate comment, maintainer decides) already produced real, reproducible results in a single Mac-overheating triage:
| Issue |
What it caught |
Evidence quality |
| #459 |
Upstream claude.exe --bg-spare worker leak — loadavg 88 on 8-core M1 |
Full PID tree, pmset -g therm proof it's scheduler-overload not thermal, repro in 4 shell commands |
| #460 |
TeamBrain-side bug: bin-session-end.ts:133 spawns N concurrent unbounded full-rescan pipelines — loadavg 162, 8 fires in 223 ms |
Code-level root cause w/ file:line, evidence dump, 5-item fix scope |
| #461 |
Local hot-fix patches: bin-session-end-gated.cjs wrapper gating SessionEnd storms, aligned to upstream pipelineLockPath (sha1 / ~/.teamagent/locks/ / {pid,started_at}) |
Verbatim diff, byte-identical lockfile verification, install/rollback recipe |
#461 is the canonical example of what /patch produces: a candidate patch with diff + repro + verification + adopt-with-caution, posted as a comment for the maintainer to decide on. That's the skill's entire reason to exist.
The skill (just updated via skill-creator)
/patch was updated this session with three requirements:
- Interactive explain-and-verify loop — before each step the skill explains what / why / what-you-get in Chinese, then asks the user to confirm understanding; loops with a fresh re-explanation (not a re-read) until the user says it's clear. No silent fast-path to "comment posted".
- Chinese-only user communication — every word the skill says to the user is 中文. Only the machine payload (git diff, the English comment template aimed at upstream maintainers, commands) stays English.
how-i-fix-this companion issue prompt — after the candidate patch comment lands, the skill prompts the user to open a companion issue titled how-i-fix-this capturing the fix narrative (symptom → localization path including dead ends → root cause → why this fix → verification). The diff is "what changed"; this issue is "how I got there".
Preserved unchanged: comment-not-PR, mandatory how-to-reproduce, LGTM + adopt-with-caution footer, no force-merge, no label spam.
Ask 1 — ship it to all TeamAgent users
Per docs/INIT-PROPAGATION.md, teamagent init already propagates .claude/skills/<name>/ mirrors to ~/.claude/skills/. Proposal:
- Vendor the skill at
.claude/skills/patch/SKILL.md (and .codex/skills/patch/SKILL.md per AGENTS.md §5/§Project Skills) so it ships with the repo and lands in every worktree.
teamagent init then mirrors it to ~/.claude/skills/patch/ for each user — zero manual install.- This needs a grill + FIXEDFLOW cycle before driver dispatch (it's a new skill = decision product, not a chore — does not qualify for
fast-path per docs/FAST-PATH-PR.md §self-dogfood clause).
Ask 2 — host a copy-paste GitHub Pages for external agents
Not every agent that wants this workflow is teamagent-initialized (Codex, Cursor, OpenClaw, plain Claude Code on a non-TeamBrain repo). Proposal:
- Publish the
/patch SKILL.md as a single self-contained page on TeamBrain's GitHub Pages site (e.g. https://libz-renlab-ai.github.io/TeamBrain/skills/patch.html), rendered so an agent can be pointed at the URL and read it directly.
- The page is copy-paste source of truth: a user tells their agent "read
<url> and follow it as a skill" and the agent gets the full workflow with zero install.
- Keep it generated from the canonical
.claude/skills/patch/SKILL.md (one source, the Pages build renders it) so it never drifts.
- This rides the existing
landing-deploy.yml GitHub Pages pipeline (apps/landing/), or a small dedicated skills/ route.
Why this matters
The /patch workflow is maintainer-respecting contribution at low friction — it lets a contributor surface evidence without forcing the maintainer into a PR review tool, and without the contributor needing commit rights. This session proved it produces genuinely actionable bug reports (#459/#460/#461). Making it (a) automatic for every TeamAgent user and (b) copy-paste-able for any external agent turns a one-off workflow into infrastructure.
Proposed scope (needs grill before driver dispatch)
Full updated SKILL.md (for review)
.claude/skills/patch/SKILL.md (387 lines)
---
name: patch
description: Package a fix the user just made on their machine into a "candidate patch" comment on a GitHub issue, with a how-to-reproduce section and an explicit LGTM-from-contributor tag — so the maintainer can review and decide whether to adopt, with caution. NOT a PR, NOT auto-merge, NOT a force push — just a polite, well-structured "I patched this locally, here's the diff, here's how I reproduced the bug, take it or leave it" comment. This skill communicates with the user ONLY in Chinese (中文), walks the user through each step interactively, and verifies the user understands what is happening before proceeding. After posting the candidate patch it also prompts the user to open a companion "how-i-fix-this" issue documenting the fix narrative. Use this skill whenever the user says "/patch", "submit my patch to an issue", "send this fix to the maintainer", "patch to issue N", "我修好了 X，能不能发给上游", "我这边修通了，发到 issue 上", "candidate patch", "LGTM patch", "fix-and-submit", "I have a fix for issue N", "post my local fix as a patch comment", or describes a local repair they want the upstream team to evaluate without opening a PR. Trigger keywords: /patch, candidate patch, patch to issue, LGTM patch, 候选补丁, 投稿补丁, 给 maintainer 看看, fix-and-submit. Maintainer-respecting by design — every comment ends with an explicit "adopt with caution, you have not run this through your CI" footer so reviewers know this is an outsider's local fix, not a vetted change.
---
┌─────────────────────────────────────────┐
local fix ───▶│ /patch (全程中文 · 每步确认用户已懂) │
(git diff) │ │
│ 0. 用中文解释这个 skill 要做什么 │
│ → 循环解释直到用户说「懂了」 │
│ 1. capture diff (HEAD or staged) │
│ 2. ask: which issue? which repo? │
│ 3. build comment: │
how-to │ • Summary │
reproduce ───▶│ • How to reproduce (bug) │
│ • The patch (unified diff) │
│ • Local verification I ran │
│ • LGTM from contributor │
│ • ⚠️ Adopt-with-caution footer │
│ 4. 给用户看 comment 草稿，中文讲解， │
│ 确认理解后才 gh issue comment │
│ 5. show URL │
│ 6. 提示用户开一个 "how-i-fix-this" │
│ companion issue 记录修复过程 │
└────────────────────┬────────────────────┘
│
maintainer reads · 👀 ────────────┐
maintainer decides · 🤔 │
cherry-picks / rejects / asks ──▶│
(the skill does NOT force adopt) │
▼
issue thread updated
(no PR, no merge)
## 沟通语言：全程中文 / Chinese-only communication
**这个 skill 对用户说的每一句话都必须是中文。** 不是「默认中文」，是「只用中文」——
解释、提问、确认、报错、给草稿讲解、最后的总结，全部中文。
唯一保留英文的地方是**机器内容本身**：`git diff` 的输出、unified diff、命令、JSON、
GitHub 的 comment body（comment body 按下面的模板，模板是英文的，因为它是给上游
maintainer 看的——但你跟用户讲解这个 comment 时，依然用中文讲）。
为什么：这个 skill 的用户是中文协作者，他们要把本地修复投稿给上游。投稿动作本身
（comment 落到 GitHub）面向的是可能不懂中文的 maintainer，所以 comment 是英文；
但「带着用户一步步走完这个投稿流程」面向的是用户本人，必须中文，否则用户看不懂
自己正在提交什么。
## 交互原则：每一步都讲清楚，确认用户懂了再往下 / Explain-and-verify loop
这个 skill **不是**「闷头跑完然后甩个 URL」。它是**陪用户走一遍**。
每进入一个关键步骤前，先用中文讲：
1. **现在要做什么** — 这一步具体的动作。
2. **为什么要做** — 这一步存在的理由。
3. **做完会得到什么** — 这一步的产物 / 副作用。
讲完，**问用户一句**：「这一步你清楚了吗？有没有要我再解释的地方？」
- 用户说「懂了 / 清楚了 / 继续」之类 → 往下走。
- 用户说「没懂 / 再讲一下 / 这个是什么意思」→ **换一种说法重新解释**，不要原样
复读。可以打比方、可以举例、可以拆得更碎。然后**再问一次**。
- 一直循环到用户明确表示理解为止。**绝不在用户没确认理解的情况下往下走**，尤其
是第 4 步（真的把 comment 发到 GitHub）之前。
为什么这样设计：投稿补丁是一个「外人往别人仓库里塞东西」的动作，用户必须完全明白
自己在提交什么、提交到哪、maintainer 会看到什么。如果用户稀里糊涂地按了「发」，
出了岔子（发错 issue、diff 里夹了不该有的东西）他自己都不知道。explain-and-verify
loop 就是确保「用户知情」这件事不是走过场。
这个原则**贯穿整个流程**，不是只在开头讲一次。第 0 步讲整体，第 1/2/3/4/6 步各自
再讲那一步。
## What it does (and what it deliberately doesn't)
`/patch` is for the workflow:
> 我在自己机器上把上游一个 bug 修通了。我没有权限直接 commit、也不想开 PR，
> 但我希望 maintainer 看到我的 diff、看到我的复现步骤、看到我本地的验证结果，
> 自己决定要不要采纳。
It produces **one well-structured comment** on a GitHub issue:
- Summary (1–2 sentences, what changed and why)
- **How to reproduce** the original bug (concrete steps, copy-pasteable)
- The patch as a unified diff inside a fenced block
- The verification the contributor did locally (commands run, outputs observed)
- An explicit "LGTM from contributor" stamp
- A footer that **tells the maintainer not to trust this blindly** — it hasn't run
through their CI, hasn't been reviewed by anyone on their side, may not match their
style or constraints. **They decide. They cherry-pick by hand if at all.**
然后，**发完 comment 之后**，它还会提示用户开一个配套的 `how-i-fix-this` issue
（见下面第 6 步），把「我是怎么定位、怎么修、怎么验证的」这个叙事沉淀下来，方便
以后的人复用。
It does **not**:
- open a pull request
- push to any branch (local or remote)
- force-merge anything
- pretend the patch is reviewed
- claim it works on the maintainer's CI matrix
## When to invoke
Use whenever the user has just finished a local fix and wants to surface it to upstream
without forcing a PR. Typical phrasings:
- "/patch"
- "把我刚才的修复发到 issue 123"
- "send this diff to libz-renlab-ai/TeamBrain#42"
- "I patched it locally, drop a candidate comment on the issue"
- "post my fix to issue N with LGTM"
- "我这边跑通了，发给 maintainer 看看，让他自己决定"
If the user says "open a PR" — that's `/ship` or `gh pr create`, not this skill.
If the user says "merge this" — refuse and point at `/ship` / `/land-and-deploy`.
## Required inputs
Before posting, you must know:
1. **Target issue** — repo + issue number (e.g. `owner/repo#123`), or a full URL.
If the user only gave you a number, ask once for the repo (or infer from `cwd` if
inside a clone — `gh repo view --json nameWithOwner -q .nameWithOwner`).
2. **The diff** — by default, `git diff HEAD` from the cwd. If the user has already
staged the fix, prefer `git diff --cached`. If the fix is already committed but not
pushed, use `git format-patch -1 HEAD --stdout` (full patch, with commit message).
Confirm the diff range with the user if there's any ambiguity (e.g. multiple commits
ahead of origin).
3. **How-to-reproduce** — the user must describe the original bug well enough that the
maintainer can repro it from scratch. If the user just says "it was broken", stop
and ask (用中文问) for: trigger (what command / what input), expected behavior,
observed behavior, environment (OS, version, branch). Don't fabricate repro steps.
4. **Local verification** — what did the user run after the fix to convince themselves
it's good? `pytest tests/foo`, manual smoke test, `claudefast -p "..."` probe,
whatever. One line is fine. **Never** invent a verification the user didn't mention.
每一项缺失或含糊时，**用中文问一个问题**，不要瞎编。
## The comment template
Use this exact skeleton. Substitute placeholders. Keep section order — maintainers
scan top-to-bottom. (模板是英文的——它是发给上游 maintainer 看的。你给用户讲解这个
草稿时仍然用中文。)
````markdown
## 🩹 Candidate patch (LGTM from contributor)
Hi maintainer — I hit this issue on my machine and have a local fix. Posting it here
**as a comment, not a PR**, so you can review the diff + my reproduction steps and
decide whether to adopt it (or cherry-pick parts of it, or reject it entirely).
### Summary
<one or two sentences: what the fix changes, what bug it addresses>
### How to reproduce the bug (without my patch)
1. <step>
2. <step>
3. Expected: <…>
Observed: <…>
Environment: <OS / runtime version / branch / commit>
### The patch
```diff
<unified diff, exactly as `git diff HEAD` / `git diff --cached` / `git format-patch -1 --stdout` produced it>
Local verification I ran
<command> → <short outcome, e.g. "12 passed, 0 failed">-
LGTM from contributor
I'm tagging this with LGTM to signal that on my machine, against my
reproduction, this fix works and doesn't regress what I tested.
⚠️ Adopt with caution
This patch has not been:
- run through your CI
- reviewed by anyone on your team
- checked against your style guide / lint config
- tested against your full matrix of supported versions / platforms
It may break invariants I don't know about. You decide whether to adopt it. If
you want to take it, please cherry-pick into your own branch and run your CI — don't
trust it just because I said LGTM.
Happy to follow up with more detail, more tests, or rework it into a proper PR if
you'd prefer that.
— posted via /patch (local-fix → candidate-comment workflow)
## Step-by-step procedure
### 第 0 步 — 用中文讲清楚这个 skill 整体要干嘛
在做任何事情之前，先用中文跟用户说明白：
- `/patch` 会把他本地的修复，**打包成一条 GitHub issue 评论**（不是 PR、不会合并、
不会 push）。
- 评论里会有：改了什么、原 bug 怎么复现、diff 本身、他本地怎么验证的、一个 LGTM
标记、一个「请谨慎采纳」的脚注。
- maintainer 看到后自己决定要不要采纳——这个 skill 不替 maintainer 做决定。
- 走完之后还会提示他开一个 `how-i-fix-this` issue 记录修复过程。
讲完问一句：「这个流程你清楚了吗？要不要我再展开讲讲某一部分？」
循环到用户确认理解，再进第 1 步。
### 第 1 步 — 收集输入（见上面 "Required inputs"）
进入前先用中文讲：现在要收集四样东西（目标 issue、diff、复现步骤、本地验证），
为什么每样都需要。缺啥问啥，**一次问一个**，全程中文。问完确认用户明白了为什么
要这些，再往下。
### 第 2 步 — 锁定目标 issue
用中文讲：现在要确认补丁发到哪个仓库的哪个 issue。接受以下任意形式：
- `owner/repo#123`
- full URL `https://github.com/owner/repo/issues/123`
- bare `#123` when inside a clone (infer repo with
`gh repo view --json nameWithOwner -q .nameWithOwner`)
确认仓库 + issue 号之后，用中文复述一遍给用户听：「我们要发到 `<owner/repo>` 的
#`<N>`，对吗？」等用户确认。
### 第 3 步 — 抓取 diff
用中文讲：现在要把他的本地改动抓成一个 diff。三种情况：
```bash
# default — uncommitted changes against HEAD
git diff HEAD > /tmp/patch-comment-diff.patch
# or — staged only
git diff --cached > /tmp/patch-comment-diff.patch
# or — one already-committed local commit
git format-patch -1 HEAD --stdout > /tmp/patch-comment-diff.patch
```
抓完用中文告诉用户：抓到了多少行改动、动了哪几个文件。
Sanity-check it's non-empty and < ~50 KB. If it's bigger, 用中文问用户要不要
(a) split into multiple comments, (b) attach as a gist + link, or
(c) only inline the most relevant hunks. **Do not silently truncate.**
确认用户认可这个 diff 范围（没有夹带不该有的文件），再往下。
### 第 4 步 — 拼 comment 草稿，中文讲解，确认后才发
把模板填进临时文件 `/tmp/patch-comment-<issue>.md`。
**把草稿原文展示给用户**，然后**用中文逐段讲解**这条 comment：
- Summary 段说了什么
- How to reproduce 段为什么重要（没有复现步骤的补丁只是「一个意见」）
- diff 段就是他的改动
- verification 段是他本地做了什么
- LGTM + adopt-with-caution 脚注合在一起，诚实地表达「他知道什么、不知道什么」
讲完问：「这条评论的内容你都看明白了吗？确认要发到 `<owner/repo>#<N>` 吗？」
**只有用户明确说「发 / 确认 / 可以」之后**，才执行：
```bash
gh issue comment <issue-number> --repo <owner/repo> --body-file /tmp/patch-comment-<issue>.md
```
`gh` 成功后会打印 comment URL。**用中文**把 URL 回报给用户：「评论已经发出去了，
链接在这里：<URL>」。
### 第 5 步 — 不要越界
发完 comment 之后，**不要**：
- add labels (you're not the maintainer; suggest in prose if relevant)
- close the issue
- open a PR
- push anything to a remote
- tag people unless the user explicitly named them
### 第 6 步 — 提示用户开一个 "how-i-fix-this" companion issue
candidate patch 评论发完后，**用中文**主动跟用户说：
> 「补丁评论已经发出去了。建议你再开一个配套的 issue，标题就叫 `how-i-fix-this`，
> 把你**是怎么定位到这个 bug、怎么想到这个修法、怎么验证的**这个过程记下来。
> 评论里的 diff 是『改了什么』，这个 issue 是『为什么这么改、怎么走到这一步的』。
> 以后别人遇到类似问题，看这个叙事能少走很多弯路。要我帮你起草这个 issue 吗？」
为什么要这个配套 issue：candidate patch 评论给的是**结果**（diff + 复现 + 验证）；
`how-i-fix-this` issue 给的是**过程叙事**（调查思路、走过的弯路、为什么选这个修法
而不是别的）。两者互补——前者让 maintainer 能采纳，后者让后来人能学习。
如果用户同意，帮他起草 `how-i-fix-this` issue 的 body（中文 body 即可，因为这是
叙事、给协作者看的；标题用英文 `how-i-fix-this` 或 `how-i-fix-this: <bug 一句话>`）。
body 建议包含：
- **症状** — 一开始观察到什么不对劲
- **定位过程** — 怎么一步步缩小范围找到根因（走过的弯路也写上，这是最有价值的部分）
- **根因** — 实际错在哪
- **修法** — 为什么选这个改动，有没有考虑过别的方案
- **验证** — 怎么确认修好了
- **关联** — 对应的 candidate patch 评论 URL、相关 issue / PR
起草完同样**用中文讲解一遍**，确认用户认可，再问要不要 `gh issue create` 发出去。
发不发由用户决定——这一步是建议，不是强制。
## Edge cases
(以下情况发生时，**都用中文**跟用户解释 + 提问。)
- **No diff yet** — the user said `/patch` but `git diff HEAD` is empty.
用中文告诉他：现在抓不到改动。问他：是忘了存盘、还是已经 commit + push 了、
还是在错的分支上？Don't post a comment with an empty diff.
- **Private repo / no `gh` auth** — `gh issue comment` will error. Catch it,
把渲染好的 comment body 用中文展示给用户，告诉他要么 `gh auth login`，
要么手动把这段贴到 issue 网页里。
- **Existing candidate-patch comment on the same issue** — quickly skim the
thread (`gh issue view <n> --repo <r> --comments`). If you find a prior
`Candidate patch (LGTM from contributor)` comment from this user, 用中文问他：
要 (a) 发一条新的、在开头注明「supersedes my earlier candidate patch above」，
还是 (b) 用 `gh issue comment --edit-last` 替换上一条。Default: 发新的。
- **Repo is a fork** — make sure the user is targeting the **upstream** issue,
not their fork's. `gh repo view` shows the upstream via `parent.nameWithOwner`.
用中文跟用户确认目标是上游仓库。
- **Binary / generated files in the diff** — strip them or 用中文问用户。一个
200 行的 yarn.lock churn 会把真正的修复淹掉。
- **User asks to open a PR instead** — 用中文礼貌地引导到 `/ship` (gstack) 或
`gh pr create`。This skill is intentionally PR-less.
## Verification recipe (for the skill author, not for end users)
To smoke-test that this skill triggers and produces the expected shape:
```bash
# trigger check
claudefast -p "I patched issue 42 in foo/bar locally, send it as a candidate patch"
# expect: invokes /patch, 全程用中文跟用户交互, asks for diff + how-to-reproduce,
# 每步确认用户理解, builds the comment template, 发完提示开 how-i-fix-this issue
# dry-run
echo "diff --git a/x b/x" > /tmp/fake.patch
# walk through the skill in chat — should refuse to post empty/fake diffs without confirmation
```
验证三条新增行为时重点看：
1. **中文** — skill 对用户说的每一句话都是中文（comment body 本身仍是英文模板）。
2. **explain-and-verify loop** — 每个关键步骤前有「讲什么 / 为什么 / 得到什么」+
一句确认问句；用户说没懂时换说法重讲，不原样复读。
3. **how-i-fix-this** — 发完 candidate patch 评论后，确实主动提示开配套 issue。
## Design rationale (why it looks like this)
- **Comment, not PR.** A PR forces the maintainer into a review tool with branches,
CI runs, merge buttons. A comment is lower-stakes — they can ignore it, cherry-pick
it, or invite the contributor to PR. Lower friction for both sides.
- **How-to-reproduce is mandatory.** A patch without a repro is just an opinion. The
repro is what lets the maintainer verify the bug exists on their end before even
looking at the diff.
- **LGTM stamp + adopt-with-caution footer.** These two together signal exactly what
the contributor knows ("works on my machine, against my repro") and what they
don't ("your CI, your matrix, your invariants"). Honest scope.
- **No PR-opening, no merging, no label spam.** The skill respects that the
maintainer owns their repo. The contributor's job stops at "here's evidence,
you decide."
- **全程中文沟通.** 这个 skill 的用户是中文协作者。投稿这个动作风险不低（往别人
仓库塞东西），用户必须百分百看懂自己在提交什么。英文走查会让一部分用户「看个
大概就按了」——中文消除这个理解断层。
- **explain-and-verify loop.** 不验证用户是否理解，就等于默认用户都懂——而投稿
补丁恰恰是那种「不懂也能按下去、但按错了代价很大」的操作。每步确认是把「知情」
做实，不是做样子。
- **how-i-fix-this companion issue.** candidate patch 评论是「结果」，会被 maintainer
采纳或拒绝后就沉到 issue 历史里。修复的**思路过程**——尤其是走过的弯路——是更耐
用的知识，值得单独沉淀成一个 issue，让后来人能搜到、能复用。
```
</details>
## Related
- [#459](https://github.com/libz-renlab-ai/TeamBrain/issues/459), [#460](https://github.com/libz-renlab-ai/TeamBrain/issues/460), [#461](https://github.com/libz-renlab-ai/TeamBrain/issues/461) — the bugs that demonstrate the workflow
- `docs/INIT-PROPAGATION.md` — how project-level skills reach users
- `docs/FAST-PATH-PR.md` — why this needs full grill (new skill = decision product, self-dogfood clause)
- `AGENTS.md` §5, §Project Skills — `.claude/skills/` + `.codex/skills/` vendoring convention
---
Filed via /investigate (continuation) on 2026-05-14.
What this proposes
Adopt the local
/patchskill into TeamBrain and propagate it to every TeamAgent user, plus stand up a public GitHub Pages page so any coding agent (not just teamagent-initialized ones) can copy-paste the skill in.The
/patchskill formalizes a workflow this triage session just exercised end-to-end: a contributor fixes an upstream bug locally, then surfaces it to the maintainer as a candidate-patch comment (not a PR, not a force-merge) with reproduction steps + local verification + an explicit adopt-with-caution footer.Track record — bugs surfaced this session
The
/patchphilosophy (local fix → structured candidate comment, maintainer decides) already produced real, reproducible results in a single Mac-overheating triage:claude.exe --bg-spareworker leak — loadavg 88 on 8-core M1pmset -g thermproof it's scheduler-overload not thermal, repro in 4 shell commandsbin-session-end.ts:133spawns N concurrent unbounded full-rescan pipelines — loadavg 162, 8 fires in 223 msbin-session-end-gated.cjswrapper gating SessionEnd storms, aligned to upstreampipelineLockPath(sha1 /~/.teamagent/locks//{pid,started_at})#461is the canonical example of what/patchproduces: a candidate patch with diff + repro + verification + adopt-with-caution, posted as a comment for the maintainer to decide on. That's the skill's entire reason to exist.The skill (just updated via skill-creator)
/patchwas updated this session with three requirements:how-i-fix-thiscompanion issue prompt — after the candidate patch comment lands, the skill prompts the user to open a companion issue titledhow-i-fix-thiscapturing the fix narrative (symptom → localization path including dead ends → root cause → why this fix → verification). The diff is "what changed"; this issue is "how I got there".Preserved unchanged: comment-not-PR, mandatory how-to-reproduce, LGTM + adopt-with-caution footer, no force-merge, no label spam.
Ask 1 — ship it to all TeamAgent users
Per
docs/INIT-PROPAGATION.md,teamagent initalready propagates.claude/skills/<name>/mirrors to~/.claude/skills/. Proposal:.claude/skills/patch/SKILL.md(and.codex/skills/patch/SKILL.mdperAGENTS.md§5/§Project Skills) so it ships with the repo and lands in every worktree.teamagent initthen mirrors it to~/.claude/skills/patch/for each user — zero manual install.fast-pathperdocs/FAST-PATH-PR.md§self-dogfood clause).Ask 2 — host a copy-paste GitHub Pages for external agents
Not every agent that wants this workflow is teamagent-initialized (Codex, Cursor, OpenClaw, plain Claude Code on a non-TeamBrain repo). Proposal:
/patchSKILL.md as a single self-contained page on TeamBrain's GitHub Pages site (e.g.https://libz-renlab-ai.github.io/TeamBrain/skills/patch.html), rendered so an agent can be pointed at the URL and read it directly.<url>and follow it as a skill" and the agent gets the full workflow with zero install..claude/skills/patch/SKILL.md(one source, the Pages build renders it) so it never drifts.landing-deploy.ymlGitHub Pages pipeline (apps/landing/), or a small dedicatedskills/route.Why this matters
The
/patchworkflow is maintainer-respecting contribution at low friction — it lets a contributor surface evidence without forcing the maintainer into a PR review tool, and without the contributor needing commit rights. This session proved it produces genuinely actionable bug reports (#459/#460/#461). Making it (a) automatic for every TeamAgent user and (b) copy-paste-able for any external agent turns a one-off workflow into infrastructure.Proposed scope (needs grill before driver dispatch)
.claude/skills/patch/SKILL.md+.codex/skills/patch/SKILL.mdinto the repoteamagent initpropagation picks up the new skill dir (extenddocs/INIT-PROPAGATION.mdif the static-mirror path needs wiring)skills/patch.htmlroute to the GitHub Pages build, generated from the canonical SKILL.mdteamagent doctorcheck: verify~/.claude/skills/patch/exists post-init/patchfor now?Full updated SKILL.md (for review)
.claude/skills/patch/SKILL.md (387 lines)
local fix ───▶│ /patch (全程中文 · 每步确认用户已懂) │⚠️ Adopt-with-caution footer │
(git diff) │ │
│ 0. 用中文解释这个 skill 要做什么 │
│ → 循环解释直到用户说「懂了」 │
│ 1. capture diff (HEAD or staged) │
│ 2. ask: which issue? which repo? │
│ 3. build comment: │
how-to │ • Summary │
reproduce ───▶│ • How to reproduce (bug) │
│ • The patch (unified diff) │
│ • Local verification I ran │
│ • LGTM from contributor │
│ •
│ 4. 给用户看 comment 草稿，中文讲解， │
│ 确认理解后才 gh issue comment │
│ 5. show URL │
│ 6. 提示用户开一个 "how-i-fix-this" │
│ companion issue 记录修复过程 │
└────────────────────┬────────────────────┘
│
maintainer reads · 👀 ────────────┐
maintainer decides · 🤔 │
cherry-picks / rejects / asks ──▶│
(the skill does NOT force adopt) │
▼
issue thread updated
(no PR, no merge)
Local verification I ran
<command>→<short outcome, e.g. "12 passed, 0 failed">LGTM from contributor
I'm tagging this with LGTM to signal that on my machine, against my
reproduction, this fix works and doesn't regress what I tested.
This patch has not been:
It may break invariants I don't know about. You decide whether to adopt it. If
you want to take it, please cherry-pick into your own branch and run your CI — don't
trust it just because I said LGTM.
Happy to follow up with more detail, more tests, or rework it into a proper PR if
you'd prefer that.
— posted via
/patch(local-fix → candidate-comment workflow)