branch-pr

Files (1)

• SKILL.md

SKILL.md (first lines)

## 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

1. **Every PR MUST link an approved issue** — no exceptions
2. **Every PR MUST have exactly one `type:*` label**
3. **Automated checks must pass** before merge is possible
4. **Blank PRs without issue linkage will be blocked** by GitHub Actions
5. **Hard-gates are fail-fast**: if any preflight gate fails, DO NOT create or update the PR

---

## Preflight Hard Gates (Blocking)

Run these gates in order. On first failure: stop immediately and return a blocking error.

### Standard Blocking Error Format

```text
PR_BLOCKED: <gate> | fix: <action>
```

### Gate 1 — Template Contract (mandatory)

- The PR body MUST be built from repo template `pull_request_template.md` **exactly**.
- If the template file is missing, sections are removed, or required sections are left incomplete/empty, block PR creation/update.

Fail examples:
- `PR_BLOCKED: template_missing | fix: create repo file pull_request_template.md and re-run preflight`
- `PR_BLOCKED: template_incomplete | fix: complete all required sections from pull_request_template.md without deleting headings`

### Gate 2 — Language Contract (mandatory)

- For this user, PR body text MUST be es-AR (rioplatense, voseo natural).
- If body is in another language or neutralized style, block.

Fail example:
- `PR_BLOCKED: language_mismatch | fix: rewrite PR body in es-AR rioplatense using the template sections`

### Gate 3 — Branch Scope + Naming Contract (mandatory)

- Source branch MUST match naming policy regex and active change scope.
- Reusing legacy/unrelated branches is forbidden.
- If branch scope does not align with the current approved issue/change, block.

Fail examples:
- `PR_BLOCKED: branch_name_invalid | fix: create a new branch using type/description naming policy`
- `PR_BLOCKED: branch_scope_mismatch | fix: create a fresh branch tied to the active change scope and cherry-pick relevant commits`

### Gate 4 — Fail-Fast Execution Rule

- If **any** gate fails: stop preflight and do NOT run `gh pr create` or `gh pr edit`.
- Only proceed to PR commands when all gates pass.

### Policy Parity Note

- These gates are policy-level and apply equally to GitHub and Azure DevOps.
- Tooling differs (`gh` vs `az repos pr`), enforcement does not.

---

## Workflow

```
1. Verify issue has `status:approved` label
2. Create branch: type/description (see Branch Naming below)
3. Implement changes with conventional commits
4. Run shellcheck on modified scripts
5. Open PR using the template
6. Add exactly one type:* label
7. 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 body MUST come from repository template `pull_request_template.md` exactly (same sections, complete content). Every PR body MUST contain:

### 1. Linked Issue (REQUIRED)

```markdown
Closes #<issue-number>
```

Valid keywords: `Closes #N`, `Fixes #N`, `Resolves #N` (case insensitive).

From ntimpano/guild, Apache-2.0.

More from ntimpano/guild