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. **Issue linkage is optional**. If a PR links an issue, verify it is relevant and approved; never fabricate or self-approve an issue.
2. **Every PR MUST have exactly one `type:*` label**
3. **Automated checks must pass** before merge is possible
4. **PRs MUST describe scope and validation**, whether or not an issue is linked.
5. **No model/tool attribution** in the PR title, body, or comments — never include
   `Generated with`, a 🤖 footer, or any mention of Claude, Claude Code, Anthropic,
   GPT, OpenAI, Codex, Copilot, Gemini, or any other model/vendor. See
   `rules/no-model-attribution.instructions.md`.
6. **Feature branch MUST be created before any project file is edited** — run `git checkout -b <tipo>/<descripción> main` as Step 0 before writing any code.
7. **NEVER edit files or commit directly on the default branch (`main`)** — all changes require a feature branch and PR.

---

## Workflow

```
0. Crear una rama de feature: git checkout -b <tipo>/<descripción> main
1. If an issue is linked, verify it has the `status:approved` label; otherwise continue without issue linkage
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
```

---

## Multi-Developer Collaboration

The project's branching decides how many PRs may be in flight. Read it from
`ospec team` (or the `delivery` of `ospec next`): `branching`, its `reasons`
and its rules in `how`. Without a declaration the recommendation is `serial`.

- **Branching policy**: `serial` keeps one PR in flight, so the open PR is merged (and released, when the project cuts a release per change) before a new branch; `parallel` allows several branches, each integrating the default branch before its merge and editing version and changelog last.
- **Branch hygiene**: one branch per task, named `<type>/<description>`; delete it after the merge.
- **Default-branch protection**: NEVER edit files or commit directly on `main`; all work goes through feature branches and PRs.
- **Sync coordination**: pull the default branch before branching. Rebase only a branch that was never pushed; once pushed, integrate the default branch with `git merge`, since the hooks deny force-pushing.
- **Parallel work**: each developer works on a dedicated branch; integrate only via PR review, never direct push.
- **Commit conventions**: use Conventional Commits with Spanish imperative verbs; keep commits atomic and buildable.

---

## 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 (OPTIONAL)

Include `Closes #<issue-number>`, `Fixes #<issue-number>`, or
`Resolves #<issue-number>` only when a relevant approved issue exists.
Otherwise omit issue linkage; do not invent an issue or approval.

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

```markdown
| File | Change |
|------|--------|
| `path/to/file` | What changed |
```

### 5. Test Plan

```markdown
- [x] Scripts run without errors: `shellcheck scripts/*.sh`

From Snakeblack/ospec-workflow, Apache-2.0.

More from Snakeblack/ospec-workflow