gentle-ai-collab-perfect

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 — read the repo, don't infer

Before recommending any contribution action, read the relevant local file. The repo documents every constraint; pulling rules verbatim beats guessing.

These files evolve. Re-read them at the start of every contribution.

Hard rules (do not negotiate)

1. Issue-first is mandatory. No PR opens without an issue that already has status:approved from a maintainer. Enforced by pr-check.yml and CONTRIBUTING.md.
2. Use Closes/Fixes/Resolves #N in the PR body. Refs #N does NOT satisfy Check Issue Reference. Verified empirically on this repo.
3. Exactly one type:* label per PR. Two type:* labels fail the check. No type:* label fails the check.
4. 400-line budget per PR (additions + deletions). Above that, request size:exception from a maintainer with rationale documented in the PR body.
5. No Co-Authored-By trailers on commits. AI attribution is not acceptable in this repo.
6. No force-push to main. It is protected.
7. PR body checkboxes must reflect API state. If gh pr view --json labels shows labels: [], do not check the "type:* added" box — write a ## Pending maintainer actions section instead.
8. PR titles follow ^(type)(\(scope\))?!?: <description> with exactly one scope (no comma). See skills/branch-pr/SKILL.md for the regex.
9. 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.

If the contributor's PR is "stuck" on something, the next step is almost always a maintainer action — not the contributor trying it. Trying it surfaces GraphQL 403 (AddLabelsToLabelable, requestReviewsByLogin, deployment-protection API) and makes the contributor look unaware of the workflow.

Verified empirically in this repo (July 2026): gh pr edit --add-label type:feature returns 403 ardelperal does not have the correct permissions to execute AddLabelsToLabelable. Treat that error as policy, not as a bug.

Issue workflow

End-to-end steps to open an issue that becomes a viable PR.

1. Search first. Confirm the issue does not already exist (gh search issues or the issue list). Avoid duplicates — CONTRIBUTING.md says PRs on duplicates will be rejected.
2. Pick the template. .github/ISSUE_TEMPLATE/bug_report.yml for bugs, feature_request.yml for changes. Each auto-applies status:needs-review via the template's labels: field.
3. Fill every required field. Don't skip the Pre-flight Checklist. The two self-attestations (not a duplicate; understand status:approved is required) are present for a reason.
4. After submission, watch for status:approved. Comment clarifications promptly. This is the gate before any PR opens.
5. If the maintainer asks for technical sub-slices (e.g. slice/journal-cas, slice/four-layer-engine, slice/tui-cli), keep them as technical slices of one approved issue. The umbrella issue keeps status:approved; the sub-issues should also get approved if you want Check Issue Has status:approved to pass per slice.

PR workflow

End-to-end steps once the issue (or chain of sub-issues) is approved.

1. 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.

2. 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.

3. 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.

4. 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

5. For chained PRs, add a brief dependency diagram showing your sibling PRs and the merge order. Mark the current PR with 📍.

6. 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:

1. 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 maintainer actions
   
   The following are **maintainer-applied per `pr-check.yml` and CONTRIBUTING.md** in this repo — not within contributor scope:
   
   - [ ] `type:feature` label applied to this PR — pending Alan
   - [ ] `size:exception` consideration — see rationale below
   - [ ] Fork workflow approval — 4 runs in `action_required` awaiting Alan
   

2. Numbers and file counts must match the API. If you can't trust the API, recount locally: git diff --stat <base>..<head>.

3. 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 maintainer 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:

• Move the unfulfillable contributor-side check into ## Pending maintainer actions with pending Alan suffix
• 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:

1. Dry-verify with gh first. Attempt the action and surface the error if it fails. Example:

   $ gh pr edit 1132 --add-label type:feature
   → GraphQL: ardelperal does not have the correct permissions to execute `AddLabelsToLabelable`
   

   That output IS your answer. Don't try to work around it.

2. 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
   

3. Cross-check the linked issue state.

   gh issue view <N> --json number,title,state,labels,comments
   

4. 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
   

5. 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.

6. 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:

• Linked issue has status:approved (and the linked PR uses Closes/Fixes/Resolves)
• PR title follows ^(type)(\(single-scope\))?!?: <description> — no comma in scope
• Body uses Closes/Fixes/Resolves #N, not Refs
• Line counts in ## 📂 Changes match gh pr view --json additions,deletions,changedFiles
• No [x] claims contradict what the API shows; moves maintainer-applied actions to ## Pending maintainer actions
• Pre-existing failures named with verification method
• Conventional Commits in title and commit messages
• No Co-Authored-By trailers
• Branch name matches the regex in CONTRIBUTING.md
• Commits are work-unit-sized (one deliverable per commit)
• Chained-slice strategy agreed with the maintainer (Stacked vs Feature Branch Chain)
• Docstring coverage on exported items in the diff ≥80% (CodeRabbit pre-merge check)
• go build ./... clean
• go vet ./... clean
• Local test run with pre-existing failures acknowledged

Anti-patterns

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:

1. Before recommending any action, look up the relevant CONTRIBUTING.md / template / workflow section and cite it.
2. Before any label, status, merge, or fork-workflow approval, check the contributor-vs-maintainer scope table; if maintainer-only, route to the maintainer with a comment or note — do NOT suggest the contributor try it.
3. Before recommending body rewrites, fetch the PR's current state and cross-check every claim against the API.
4. 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.
5. 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/bug_report.yml, feature_request.yml — issue body structures.
• .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.
• skills/issue-creation/SKILL.md — issue creation mechanics in detail.
• 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