/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 availability only; inventory is not permission. Use the reviewed `CONTRIBUTING.md` catalog | | `.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 ordin