gentle-ai-collab-perfect

---

name: gentle-ai-collab-perfect description: "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." license: Apache-2.0 metadata: author: ardelperal version: "0.1"

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 any target-host read, obtain explicit authorization for the remote destination (exact target), read operation and credential/session; never probe ambient credentials. Locally, 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, AI Assistance, 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)

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. Ask the human whether the PR should close the approved issue on merge. Preserve the human-selected Closes/Fixes/Resolves #N closing intent or Refs #N non-closing intent; both can satisfy Check Issue Reference. Never infer or change closing intent.
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 authenticated actor target-host viewerPermission MAINTAIN or ADMIN and a current direct human instruction binding the exact target/action; here verified policy authority means that actor permission and exact direct instruction, not separate target-host proof of the instruction-giver's identity. Do not mutate automatically. size:exception additionally requires documented over-budget rationale and human choice.
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 require proof. Compare the same failing command/environment against a comparable isolated clean base without disturbing user changes; otherwise report baseline unverified. Do not assume particular packages fail or claim all tests pass when they fail.

---

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 | Current direct human instruction for the exact target/action plus actor MAINTAIN/ADMIN; size:exception also needs documented rationale and human choice | Same exact direct instruction, actor capability, human choice 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.

1. Branch.

   # Resolve the authorized target's default/base branch from current metadata.
   # Obtain human authorization before checkout or branch creation.
   

   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/...: report observed failures. Attribute failures to the base only after the same command/environment reproduces on a comparable isolated clean base; otherwise mark baseline unverified.

4. Draft the PR body before PR creation. Obtain explicit human authorization for the PR creation operation, exact remote destination and credential/session before any target-host read or publication; drafting is not permission to publish. When authorized, use the current .github/PULL_REQUEST_TEMPLATE.md:

   • ## 🔗 Linked Issue → human-selected closing (Closes/Fixes/Resolves #N) or non-closing (Refs #N) reference.
   • ## 🏷️ PR Type → exactly one [x] type:* matching the actual type
   • ## 📝 Summary → one paragraph: what + why
   • ## 📂 Changes → before PR creation, use local diff counts for the intended base/head and label them provisional; do not claim post-publication API numbers yet.
   • ## 🤖 AI Assistance → select exactly one of None or Material assistance used based on actual use; if material, complete applicable tool/model (if known), material scope and verification performed fields. Do not precheck either choice without evidence; follow AI_POLICY.md.
   • ## 🧪 Test Plan → every go test command actually run + result; distinguish clean-base-proven failures from baseline unverified.
   • ## ✅ Contributor Checklist → [x] only where verifiable, including the required AI-assistance option and applicable declaration fields; [ ] 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, only if PR creation was actually confirmed: under explicit authorization for the exact remote destination, post-publication read operation and credential/session, read the PR's additions,deletions,changedFiles from the target API and reconcile the provisional local diff counts. A body correction needs a separately authorized edit for that exact PR; never invent a successful remote read, edit or creation. Reuse fresh target-bound issue approval, default branch, type-label and check observations. Read target branch rulesets/branch protection and current run status to identify REQUIRED CI. CodeRabbit pending is optional unless target policy requires it. Unknown requiredness is not merge-ready. Commit, push, PR, merge, chain strategy/exception and native RDD consent remain human-owned.

---

PR body honesty — the single most often-abused rule

Every [x] in the Contributor Checklist is a public claim requiring evidence appropriate to that claim. Use API-backed PR state for issue linkage, labels and published counts; locally observed test evidence for test claims; and an honest human/agent AI declaration for the AI Assistance selection and applicable fields. Do not precheck any claim without its evidence. Three rules:

1. For API-backed PR state, mark [x] only when the assertion is true against the authorized target API.

   gh pr view <N> --repo "$TARGET" --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 human ch