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

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 under the canonical issue-creation workflow contract. 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. 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.
4. 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.
5. 400-line budget per PR (additions + deletions). Above that, size:exception additionally requires documented over-budget rationale.
6. No Co-Authored-By trailers on commits. AI attribution is not acceptable in this repo.
7. No force-push to main. It is protected.
8. 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.
9. PR titles follow ^(type)(\(scope\))?!?: <description> with exactly one scope (no comma). See skills/branch-pr/SKILL.md for the regex.
10. 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 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.

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

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

1. Verify authority before a PR-label action. Use the canonical issue-creation workflow contract; do not probe a mutation to discover authority.

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 pending actions to ## Pending repository workflow 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. Route PR labels only through the canonical issue-creation workflow contract; route other maintainer-only actions to a maintainer without suggesting an unauthorized attempt.
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 — 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