josedowski/axioma/gentle-ai-collab-perfect

Claude Code and agent skill by josedowski/axioma

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

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.

Install

npx vskill@latest install josedowski/axioma/gentle-ai-collab-perfect

SKILL.md

The same SKILL.md was published earlier as josedowski/axioma/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.

FileWhat it tells you
CONTRIBUTING.mdIssue-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.mdRequired PR body sections (Linked Issue, PR Type, Summary, Changes, Test Plan, Automated Checks, Contributor Checklist, Notes for Reviewers)
.github/ISSUE_TEMPLATE/bug_report.ymlBug report structure + status:needs-review auto-label + status:approved blocking gate
.github/ISSUE_TEMPLATE/feature_request.ymlFeature request structure + same gates
.github/workflows/pr-check.ymlAutomated gates: Check Issue Reference, Check Issue Has status:approved, Check PR Has type:* Label, Check PR Cognitive Load
.github/ISSUE_TEMPLATE/config.ymlIssue-template routing rules; do not bypass
skills/branch-pr/SKILL.mdBranch + PR creation mechanics
skills/chained-pr/SKILL.mdChained vs Stacked PR strategy mechanics
skills/issue-creation/SKILL.mdIssue creation mechanics
skills/cognitive-doc-design/SKILL.mdDoc-writing principles
skills/comment-writer/SKILL.mdTone 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 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.

ActionContributorMaintainer
Open / comment on issues✅—
Open a PR from a working branch (wherever they push from)✅—
Edit own PR body✅—
Push commits to own branches✅—
Add status:approved to an issue❌✅
Apply type:* label to a PR❌✅
Apply size:exception label❌✅
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 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.

  1. 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.
  1. 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.
  1. 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
  1. For chained PRs, add a brief dependency diagram showing your sibling PRs and the merge order. Mark the current PR with 📍.
  1. 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.

``bash gh pr view <N> --json labels,closingIssuesReferences,additions,deletions,changedFiles ` If labels: [], do not check the "type:* added" box. Instead: ``markdown ## 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

```

  1. Numbers and file counts must match the API. If you can't trust the API, recount locally: git diff --stat <base>..<head>.
  1. 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:

``markdown > **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

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/josedowski/axioma/gentle-ai-collab-perfect/badge)](https://verified-skill.com/skills/josedowski/axioma/gentle-ai-collab-perfect)

Something wrong with this skill or its page? Tell us.