Skill v1.0.1
currentAutomated scan96/100+2 new
version: "1.0.1" name: gentle-ai-branch-pr description: "Create Gentle AI pull requests with issue-first checks. Trigger: creating, opening, or preparing PRs for review." license: Apache-2.0 metadata: author: gentleman-programming version: "2.0"
When to Use
Use this skill when:
- Creating a pull request for any change
- Preparing a branch for submission
- Helping a contributor open a PR
Critical Rules
- Every PR MUST link an approved issue — no exceptions
- Every PR MUST have exactly one `type:*` label
- Automated checks must pass before merge is possible
- Blank PRs without issue linkage will be blocked by GitHub Actions
Workflow
1. Verify issue has `status:approved` label2. Create branch: type/description (see Branch Naming below)3. Implement changes with conventional commits4. Run shellcheck on modified scripts5. Open PR using the template6. Add exactly one type:* label7. Wait for automated checks to pass
Branch Naming
Branch names MUST match this regex:
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
Format: type/description — lowercase, no spaces, only a-z0-9._- in description.
| Type | Branch pattern | Example | |
|---|---|---|---|
| Feature | feat/<description> | feat/user-login | |
| Bug fix | fix/<description> | fix/zsh-glob-error | |
| Chore | chore/<description> | chore/update-ci-actions | |
| Docs | docs/<description> | docs/installation-guide | |
| Style | style/<description> | style/format-scripts | |
| Refactor | refactor/<description> | refactor/extract-shared-logic | |
| Performance | perf/<description> | perf/reduce-startup-time | |
| Test | test/<description> | test/add-setup-coverage | |
| Build | build/<description> | build/update-shellcheck | |
| CI | ci/<description> | ci/add-branch-validation | |
| Revert | revert/<description> | revert/broken-setup-change |
PR Body Format
The PR template is at .github/PULL_REQUEST_TEMPLATE.md. Every PR body MUST contain:
1. Linked Issue (REQUIRED)
Closes #<issue-number>
Valid keywords: Closes #N, Fixes #N, Resolves #N (case insensitive). The linked issue MUST have the status:approved label.
2. PR Type (REQUIRED)
Check exactly ONE in the template and add the matching label:
| Checkbox | Label to add | |
|---|---|---|
| Bug fix | type:bug | |
| New feature | type:feature | |
| Documentation only | type:docs | |
| Code refactoring | type:refactor | |
| Maintenance/tooling | type:chore | |
| Breaking change | type:breaking-change |
3. Summary
1-3 bullet points of what the PR does.
4. Changes Table
| File | Change ||------|--------|| `path/to/file` | What changed |
5. Test Plan
-[x] Scripts run without errors: `shellcheck scripts/*.sh`-[x] Manually tested the affected functionality-[x] Skills load correctly in target agent
6. Contributor Checklist
All boxes must be checked:
- Linked an approved issue
- Added exactly one
type:*label - Ran shellcheck on modified scripts
- Skills tested in at least one agent
- Docs updated if behavior changed
- Conventional commit format
- No
Co-Authored-Bytrailers
Automated Checks (all must pass)
| Check | Job name | What it verifies | |
|---|---|---|---|
| PR Validation | Check Issue Reference | Body contains Closes/Fixes/Resolves #N | |
| PR Validation | Check Issue Has status:approved | Linked issue has status:approved | |
| PR Validation | Check PR Has type:* Label | PR has exactly one type:* label | |
| CI | Shellcheck | Shell scripts pass shellcheck |
Conventional Commits
Commit messages MUST match this regex:
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
Format: type(scope): description or type: description
type— required, one of:build,chore,ci,docs,feat,fix,perf,refactor,revert,style,test(scope)— optional, lowercase witha-z0-9._-!— optional, indicates breaking changedescription— required, starts after:
Type-to-label mapping:
| Commit type | PR label | |
|---|---|---|
feat | type:feature | |
fix | type:bug | |
docs | type:docs | |
refactor | type:refactor | |
chore | type:chore | |
style | type:chore | |
perf | type:feature | |
test | type:chore | |
build | type:chore | |
ci | type:chore | |
revert | type:bug | |
feat! / fix! | type:breaking-change |
Examples:
feat(scripts): add Codex support to setup.shfix(skills): correct topic key format in sdd-applydocs(readme): update multi-model configuration guiderefactor(skills): extract shared persistence logicchore(ci): add shellcheck to PR validation workflowperf(scripts): reduce setup.sh execution timestyle(skills): fix markdown formattingtest(scripts): add setup.sh integration testsci(workflows): add branch name validationrevert: undo broken setup changefeat!: redesign skill loading system
Commands
# Create branchgit checkout -b feat/my-feature main# Run shellcheck before pushingshellcheck scripts/*.sh# Push and create PRgit push -u origin feat/my-featuregh pr create --title "feat(scope): description" --body "Closes #N"# Add type label to PRgh pr edit <pr-number> --add-label "type:feature"