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

The [contribution policy transition](../../docs/contribution-policy-transition.md) is **PRE-CUTOVER / NOT ACTIVE**; the active rules below still apply.

1. **Every PR MUST link an approved issue** — no exceptions
2. **Every PR MUST have exactly one `type:*` label**
3. **All required automated checks must pass** before merge is possible
4. **Blank PRs without issue linkage will be blocked** by GitHub Actions
5. **The PR targets the canonical repository, the branch lives in your fork** — `origin` is your fork, `upstream` is the canonical repository. A push straight to the canonical repository is refused, either by permissions or by the ruleset with `GH013`; do not retry it or switch destinations silently
6. **Applying the `type:*` label needs maintainer triage access** on the canonical repository. When the API refuses, ask a maintainer instead of retrying

---

## Workflow

```
1. Verify every linked issue has `status:approved`, a real assignee, and the proportional evidence defined in CONTRIBUTING.md; the PR author need not match the assignee
2. Create branch from the canonical `main` (`upstream/main`), with `origin` pointing at your fork: feat/*, fix/*, docs/*, refactor/*, chore/*
3. Implement changes
4. For behavior changes, run a focused regression test and affected package tests locally; record commands and outcomes. For docs-only changes, record N/A for Go tests and verify the documentation.
5. Check every changed path against the [Transient Artifact Policy](../../CONTRIBUTING.md#transient-artifact-policy)
6. Push the branch to your fork, then open the PR against the canonical repository using the template
7. Add exactly one type:* label — this needs a maintainer with triage access on the canonical repository, so ask for it rather than retrying
8. After pushing/opening the PR, wait for GitHub CI's full unit/E2E/lint and applicable platform checks; report results only after they run
```

---

## Branch Naming (enforced by GitHub ruleset)

Branch names are validated by a GitHub ruleset. Pushes that don't match **will be rejected**.

**Pattern:** `^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$`

| Type | Branch pattern | Example |
|------|---------------|---------|
| Feature | `feat/<description>` | `feat/json-export-command` |
| Bug fix | `fix/<description>` | `fix/duplicate-observation-insert` |
| Chore | `chore/<description>` | `chore/bump-bubbletea-v0.26` |
| Docs | `docs/<description>` | `docs/api-reference-update` |
| Style | `style/<description>` | `style/fix-tui-alignment` |
| Refactor | `refactor/<description>` | `refactor/extract-query-sanitizer` |
| Performance | `perf/<description>` | `perf/optimize-fts5-queries` |
| Test | `test/<description>` | `test/add-sync-coverage` |
| Build | `build/<description>` | `build/update-go-toolchain` |
| CI | `ci/<description>` | `ci/split-e2e-job` |
| Revert | `revert/<description>` | `revert/broken-migration` |

**Rules:**
- Description MUST be lowercase
- Only `a-z`, `0-9`, `.`, `_`, `-` allowed in description
- No uppercase, no spaces, no special characters

---

## PR Body Format

Use the [canonical PR template](../../.github/PULL_REQUEST_TEMPLATE.md) as the source for body shape; do not duplicate its structure here. Describe the problem and result, record honest verification, and include risks and mitigations only when applicable.

Every PR body MUST contain a closing reference to an approved, assigned issue:

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

Valid keywords: `Closes #N`, `Fixes #N`, `Resolves #N` (case insensitive).
Every linked issue MUST have `status:approved` and a real assignee. Approval means a maintainer accepted proportional evidence: scope/checks for trivial changes; current-remote-main SHA, reproduction, root cause, and regression tests for bugs; approved design, non-goals, and independent review for high-risk changes. Evidence can live in the issue; no separate design document is required by default.

Existing PRs must comply before merge, without waiting for backlog-wide migration. Re-run native validation after issue approval/assignment changes; do not rely on stale green checks.

Add exactly one canonical `type:*` PR label; no duplicate type checkbox is required in the body. All required automated checks must pass before merge; report other applicable checks honestly as described below.

Record actual verification commands/steps and observed outcomes, not assumed passes. For behavior changes, include focused regression and affected package tests. For docs-only changes, mark local Go tests `N/A — documentation-only; no Go behavior changed` and list the documentation checks actually run. Targeted coverage can help find missed branches; no total module coverage or per-PR numeric gate applies. Without a PR (or before pushing), and for high-risk changes, run additional applicable local checks. Identify checks not run and missing CI evidence; GitHub CI full unit/E2E/lint and applicable platform results remain pending until they run. Local success is not a hosted CI pass.

For high-risk changes, link the approved design, non-goals, and independent review evidence required by [CONTRIBUTING](../../CONTRIBUTING.md). Omit the risk section for low-risk changes.

---

## Automated Checks

The six required contexts are listed in [CONTRIBUTING.md](../../CONTRIBUTING.md#step-4-automated-pr-checks); all six must pass before merge. Lint, transient-artifact checks, `Windows Setup Test`, and `Cloud Sync Wrapper Tests (Windows)` run for PRs but not merge groups, and are not among the six required contexts. Report their actual outcomes without treating pending checks as passed.

| Check | Job name | What it verifies |
|-------|----------|-----------------|
| PR Validation | `Check Issue Reference` | Body contains `Closes/Fixes/Resolves #N` |
| PR Validation | `Check Issue Has status:approved` | Every linked issue is approved and assigned |
| PR Label Policy | `Check PR Has type:* Label` | PR has exactly one `type:*` label |
| Transient Artifact Check | `Check PR Has No Transient Artifacts` | PR files comply with the [Transient Artifact Policy](../../CONTRIBUTING.md#transient-artifact-policy) |
| CI | `Unit Tests` | `go test ./...` passes |
| CI | `E2E Tests` | `go test -tags e2e ./internal/server/...` passes |
| CI | `Plugin Tests` | `npm test` passes in `plugin/pi` |
| CI | `Lint` | golangci-lint reports no new findings in Go changes |
| CI | `Windows Setup Test` | Windows setup preserves absolute paths and MCP job-object parent-lifetime tests pass |
| CI | `Cloud Sync Wrapper Tests (Windows)` | Cloud sync wrapper and missing-PowerShell-Engram tests pass on Windows |

---

## Conventional Commits (enforced by GitHub ruleset)

Commit messages are validated by a GitHub ruleset. Commits that don't match **will be rejected**.

**Pattern:** `^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+`

**Format:**
```
<type>(<optional-scope>): <description>
<type>(<optional-scope>)!: <description>   ← breaking change
```

### Allowed types

From Gentleman-Programming/engram, Apache-2.0.

More from Gentleman-Programming/engram