Skip to content

docs(skills): maintainer-driven tool actions and duplicate-cluster resolution #970

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
castrojo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(skills): maintainer-driven tool actions and duplicate-cluster resolution #970

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions docs/skills/human-gates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: human-gates
version: "1.0"
last_updated: "2026-06-23"
version: "1.1"
last_updated: "2026-08-08"
id: human-gates
one_line_purpose: Decide when to stop for Design, Security, Breakage, or Merge review.
entry_point: docs/skills/human-gates.md
Expand Down Expand Up @@ -87,6 +87,13 @@ This gate is always human. CI passing plus an approving review from a human revi

Agents never self-merge, never bypass branch protection, and never force-push to a protected branch.

This gate binds agents, not the maintainer's own hands. A review tool that
executes a merge or close only on the maintainer's explicit per-item keypress
— with rulesets and branch protection still enforced by GitHub — is the human
acting at the gate, not an agent self-merging. What remains forbidden for any
tool: `--admin` overrides, submitting an approving review, and any
non-interactive batch mutation.

---

## How to Signal a Gate
Expand Down
10 changes: 5 additions & 5 deletions docs/skills/index.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"generated_at": "2026-08-06",
"generated_at": "2026-08-08",
"schema_version": "1.0",
"skills": [
{
Expand Down Expand Up @@ -362,8 +362,8 @@
"security"
],
"description": "The four human decision gates \u2014 Design, Security, Breakage, and Merge \u2014 when an agent must stop and request human input. Use when uncertain whether a change requires human review, or to verify evidence requirements before opening a PR.",
"version": "1.0",
"last_updated": "2026-06-23",
"version": "1.1",
"last_updated": "2026-08-08",
"doc_type": "reference"
},
{
Expand Down Expand Up @@ -503,8 +503,8 @@
"backlog"
],
"description": "Human-decides, agent-lands PR and issue backlog review. Present one card at a time, take the human verdict, execute it immediately, then advance. Use when reviewing the PR queue or triaging the issue backlog.",
"version": "3.4",
"last_updated": "2026-08-07",
"version": "3.5",
"last_updated": "2026-08-08",
"doc_type": "procedure"
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/skills/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
This file is a human-readable mirror of `index.json`. Both are generated by
`scripts/generate_skill_index.py` — do not hand-edit either file.

Generated: 2026-08-06 · schema 1.0 · 39 skills
Generated: 2026-08-08 · schema 1.0 · 39 skills

| id | category | status | one-line purpose |
|---|---|---|---|
Expand Down
12 changes: 9 additions & 3 deletions docs/skills/pr-review/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: pr-review
version: "3.4"
last_updated: "2026-08-07"
version: "3.5"
last_updated: "2026-08-08"
id: pr-review
one_line_purpose: Run human-decides, agent-lands backlog review one card at a time.
entry_point: docs/skills/pr-review/SKILL.md
Expand Down Expand Up @@ -130,6 +130,13 @@ On any overlap, print `⚠️ COMPETING PAIR` between both cards. The human must
resolve the pair (defer one, or explicitly acknowledge) before both can be
voted `merge`.

#### Duplicate-cluster resolution

A competing pair sharing a *closing issue* — or two Renovate PRs normalizing to the *same dependency* — is one piece of work twice, not an ordering hazard. Resolve the cluster as a unit, halting on the first failure:
**(1)** the human names the survivor from presented diff evidence (`gh pr diff` works for fork heads); **(2)** arm the survivor first: `gh pr merge <S> --squash --auto --match-head-commit <sha>` with the SHA read live, so a push before landing is a server-side refusal;
**(3)** comment on each superseded PR naming survivor and evidence (`--body-file`, never `--body` with prose through a shell); **(4)** close it — never `--reason "not planned"`, never a label swap;
**(5)** re-check linked issues per rule 3 below — a still-open issue with no remaining open PR is a finding to report, not something to silently fix.

#### CI card classification

Classify every red before it costs the human a slot. Full triage procedure,
Expand Down Expand Up @@ -164,7 +171,6 @@ git diff <approved_sha>...<current_head>
Full procedure and the table of regressions CI cannot see:
[references/dismissed-approval.md](references/dismissed-approval.md).


### 2 — Verdict

Prompt the human **per PR, one at a time**. Use `gum choose` when available:
Expand Down