engram-branch-pr

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. All required automated checks must pass before merge is possible
4. Blank PRs without issue linkage will be blocked by GitHub Actions

---

Workflow

1. Verify issue has `status:approved` label
2. Create branch: 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. Open PR using the template
7. Add exactly one type:* label
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

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

- [ ] Focused regression (behavior change): `<actual command>` — `<actual outcome or N/A: documentation-only>`
- [ ] Affected package (behavior change): `<actual command>` — `<actual outcome or N/A: documentation-only>`
- [ ] GitHub CI full unit/E2E/lint and applicable platform checks — pending until they run

Replace example commands and outcomes with actual evidence. For docs-only changes, record N/A — documentation-only; no Go behavior changed for local Go tests 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 and identify any missing CI evidence.

6. Contributor Checklist

All boxes must be checked:

• Linked an approved issue
• Added exactly one type:* label
• Recorded actual focused regression and affected package test commands/outcomes for behavior changes, or N/A for docs-only changes
• Ran additional applicable local checks without a PR or for high-risk changes; identified missing CI evidence
• Docs updated if behavior changed
• Conventional commit format
• No Co-Authored-By trailers
• Every changed path complies with the Transient Artifact Policy

---

Automated Checks

The six required contexts are listed in CONTRIBUTING.md; 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	Linked issue has status:approved
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
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

Type	Purpose	PR label
feat	New feature	type:feature
fix	Bug fix	type:bug
docs	Documentation only	type:docs
refactor	Code refactoring	type:refactor
chore	Maintenance, deps	type:chore
style	Formatting, whitespace	type:chore
perf	Performance improvement	type:refactor
test	Adding/fixing tests	type:chore
build	Build system changes	type:chore
ci	CI/CD changes	type:chore
revert	Revert previous commit	(match original type)
feat! / fix!	Breaking change	type:breaking-change

Rules

• Type MUST be one of the listed values
• Scope is optional, lowercase, allows a-z, 0-9, ., _, -
• ! before : marks a breaking change
• Description MUST start after : (colon + space)

Examples

feat(cli): add --json flag to session list command
fix(store): prevent duplicate observation insert on retry
docs(contributing): update workflow documentation
refactor(internal): extract search query sanitizer
chore(deps): bump github.com/charmbracelet/bubbletea to v0.26
style(tui): fix alignment in session detail view
perf(store): optimize FTS5 query for large datasets
test(sync): add coverage for conflict resolution
ci(workflows): split e2e into separate job
fix!: change session ID format

Invalid examples (will be rejected)

Fix bug                          ← no type prefix
feat: Add login                  ← description should be lowercase
FEAT(cli): add flag              ← type must be lowercase
feat (cli): add flag             ← no space before scope
feat(CLI): add flag              ← scope must be lowercase
update docs                      ← no conventional commit format

---

Commands

# Create branch
git checkout -b feat/my-feature main

# For behavior changes, run actual focused regression and affected package commands:
# go test ./internal/store -run '<actual regression test name>'
# go test ./internal/store
# Record actual commands and outcomes in the PR test plan.
# For docs-only changes, record N/A for Go tests and the documentation checks run.
# Without a PR or for high-risk changes, run additional applicable local checks.
# After pushing, GitHub CI runs broad unit/E2E/lint and applicable platform checks;
# do not claim their results until the checks actually pass.

# Push and create PR
git push -u origin feat/my-feature
gh pr create --title "feat(scope): description" --body "Closes #N"

# Add type label to PR
gh pr edit <pr-number> --add-label "type:feature"