9 added, 8 removed. Audit A to A.
---
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"
---
# Gentle AI — Branch & PR Skill
## When to Use
Load this skill whenever you need to:
- Create a branch for a new fix or feature
- Open a pull request on [Gentleman-Programming/gentle-ai](https://github.com/Gentleman-Programming/gentle-ai)
- Prepare changes for review
## Critical Rules
1. **Every PR MUST link an approved issue** — `Closes/Fixes/Resolves #<N>` in the PR body, and that issue MUST have `status:approved`. PRs without this are **automatically rejected** by CI.
- 2. **Exactly one `type:*` label** — CI rejects zero or multiple type labels. Route every PR-label mutation 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. `size:exception` additionally requires documented over-budget rationale.
- 3. **400-line review budget** — keep PRs within 400 changed lines (`additions + deletions`) or document the rationale required for a `size:exception` label.
- 4. **Automated checks must pass** — see the Automated Checks table below.
- 5. **No `Co-Authored-By` trailers** — never add AI attribution to commits.
- 6. **No force-push to main/master** — protected branch.
+ 2. **Ordinary `type:*` categorization** — CI rejects zero or multiple type labels. 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.
+ 3. **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.
+ 4. **400-line review budget** — keep PRs within 400 changed lines (`additions + deletions`) or document the rationale required for a `size:exception` label.
+ 5. **Automated checks must pass** — see the Automated Checks table below.
+ 6. **No `Co-Authored-By` trailers** — never add AI attribution to commits.
+ 7. **No force-push to main/master** — protected branch.
## Workflow
```
1. Confirm the issue has status:approved
gh issue view <N> --repo Gentleman-Programming/gentle-ai
2. Create a branch from main using the naming convention below
3. Implement changes following specs and design
4. Run checks locally (format + unit + E2E)
5. Commit using Conventional Commits format
6. Open a PR referencing the issue
→ Declare exactly ONE type:* result in the PR body
→ Use the canonical issue-creation workflow contract before any PR-label mutation
→ Fill in the PR body using the template
7. All automated checks must pass before merge
```
---
## Branch Naming
Branch names **must** match this pattern:
```
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
```
| Type | Example |
|------|---------|
| `feat/` | `feat/user-login` |
| `fix/` | `fix/duplicate-observation-insert` |
| `docs/` | `docs/api-reference-update` |
| `refactor/` | `refactor/extract-query-sanitizer` |
| `chore/` | `chore/bump-bubbletea-v0.26` |
| `style/` | `style/fix-linter-warnings` |
| `perf/` | `perf/optimize-catalog-loading` |
| `test/` | `test/add-pipeline-coverage` |
| `build/` | `build/update-goreleaser-config` |
| `ci/` | `ci/add-e2e-docker-job` |
| `revert/` | `revert/undo-model-picker-change` |
**Rules:**
- All lowercase
- Use hyphens, dots, or underscores as separators (no spaces, no uppercase)
- Description must be short and descriptive
---
## PR Body Format
The PR body must follow the template at `.github/PULL_REQUEST_TEMPLATE.md`. All sections are required unless marked optional.
```markdown
## 🔗 Linked Issue
Closes #<N>
## 🏷️ PR Type
- [ ] `type:bug` — Bug fix (non-breaking change that fixes an issue)
- [ ] `type:feature` — New feature (non-breaking change that adds functionality)
- [ ] `type:docs` — Documentation only
- [ ] `type:refactor` — Code refactoring (no functional changes)
- [ ] `type:chore` — Build, CI, or tooling changes
- [ ] `type:breaking-change` — Breaking change
## 📝 Summary
<!-- Clear description of what this PR does and why. -->
## 📂 Changes
| File / Area | What Changed |
|-------------|-------------|
| `path/to/file` | Brief description |
## 🧪 Test Plan
**Unit Tests**
\`\`\`bash
go test ./...
\`\`\`
**Go Format**
\`\`\`bash
go run ./internal/gofmtcheck
\`\`\`
**E2E Tests** (Docker required)
\`\`\`bash
cd e2e && ./docker-test.sh
\`\`\`
- [ ] Unit tests pass (`go test ./...`)
- [ ] Go format passes (`go run ./internal/gofmtcheck`)
- [ ] E2E tests pass (`cd e2e && ./docker-test.sh`)
- [ ] Manually tested locally
## ✅ Contributor Checklist
- [ ] PR is linked to an issue with `status:approved`
- - [ ] PR stays within 400 changed lines, or the `size:exception` rationale is documented
+ - [ ] PR stays within 400 changed lines, or the `size:exception` rationale and verified policy authority are documented
- [ ] API read-back confirms exactly one appropriate `type:*` label on this PR
- [ ] Unit tests pass (`go test ./...`)
- [ ] E2E tests pass (`cd e2e && ./docker-test.sh`)
- [ ] I have updated documentation if necessary
- [ ] My commits follow Conventional Commits format
- [ ] My commits do not include `Co-Authored-By` trailers
```
---
## Automated Checks
These checks run on every PR and **all must pass** before merge:
| Check | What It Verifies | How to Fix |
|-------|-----------------|------------|
- | **Check PR Cognitive Load** | PR stays within 400 changed lines (`additions + deletions`) or has `size:exception` | Split the PR, or document the `size:exception` rationale before its canonical workflow action |
+ | **Check PR Cognitive Load** | PR stays within 400 changed lines (`additions + deletions`) or has `size:exception` | Split the PR, or document the `size:exception` rationale and verify policy authority before its canonical workflow action |
| **Check Issue Reference** | PR body contains `Closes/Fixes/Resolves #N` | Add `Closes #<N>` to the PR body |
| **Check Issue Has `status:approved`** | Linked issue has the required label | Use the canonical issue-creation workflow contract only when a current direct instruction and target-host capability grant authorize the exact action; otherwise wait |
| **Check PR Has `type:*` Label** | Exactly one `type:*` label is applied to the PR | Use the canonical issue-creation workflow contract only when a current direct instruction and target-host capability authorize the exact action; otherwise wait |
| **Unit Tests** | `go test ./...` passes | Fix failing tests before pushing |
| **Go Format** | `go run ./internal/gofmtcheck` passes | Format malformed Go files before pushing |
| **E2E Tests** | `cd e2e && ./docker-test.sh` passes | Fix failing E2E scenarios before pushing |
---
## Conventional Commits
Commit messages **must** match this pattern:
```
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
```
### Format
```
<type>(<optional-scope>)!: <description>
[optional body]
[optional footer]
```
### Allowed Types
| Type | Purpose | PR Label |
|------|---------|----------|
| `feat` | New feature | `type:feature` |
| `fix` | Bug fix | `type:bug` |
| `docs` | Documentation only | `type:docs` |
| `refactor` | Code change (no behavior change) | `type:refactor` |
| `chore` | Maintenance, dependencies, tooling | `type:chore` |
| `style` | Formatting, linting (no logic change) | `type:chore` |
| `perf` | Performance improvement | `type:feature` |
| `test` | Adding or updating tests | `type:chore` |
| `build` | Build system or external deps | `type:chore` |
| `ci` | CI configuration | `type:chore` |
| `revert` | Reverts a previous commit | matches reverted type |
### Breaking Changes
Add `!` after the type/scope:
```
feat(cli)!: rename --config flag to --config-file
BREAKING CHANGE: the --config flag has been renamed to --config-file.
```
Breaking changes map to `type:breaking-change` label.
### Examples
```
feat(tui): add progress bar to installation steps
fix(agent): correct Claude Code detection on macOS
docs: update contributing guide
chore(deps): bump bubbletea to v0.26
refactor(pipeline): extract step executor
style: fix linter warnings in catalog package
perf(system): cache OS detection result
test(installer): add coverage for catalog step execution
build: update goreleaser config for arm64
ci: split unit and e2e test jobs
revert: undo model picker redesign
feat(cli)!: change default config path
```
---
## Commands
### Setup
```bash
# Confirm issue is approved before starting
gh issue view <N> --repo Gentleman-Programming/gentle-ai
# Create branch
git checkout main && git pull
git checkout -b fix/<short-description>
```
### Testing Locally
```bash
# Unit tests
go test ./...
# Go format
go run ./internal/gofmtcheck
# Unit tests — specific package
go test ./internal/tui/...
# Unit tests — verbose
go test -v ./...
# E2E tests (Docker must be running)
cd e2e && ./docker-test.sh
```
### Open a PR
```bash
gh pr create \
--repo Gentleman-Programming/gentle-ai \
--title "fix(agent): correct Claude Code detection on Linux" \
--body "$(cat <<'EOF'
## 🔗 Linked Issue
Closes #42
## 🏷️ PR Type
- [x] \`type:bug\` — Bug fix (non-breaking change that fixes an issue)
## 📝 Summary
Fixes Claude Code binary detection failing on Linux when HOME is not set.
## 📂 Changes
| File / Area | What Changed |
|-------------|-------------|
| \`internal/agents/claude.go\` | Added HOME env var fallback |
## 🧪 Test Plan
- [x] Unit tests pass (\`go test ./...\`)
- [x] E2E tests pass (\`cd e2e && ./docker-test.sh\`)
- [x] Manually tested locally
## ✅ Contributor Checklist
- [x] PR is linked to an issue with \`status:approved\`
- - [x] PR stays within 400 changed lines, or the \`size:exception\` rationale is documented
+ - [x] PR stays within 400 changed lines, or the \`size:exception\` rationale and verified policy authority are documented
- [x] API read-back confirms exactly one appropriate \`type:*\` label on this PR
- [x] Unit tests pass (\`go test ./...\`)
- [x] E2E tests pass (\`cd e2e && ./docker-test.sh\`)
- [x] I have updated documentation if necessary
- [x] My commits follow Conventional Commits format
- [x] My commits do not include \`Co-Authored-By\` trailers
EOF
)"
```
### Check PR Status
```bash
gh pr checks --repo Gentleman-Programming/gentle-ai <PR-number>
gh pr view --repo Gentleman-Programming/gentle-ai <PR-number>
```