JinDaGe - engram-branch-pr Skill Details

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

Every PR MUST link an approved issue — no exceptions
Every PR MUST have exactly one type:* label
All required automated checks must pass before merge is possible
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.

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

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"