Naming Conventions

August 7, 2026 · View on GitHub

This spec documents the five naming conventions used across the Fab workflow. Each entry includes the pattern, an example, and where the convention is encoded.

Change Folder Name

The primary identity for a change within Fab.

Field	Value
Pattern	`{YYMMDD}-{XXXX}-{slug}`
Example	`260226-jq7a-slim-config-decouple-naming`
Encoded in	`fab change new` (Go binary)

Components:

YYMMDD — date (generated by fab change new, always today)
XXXX — 4 random lowercase alphanumeric chars (uniqueness guarantee)
slug — 2-6 word kebab-case description (caller-provided via --slug)

The {YYMMDD}-{XXXX} prefix is immutable. Only the slug can be changed via fab change rename.

Git Branch

The branch name used for git isolation during development.

Field	Value
Pattern	`{change-folder-name}`
Example	`260226-jq7a-slim-config-decouple-naming`
Encoded in	`/git-branch` skill (`src/kit/skills/git-branch.md`)

The branch name equals the change folder name directly. No prefix is applied. For standalone branches (no matching change), the raw argument is used as-is.

Worktree

The directory name for filesystem-isolated worktrees.

Field	Value
Pattern	`{adjective}-{noun}`
Example	`swift-fox`
Encoded in	`wt create` (`src/go/ binary wt`)

Random adjective-noun combo from predefined word lists. Can be overridden with --worktree-name. Worktrees are created at $(dirname {repo_root})/{repo_name}.worktrees/.

PR Title

The title used when creating GitHub pull requests.

Field	Value
Pattern	`{type}: {title}` (or `{type}: {issues} {title}` when issues exist)
Example	`feat: DEV-123 DEV-456 Add OAuth support` or `fix: Resolve concurrent access bug`
Encoded in	`/git-pr` skill (`src/kit/skills/git-pr.md`)

Type is inferred from intake keywords or diff analysis: feat, fix, refactor, docs, test, ci, chore. Issue IDs (from fab status get-issues) are included space-joined when non-empty — this enables Linear auto-linking. Title is derived from the intake heading or the last commit message.

Backlog Entry

The format for items in the local backlog (fab/backlog.md).

Field	Value
Pattern	`- [ ] [{ID}] [{issue_ids}] (BUG) {YYYY-MM-DD}: {description}` (issue IDs and the `(BUG)` marker are both optional)
Example	`- [ ] [ni3o] [DEV-1011] 2026-02-12: Capture more metrics`, `- [ ] [ngaw] 2026-02-23: Quality gate`, or `- [ ] [k4tp] (BUG) 2026-03-04: Archive drops the pointer symlink`
Encoded in	`idea` command (`src/go/ binary idea` — backlog management); parsed by `src/go/fab/internal/backlog`

Components:

[{ID}] — 4-char alphanumeric backlog ID
[{issue_ids}] — optional Linear issue ID(s) in brackets (e.g., [DEV-1011])
(BUG) — optional bug marker, placed between the issue IDs and the date
{YYYY-MM-DD} — ISO date when item was added
{description} — free-form description, may include tags