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. 5 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. Run tests locally (unit + e2e)
5. Open PR using the template
6. Add exactly one type:* label
7. Wait for 5 automated checks to pass

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._-]+$

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:

3. Summary

1-3 bullet points of what the PR does.

4. Changes Table

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

5. Test Plan

- [x] Unit tests pass locally: `go test ./...`
- [x] E2E tests pass locally: `go test -tags e2e ./internal/server/...`
- [x] Manually tested the affected functionality

6. Contributor Checklist

All boxes must be checked:

• Linked an approved issue
• Added exactly one type:* label
• Ran unit tests locally
• Ran e2e tests locally
• Docs updated if behavior changed
• Conventional commit format
• No Co-Authored-By trailers

Automated Checks (all 5 must pass)

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

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

# Run tests before pushing
go test ./...                                    # unit tests
go test -tags e2e ./internal/server/...          # e2e tests

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