When to use
Use this skill when the active repo is Gentleman-Programming/gentle-ai and the contributor is an external collaborator (not the maintainer). Scope of the skill:
- Opening or commenting on issues
- Drafting, editing, or auditing PR bodies
- Choosing a chained-PR strategy (Stacked vs Feature Branch Chain)
- Cross-checking PR claims against the GitHub API
- Deciding whether an action is contributor-scope or maintainer-scope
Do NOT load this skill for:
- Using gentle-ai as an installer (Gentleman-Programming/gentle-ai is the installer itself; not this skill)
- Reading docs, debugging tests, or reviewing the codebase in general
- Tasks on a different repository
The skill assumes the contributor is working from wherever they push — a fork, a personal working repo, or anywhere they have write access. It deliberately does not assume a fork. Use it whether you push to ardelperal/gentle-ai, to a personal fork, or to a contributor org.
Source of truth — inspect the repo, don't infer
Before recommending any contribution action, inspect the relevant current source. The repo documents every constraint; pulling rules verbatim beats guessing.
| Source |
What it tells you |
CONTRIBUTING.md |
Issue-first workflow, label taxonomy, branch naming regex ^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$, Conventional Commits format, 400-line review budget |
.github/PULL_REQUEST_TEMPLATE.md |
Required PR body sections (Linked Issue, PR Type, Summary, Changes, Test Plan, Automated Checks, Contributor Checklist, Notes for Reviewers) |
.github/ISSUE_TEMPLATE |
Current issue templates, forms, and routing policy |
| Discovered GitHub labels |
Current label names and availability; do not infer them from this skill |
.github/workflows/pr-check.yml |
Automated gates: Check Issue Reference, Check Issue Has status:approved, Check PR Has type:* Label, Check PR Cognitive Load |
skills/branch-pr/SKILL.md |
Branch + PR creation mechanics |
skills/chained-pr/SKILL.md |
Chained vs Stacked PR strategy mechanics |
internal/assets/skills/issue-creation/SKILL.md |
Canonical issue discovery, drafting, privacy review, and publication authority |
skills/cognitive-doc-design/SKILL.md |
Doc-writing principles |
skills/comment-writer/SKILL.md |
Tone for comment replies |
These files evolve. Re-read them at the start of every contribution.
Hard rules (do not negotiate)
- Issue-first is mandatory. No PR opens without an issue that already has
status:approved under the canonical issue-creation workflow contract. Enforced by pr-check.yml and CONTRIBUTING.md.
- Use
Closes/Fixes/Resolves #N in the PR body. Refs #N does NOT satisfy Check Issue Reference. Verified empirically on this repo.
- Ordinary
type:* categorization — zero or multiple labels fail the check. Route it through the canonical issue-creation workflow contract: a current direct human instruction binds the exact target/action, target-host capability is verified, and it uses one bounded mutation and target-host readback; otherwise wait without mutation.
- Protected policy labels — adding or removing
status:approved or size:exception requires verified policy authority from a target-host repository maintainer or repository-authorized approver for the exact target/action, plus authenticated actor target-host viewerPermission MAINTAIN or ADMIN. size:exception additionally requires documented over-budget rationale.
- 400-line budget per PR (
additions + deletions). Above that, size:exception additionally requires documented over-budget rationale.
- No
Co-Authored-By trailers on commits. AI attribution is not acceptable in this repo.
- No force-push to
main. It is protected.
- PR body checkboxes must reflect API state. If
gh pr view --json labels shows labels: [], do not check the "type:* added" box — record the pending canonical PR-label action instead.
- PR titles follow
^(type)(\(scope\))?!?: <description> with exactly one scope (no comma). See skills/branch-pr/SKILL.md for the regex.
- Pre-existing test failures are named honestly. This repo has pre-existing failures in
pi_codegraph, tui/sync, and similar packages. Acknowledging them with the verification method (e.g. git stash baseline) is mandatory. Claiming "all tests pass" without that context is dishonest.
Contributor vs maintainer scope
This split catches external contributors most often. Verify with gh before recommending any action that requires elevated permissions.
| Action |
Contributor |
Maintainer |
| Open / comment on issues |
✅ |
— |
| Open a PR from a working branch (wherever they push from) |
✅ |
— |
| Edit own PR body |
✅ |
— |
| Push commits to own branches |
✅ |
— |
| Apply/remove ordinary existing issue labels |
Only under the canonical issue-creation workflow contract and target-host capability grant |
Same; verify the target host grants the action |
Apply/remove ordinary type:* PR categorization |
Only under the canonical issue-creation workflow contract: current direct human instruction, exact target/action, target-host capability, one bounded mutation and target-host readback |
Same; verify the target host grants the action |
Add/remove protected status:approved or size:exception |
Verified policy authority from a repository maintainer or repository-authorized approver plus actor MAINTAIN/ADMIN; size:exception also needs documented rationale |
Same verified policy authority, actor capability, and rationale |
Approve action_required fork-PR workflows (fork approval gate) |
❌ |
✅ |
| Review a PR (approve / request changes) |
❌ |
✅ |
| Merge a PR |
❌ |
✅ |
| Push slice/* branches to upstream so cross-fork base refs work |
❌ |
✅ |
If a PR-label action lacks a current direct instruction or verified target-host capability, wait without mutation. Other maintainer-only actions remain maintainer-only.
Issue workflow
Use the canonical issue-creation skill at internal/assets/skills/issue-creation/SKILL.md for duplicate discovery, template handling, privacy review, and publication. Apply Gentle AI's current repository policy from CONTRIBUTING.md, .github/ISSUE_TEMPLATE, and discovered GitHub labels rather than copying form fields, label names, or commands here.
After submission, return to this collaboration workflow for the contributor/maintainer boundary and the approved-issue gate before PR work. If a maintainer requests technical sub-slices, keep them within the approved issue structure required by the current repository policy and checks.
PR workflow
End-to-end steps once the issue (or chain of sub-issues) is approved.
Branch.
git checkout main && git pull
git checkout -b <type>/<short-description>
Branch name matches the regex in CONTRIBUTING.md. <short-description> is kebab-case, max a few words.
Implement. Work-unit commits: each commit is one deliverable unit with its code + tests + docs. Keep rollback reasonable — reverting one commit should not remove unrelated work.
Local validation.
go build ./... clean
go vet ./... clean
go test ./internal/... with pre-existing failures acknowledged via git stash baseline. The repo has known pre-existing failures in internal/components/communitytool/pi_codegraph, internal/tui/sync, and similar — confirm they exist with git stash AND git stash pop, then name them in the PR body's Test Plan.
Open the PR with gh pr create. Body matches .github/PULL_REQUEST_TEMPLATE.md:
## 🔗 Linked Issue → Closes #N (or Fixes/Resolves). Never Refs.
## 🏷️ PR Type → exactly one [x] type:* matching the actual type
## 📝 Summary → one paragraph: what + why
## 📂 Changes → file table with line counts from gh pr view --json additions,deletions,changedFiles
## 🧪 Test Plan → every go test command actually run + result, including pre-existing failures with verification method
## ✅ Contributor Checklist → [x] only where verifiable; [ ] pending maintainer for the rest
## 💬 Notes for Reviewers → chain position, merge order, blockers
For chained PRs, add a brief dependency diagram showing your sibling PRs and the merge order. Mark the current PR with 📍.
After opening: check gh pr checks --json and address any pending contributor follow-up items you documented in the body.
PR body honesty — the single most often-abused rule
Every [x] in the Contributor Checklist is a public claim that pr-check.yml and the maintainer will verify. Three rules:
Mark [x] only when the assertion is true against the API.
gh pr view <N> --json labels,closingIssuesReferences,additions,deletions,changedFiles
If labels: [], do not check the "type:* added" box. Instead:
## Pending repository workflow actions
The following remain pending:
- [ ] Ordinary `type:feature` categorization requires the canonical issue-creation workflow contract
- [ ] Protected `size:exception` requires its documented rationale and verified policy authority from a repository maintainer or repository-authorized approver
- [ ] Fork workflow approval — 4 runs in `action_required` awaiting a maintainer
Numbers and file counts must match the API. If you can't trust the API, recount locally: git diff --stat <base>..<head>.
Pre-existing failures must be named and methodology stated. "Tests pass" is dishonest if four packages fail in the git stash-absent baseline. State them:
> **Known pre-existing failures (not blocking this PR):** `internal/components/communitytool/pi_codegraph`, `internal/tui/sync`, `internal/tui/sddmode` clusters present on `main` are not introduced by this slice; verified identical via `git stash` baseline.
Honest rewrites often look like adding content, not removing. Adding ## Pending repository workflow actions and a quoted callout for pre-existing failures is normal and expected.
Standard honest-rewrite pattern
When the contributor checks a box that doesn't reflect reality:
- For a PR label, record its pending canonical workflow action; keep other maintainer-only actions distinct
- Update diff numbers to match the API exactly; if a qualifier is needed (e.g. "slice-specific commits only"), state it explicitly
- For test claims, state the exact local commands run and the count of PASS/SKIP observed; don't aggregate to "all pass" if any were skipped on Windows
- Always name pre-existing repo failures that the contributor observed but did not fix, with the verification method (
git stash baseline)
- For process claims (e.g. "blind dual review approved"), reference the artifact (round-1 → round-2 polish commits ARE that evidence)
Chained PR strategy
This repo supports two strategies via gentle-ai-chained-pr:
Stacked to main
Use when each slice can land independently. Branches are independent stacks that each target main. The diff "pollutes" with previous-slice commits because GitHub does not allow cross-fork base refs (slice branches live only in the contributor's working repo).
- Pros: simple, each PR is its own atomic change.
- Cons: large chained diffs; reviewers must mentally isolate slice-specific changes; needs
size:exception for anything past 400 lines of slice-specific additions.
Feature Branch Chain (tracker PR)
Use when the feature integrates as one atomic unit. The maintainer pushes the slice/* branches to the upstream as branch (not PR); child PR #1 targets the tracker branch, child #2 targets the child #1 branch, child #3 targets child #2. The tracker PR stays draft / no-merge until all children are reviewed and merged.
- Pros: clean per-slice diffs; atomic integration; reversible as a unit.
- Cons: requires maintainer cooperation to push slice branches upstream; slower.
Critical limitation: GitHub does NOT support cross-fork base refs. If your slice branches live only in your working repo, the only options are:
- Stacked to main (with polluted diffs) — accept the reality
- Ask the maintainer to push slice branches upstream so you can do Feature Branch Chain
The maintainer is the only one who can make Feature Branch Chain work; the contributor alone cannot force it.
Verification protocol
Before recommending any action that touches permissions, label state, or commit history:
Verify authority before a PR-label action. Use the canonical issue-creation workflow contract; do not probe a mutation to discover authority.
Cross-check PR body claims against the GitHub API.
gh pr view <N> --json \
labels,closingIssuesReferences,additions,deletions,changedFiles,\
headRefName,baseRefName,isCrossRepository,headRepository,maintainerCanModify,\
reviewDecision,statusCheckRollup
Cross-check the linked issue state.
gh issue view <N> --json number,title,state,labels,comments
After applying a body rewrite, round-trip the body and confirm closingIssuesReferences is populated for the linked issue:
gh pr view <N> --json body --jq '.body' # round-trip
gh pr view <N> --json closingIssuesReferences # confirm linkage parsed
Trust the contributor's lived permissions over inferred defaults. If they say "I can only do X", route everything else to the maintainer — don't waste their PR review budget on GraphQL 403s.
Always run the actual test command before claiming it passes. "Tests pass" must reflect go test ./path/to/pkg -v output, not hope.
Pre-PR self-audit checklist
Run this in your head (or print and tick) before requesting review:
Anti-patterns
| Anti-pattern |
Symptom |
Fix |
"type:* added" checkbox while labels: [] |
CodeRabbit or maintainer catches the lie on first read |
Record the pending canonical PR-label action |
Refs #N instead of Closes #N |
Check Issue Reference fails; PR auto-rejected |
Use Closes/Fixes/Resolves keyword |
[x] PR stays within 400 changed lines for a 3,200-line PR |
Check PR Cognitive Load fails; size:exception not requested |
Compute real totals, document the rationale and verified policy authority in Pending repository workflow actions |
feat(tui,cli): wire... title |
Title fails the single-scope regex |
Use one of feat(tui): ..., feat(cli): ..., feat(tui-cli): ... (dash, not comma) |
Slice branches all base on main with stale carry-over commits |
Reviewers can't isolate slice-specific changes; size:exception needed |
Accept Stacked to main (request exception) OR ask maintainer to push slice branches upstream and use Feature Branch Chain |
| Mutating a PR label without canonical authority |
No current direct instruction or verified capability |
Wait without mutation |
| Burning reviewer attention on smoke-test green |
Low-cardinality tests pass without exercising the behavior; reviewer flags in CodeRabbit |
Each test asserts specific behavior, not just non-panicking |
Pretending local test run = go test ./... clean |
Repo has pre-existing failures (pi_codegraph, tui/sync); saying "all tests pass" is dishonest |
Run with git stash baseline, name pre-existing failures explicitly |
| Calling a working repo a "fork" in code or docs |
Misrepresents the contributor's relationship to the upstream |
Use neutral language: "your working branch", "the contributor's push location", not "your fork" |
How to apply this skill — workflow for the AI assistant
When you (the AI assistant) are helping a contributor with anything that touches this repo:
- Before recommending any action, look up the relevant
CONTRIBUTING.md / template / workflow section and cite it.
- Before any label, status, merge, or fork-workflow approval, check the contributor-vs-maintainer scope table. Route PR labels only through the canonical issue-creation workflow contract; route other maintainer-only actions to a maintainer without suggesting an unauthorized attempt.
- Before recommending body rewrites, fetch the PR's current state and cross-check every claim against the API.
- Before recommending chained-PR structure, ask the contributor whether each slice can land independently (Stacked) or needs atomic integration (Feature Branch Chain). Be explicit about the cross-fork base-ref limitation.
- Always use Conventional Commits in title and commit messages.
When in doubt, the right move is more verification, less action.
References
CONTRIBUTING.md — full workflow, label taxonomy, branch naming, commit format, review budget.
.github/PULL_REQUEST_TEMPLATE.md — PR body structure.
.github/ISSUE_TEMPLATE — current issue templates, forms, and routing policy.
.github/workflows/pr-check.yml — automated gates.
skills/branch-pr/SKILL.md — branch + PR creation mechanics in detail.
skills/chained-pr/SKILL.md — chained vs stacked PR strategy mechanics in detail.
internal/assets/skills/issue-creation/SKILL.md — canonical issue-creation authority.
skills/cognitive-doc-design/SKILL.md — doc-writing principles (low cognitive load).
skills/comment-writer/SKILL.md — tone and structure for PR comments and issue replies.
skills/work-unit-commits/SKILL.md — splitting commits for review-friendly PRs.
GitHub Actions docs for the action_required gate used in fork PRs: https://docs.github.com/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks
1---
2name: gentle-ai-collab-perfect
3description: "Trigger: contributing to Gentleman-Programming/gentle-ai as an external collaborator. Strict issue-first workflow, honest PR bodies, contributor-vs-maintainer scope, chained-PR strategy, verification protocol, docstring coverage. Load whenever the active repo is Gentleman-Programming/gentle-ai and any part of the contribution flow is in scope: opening an issue, drafting or editing a PR body, splitting a change into chained/stacked PRs, or auditing a PR before requesting review."
4license: Apache-2.0
5metadata:
6 source: https://skillmd.com/skills/gabrielmoreira/gentle-ai-collab-perfect
7 author: ardelperal
8 version: "0.1"
9---
10
11## When to use
12
13Use this skill when the active repo is `Gentleman-Programming/gentle-ai` and the contributor is an external collaborator (not the maintainer). Scope of the skill:
14
15- Opening or commenting on issues
16- Drafting, editing, or auditing PR bodies
17- Choosing a chained-PR strategy (Stacked vs Feature Branch Chain)
18- Cross-checking PR claims against the GitHub API
19- Deciding whether an action is contributor-scope or maintainer-scope
20
21Do NOT load this skill for:
22
23- Using gentle-ai as an installer (Gentleman-Programming/gentle-ai is the installer itself; not this skill)
24- Reading docs, debugging tests, or reviewing the codebase in general
25- Tasks on a different repository
26
27The skill assumes the contributor is working from wherever they push — a fork, a personal working repo, or anywhere they have write access. **It deliberately does not assume a fork.** Use it whether you push to `ardelperal/gentle-ai`, to a personal fork, or to a contributor org.
28
29---
30
31## Source of truth — inspect the repo, don't infer
32
33Before recommending any contribution action, inspect the relevant current source. The repo documents every constraint; pulling rules verbatim beats guessing.
34
35| Source | What it tells you |
36|---|---|
37| `CONTRIBUTING.md` | Issue-first workflow, label taxonomy, branch naming regex `^(feat\|fix\|chore\|docs\|style\|refactor\|perf\|test\|build\|ci\|revert)\/[a-z0-9._-]+$`, Conventional Commits format, 400-line review budget |
38| `.github/PULL_REQUEST_TEMPLATE.md` | Required PR body sections (Linked Issue, PR Type, Summary, Changes, Test Plan, Automated Checks, Contributor Checklist, Notes for Reviewers) |
39| `.github/ISSUE_TEMPLATE` | Current issue templates, forms, and routing policy |
40| Discovered GitHub labels | Current label names and availability; do not infer them from this skill |
41| `.github/workflows/pr-check.yml` | Automated gates: `Check Issue Reference`, `Check Issue Has status:approved`, `Check PR Has type:* Label`, `Check PR Cognitive Load` |
42| `skills/branch-pr/SKILL.md` | Branch + PR creation mechanics |
43| `skills/chained-pr/SKILL.md` | Chained vs Stacked PR strategy mechanics |
44| `internal/assets/skills/issue-creation/SKILL.md` | Canonical issue discovery, drafting, privacy review, and publication authority |
45| `skills/cognitive-doc-design/SKILL.md` | Doc-writing principles |
46| `skills/comment-writer/SKILL.md` | Tone for comment replies |
47
48These files evolve. Re-read them at the start of every contribution.
49
50---
51
52## Hard rules (do not negotiate)
53
541. **Issue-first is mandatory.** No PR opens without an issue that already has `status:approved` under the canonical issue-creation workflow contract. Enforced by `pr-check.yml` and CONTRIBUTING.md.
552. **Use `Closes/Fixes/Resolves #N`** in the PR body. `Refs #N` does NOT satisfy `Check Issue Reference`. Verified empirically on this repo.
563. **Ordinary `type:*` categorization** — zero or multiple labels fail the check. Route it through the canonical issue-creation workflow contract: a current direct human instruction binds the exact target/action, target-host capability is verified, and it uses one bounded mutation and target-host readback; otherwise wait without mutation.
574. **Protected policy labels** — adding or removing `status:approved` or `size:exception` requires verified policy authority from a target-host repository maintainer or repository-authorized approver for the exact target/action, plus authenticated actor target-host `viewerPermission` `MAINTAIN` or `ADMIN`. `size:exception` additionally requires documented over-budget rationale.
585. **400-line budget per PR** (`additions + deletions`). Above that, `size:exception` additionally requires documented over-budget rationale.
596. **No `Co-Authored-By` trailers** on commits. AI attribution is not acceptable in this repo.
607. **No force-push to `main`.** It is protected.
618. **PR body checkboxes must reflect API state.** If `gh pr view --json labels` shows `labels: []`, do not check the "type:* added" box — record the pending canonical PR-label action instead.
629. **PR titles follow `^(type)(\(scope\))?!?: <description>`** with exactly **one scope** (no comma). See `skills/branch-pr/SKILL.md` for the regex.
6310. **Pre-existing test failures are named honestly.** This repo has pre-existing failures in `pi_codegraph`, `tui/sync`, and similar packages. Acknowledging them with the verification method (e.g. `git stash` baseline) is mandatory. Claiming "all tests pass" without that context is dishonest.
64
65---
66
67## Contributor vs maintainer scope
68
69This split catches external contributors most often. Verify with `gh` before recommending any action that requires elevated permissions.
70
71| Action | Contributor | Maintainer |
72|---|---|---|
73| Open / comment on issues | ✅ | — |
74| Open a PR from a working branch (wherever they push from) | ✅ | — |
75| Edit own PR body | ✅ | — |
76| Push commits to own branches | ✅ | — |
77| Apply/remove ordinary existing issue labels | Only under the canonical issue-creation workflow contract and target-host capability grant | Same; verify the target host grants the action |
78| Apply/remove ordinary `type:*` PR categorization | Only under the canonical issue-creation workflow contract: current direct human instruction, exact target/action, target-host capability, one bounded mutation and target-host readback | Same; verify the target host grants the action |
79| Add/remove protected `status:approved` or `size:exception` | Verified policy authority from a repository maintainer or repository-authorized approver plus actor `MAINTAIN`/`ADMIN`; `size:exception` also needs documented rationale | Same verified policy authority, actor capability, and rationale |
80| Approve `action_required` fork-PR workflows (fork approval gate) | ❌ | ✅ |
81| Review a PR (approve / request changes) | ❌ | ✅ |
82| Merge a PR | ❌ | ✅ |
83| Push slice/* branches to upstream so cross-fork base refs work | ❌ | ✅ |
84
85If a PR-label action lacks a current direct instruction or verified target-host capability, wait without mutation. Other maintainer-only actions remain maintainer-only.
86
87---
88
89## Issue workflow
90
91Use the canonical `issue-creation` skill at `internal/assets/skills/issue-creation/SKILL.md` for duplicate discovery, template handling, privacy review, and publication. Apply Gentle AI's current repository policy from `CONTRIBUTING.md`, `.github/ISSUE_TEMPLATE`, and discovered GitHub labels rather than copying form fields, label names, or commands here.
92
93After submission, return to this collaboration workflow for the contributor/maintainer boundary and the approved-issue gate before PR work. If a maintainer requests technical sub-slices, keep them within the approved issue structure required by the current repository policy and checks.
94
95---
96
97## PR workflow
98
99End-to-end steps once the issue (or chain of sub-issues) is approved.
100
1011. **Branch.**
102 ```
103 git checkout main && git pull
104 git checkout -b <type>/<short-description>
105 ```
106 Branch name matches the regex in `CONTRIBUTING.md`. `<short-description>` is kebab-case, max a few words.
107
1082. **Implement.** Work-unit commits: each commit is one deliverable unit with its code + tests + docs. Keep rollback reasonable — reverting one commit should not remove unrelated work.
109
1103. **Local validation.**
111 - `go build ./...` clean
112 - `go vet ./...` clean
113 - `go test ./internal/...` with pre-existing failures acknowledged via `git stash` baseline. The repo has known pre-existing failures in `internal/components/communitytool/pi_codegraph`, `internal/tui/sync`, and similar — confirm they exist with `git stash` AND `git stash pop`, then name them in the PR body's Test Plan.
114
1154. **Open the PR with `gh pr create`.** Body matches `.github/PULL_REQUEST_TEMPLATE.md`:
116 - `## 🔗 Linked Issue` → `Closes #N` (or `Fixes`/`Resolves`). Never `Refs`.
117 - `## 🏷️ PR Type` → exactly one `[x] type:*` matching the actual type
118 - `## 📝 Summary` → one paragraph: what + why
119 - `## 📂 Changes` → file table with line counts from `gh pr view --json additions,deletions,changedFiles`
120 - `## 🧪 Test Plan` → every `go test` command actually run + result, **including pre-existing failures with verification method**
121 - `## ✅ Contributor Checklist` → `[x]` only where verifiable; `[ ] pending maintainer` for the rest
122 - `## 💬 Notes for Reviewers` → chain position, merge order, blockers
123
1245. **For chained PRs**, add a brief dependency diagram showing your sibling PRs and the merge order. Mark the current PR with `📍`.
125
1266. **After opening:** check `gh pr checks --json` and address any `pending contributor follow-up` items you documented in the body.
127
128---
129
130## PR body honesty — the single most often-abused rule
131
132Every `[x]` in the Contributor Checklist is a public claim that `pr-check.yml` and the maintainer will verify. Three rules:
133
1341. **Mark `[x]` only when the assertion is true against the API.**
135 ```bash
136 gh pr view <N> --json labels,closingIssuesReferences,additions,deletions,changedFiles
137 ```
138 If `labels: []`, do not check the "type:* added" box. Instead:
139 ```markdown
140 ## Pending repository workflow actions
141
142 The following remain pending:
143
144 - [ ] Ordinary `type:feature` categorization requires the canonical issue-creation workflow contract
145 - [ ] Protected `size:exception` requires its documented rationale and verified policy authority from a repository maintainer or repository-authorized approver
146 - [ ] Fork workflow approval — 4 runs in `action_required` awaiting a maintainer
147 ```
148
1492. **Numbers and file counts must match the API.** If you can't trust the API, recount locally: `git diff --stat <base>..<head>`.
150
1513. **Pre-existing failures must be named and methodology stated.** "Tests pass" is dishonest if four packages fail in the `git stash`-absent baseline. State them:
152 ```markdown
153 > **Known pre-existing failures (not blocking this PR):** `internal/components/communitytool/pi_codegraph`, `internal/tui/sync`, `internal/tui/sddmode` clusters present on `main` are not introduced by this slice; verified identical via `git stash` baseline.
154 ```
155
156Honest rewrites often look like **adding** content, not removing. Adding `## Pending repository workflow actions` and a quoted callout for pre-existing failures is normal and expected.
157
158### Standard honest-rewrite pattern
159
160When the contributor checks a box that doesn't reflect reality:
161- For a PR label, record its pending canonical workflow action; keep other maintainer-only actions distinct
162- Update diff numbers to match the API exactly; if a qualifier is needed (e.g. "slice-specific commits only"), state it explicitly
163- For test claims, state the exact local commands run and the count of PASS/SKIP observed; don't aggregate to "all pass" if any were skipped on Windows
164- Always name pre-existing repo failures that the contributor observed but did not fix, with the verification method (`git stash` baseline)
165- For process claims (e.g. "blind dual review approved"), reference the artifact (round-1 → round-2 polish commits ARE that evidence)
166
167---
168
169## Chained PR strategy
170
171This repo supports two strategies via `gentle-ai-chained-pr`:
172
173### Stacked to main
174
175Use when **each slice can land independently**. Branches are independent stacks that each target `main`. The diff "pollutes" with previous-slice commits because GitHub does not allow cross-fork base refs (slice branches live only in the contributor's working repo).
176
177- Pros: simple, each PR is its own atomic change.
178- Cons: large chained diffs; reviewers must mentally isolate slice-specific changes; needs `size:exception` for anything past 400 lines of slice-specific additions.
179
180### Feature Branch Chain (tracker PR)
181
182Use when **the feature integrates as one atomic unit**. The maintainer pushes the slice/* branches to the upstream as `branch` (not PR); child PR #1 targets the tracker branch, child #2 targets the child #1 branch, child #3 targets child #2. The tracker PR stays draft / no-merge until all children are reviewed and merged.
183
184- Pros: clean per-slice diffs; atomic integration; reversible as a unit.
185- Cons: requires maintainer cooperation to push slice branches upstream; slower.
186
187**Critical limitation:** GitHub does NOT support cross-fork base refs. If your slice branches live only in your working repo, the only options are:
188- Stacked to main (with polluted diffs) — accept the reality
189- Ask the maintainer to push slice branches upstream so you can do Feature Branch Chain
190
191The maintainer is the only one who can make Feature Branch Chain work; the contributor alone cannot force it.
192
193---
194
195## Verification protocol
196
197Before recommending any action that touches permissions, label state, or commit history:
198
1991. **Verify authority before a PR-label action.** Use the canonical issue-creation workflow contract; do not probe a mutation to discover authority.
200
2012. **Cross-check PR body claims against the GitHub API.**
202 ```bash
203 gh pr view <N> --json \
204 labels,closingIssuesReferences,additions,deletions,changedFiles,\
205 headRefName,baseRefName,isCrossRepository,headRepository,maintainerCanModify,\
206 reviewDecision,statusCheckRollup
207 ```
208
2093. **Cross-check the linked issue state.**
210 ```bash
211 gh issue view <N> --json number,title,state,labels,comments
212 ```
213
2144. **After applying a body rewrite**, round-trip the body and confirm `closingIssuesReferences` is populated for the linked issue:
215 ```bash
216 gh pr view <N> --json body --jq '.body' # round-trip
217 gh pr view <N> --json closingIssuesReferences # confirm linkage parsed
218 ```
219
2205. **Trust the contributor's lived permissions over inferred defaults.** If they say "I can only do X", route everything else to the maintainer — don't waste their PR review budget on GraphQL 403s.
221
2226. **Always run the actual test command before claiming it passes.** "Tests pass" must reflect `go test ./path/to/pkg -v` output, not hope.
223
224---
225
226## Pre-PR self-audit checklist
227
228Run this in your head (or print and tick) before requesting review:
229
230- [ ] Linked issue has `status:approved` (and the linked PR uses `Closes/Fixes/Resolves`)
231- [ ] PR title follows `^(type)(\(single-scope\))?!?: <description>` — no comma in scope
232- [ ] Body uses `Closes/Fixes/Resolves #N`, not `Refs`
233- [ ] Line counts in `## 📂 Changes` match `gh pr view --json additions,deletions,changedFiles`
234- [ ] No `[x]` claims contradict what the API shows; moves pending actions to `## Pending repository workflow actions`
235- [ ] Pre-existing failures named with verification method
236- [ ] Conventional Commits in title and commit messages
237- [ ] No `Co-Authored-By` trailers
238- [ ] Branch name matches the regex in CONTRIBUTING.md
239- [ ] Commits are work-unit-sized (one deliverable per commit)
240- [ ] Chained-slice strategy agreed with the maintainer (Stacked vs Feature Branch Chain)
241- [ ] Docstring coverage on exported items in the diff ≥80% (CodeRabbit pre-merge check)
242- [ ] `go build ./...` clean
243- [ ] `go vet ./...` clean
244- [ ] Local test run with pre-existing failures acknowledged
245
246---
247
248## Anti-patterns
249
250| Anti-pattern | Symptom | Fix |
251|---|---|---|
252| "type:* added" checkbox while `labels: []` | CodeRabbit or maintainer catches the lie on first read | Record the pending canonical PR-label action |
253| `Refs #N` instead of `Closes #N` | `Check Issue Reference` fails; PR auto-rejected | Use `Closes`/`Fixes`/`Resolves` keyword |
254| `[x] PR stays within 400 changed lines` for a 3,200-line PR | `Check PR Cognitive Load` fails; `size:exception` not requested | Compute real totals, document the rationale and verified policy authority in Pending repository workflow actions |
255| `feat(tui,cli): wire...` title | Title fails the single-scope regex | Use one of `feat(tui): ...`, `feat(cli): ...`, `feat(tui-cli): ...` (dash, not comma) |
256| Slice branches all base on `main` with stale carry-over commits | Reviewers can't isolate slice-specific changes; `size:exception` needed | Accept Stacked to main (request exception) OR ask maintainer to push slice branches upstream and use Feature Branch Chain |
257| Mutating a PR label without canonical authority | No current direct instruction or verified capability | Wait without mutation |
258| Burning reviewer attention on smoke-test green | Low-cardinality tests pass without exercising the behavior; reviewer flags in CodeRabbit | Each test asserts specific behavior, not just non-panicking |
259| Pretending local test run = `go test ./...` clean | Repo has pre-existing failures (`pi_codegraph`, `tui/sync`); saying "all tests pass" is dishonest | Run with `git stash` baseline, name pre-existing failures explicitly |
260| Calling a working repo a "fork" in code or docs | Misrepresents the contributor's relationship to the upstream | Use neutral language: "your working branch", "the contributor's push location", not "your fork" |
261
262---
263
264## How to apply this skill — workflow for the AI assistant
265
266When you (the AI assistant) are helping a contributor with anything that touches this repo:
267
2681. **Before recommending any action**, look up the relevant `CONTRIBUTING.md` / template / workflow section and cite it.
2692. **Before any label, status, merge, or fork-workflow approval**, check the contributor-vs-maintainer scope table. Route PR labels only through the canonical issue-creation workflow contract; route other maintainer-only actions to a maintainer without suggesting an unauthorized attempt.
2703. **Before recommending body rewrites**, fetch the PR's current state and cross-check every claim against the API.
2714. **Before recommending chained-PR structure**, ask the contributor whether each slice can land independently (Stacked) or needs atomic integration (Feature Branch Chain). Be explicit about the cross-fork base-ref limitation.
2725. **Always** use Conventional Commits in title and commit messages.
273
274When in doubt, the right move is more verification, less action.
275
276---
277
278## References
279
280- `CONTRIBUTING.md` — full workflow, label taxonomy, branch naming, commit format, review budget.
281- `.github/PULL_REQUEST_TEMPLATE.md` — PR body structure.
282- `.github/ISSUE_TEMPLATE` — current issue templates, forms, and routing policy.
283- `.github/workflows/pr-check.yml` — automated gates.
284- `skills/branch-pr/SKILL.md` — branch + PR creation mechanics in detail.
285- `skills/chained-pr/SKILL.md` — chained vs stacked PR strategy mechanics in detail.
286- `internal/assets/skills/issue-creation/SKILL.md` — canonical issue-creation authority.
287- `skills/cognitive-doc-design/SKILL.md` — doc-writing principles (low cognitive load).
288- `skills/comment-writer/SKILL.md` — tone and structure for PR comments and issue replies.
289- `skills/work-unit-commits/SKILL.md` — splitting commits for review-friendly PRs.
290
291GitHub Actions docs for the `action_required` gate used in fork PRs: https://docs.github.com/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks