Skill: New Branch Bootstrap

Description

Canonical recipe for spinning up a fresh working branch off the latest upstream main. Use this skill whenever the user says things like "make a new branch off fetched origin/main", "peel off a fresh branch", "dust off #NNNN", or otherwise signals the start of a new unit of work.

When to Use

Starting any new feature, fix, chore, or refactor.
Rebasing a stale PR onto current main (see Rebase variant).
Reproducing a CI failure from a clean baseline.

Preconditions (verify before branching)

Clean worktree. If git status --porcelain is non-empty, ask the user before proceeding.
Upstream remote known. Find the remote in git remote -v that points at meshtastic/Meshtastic-Android: upstream in a fork clone, origin in a direct clone. The recipes below call it upstream; substitute its real name.
Secrets: nothing to bootstrap — secrets.defaults.properties is tracked and is the secrets plugin's fallback, so every flavor builds without a local secrets file.

Standard Recipe

# 1. Fetch latest upstream
git fetch upstream --prune --tags

# 2. Create the branch from upstream/main (never from a local stale main)
git switch -c <branch-name> upstream/main

# 3. Sanity check
git --no-pager log -1 --oneline

Branch Naming

Use conventional-commit style prefixes. .specify/memory/constitution.md (Branch naming) is the canonical list of prefixes; AGENTS.md remains authoritative for rules, architecture and workflow. CONTRIBUTING.md → Pull Requests carries the same set contributor-facing:

Prefix	Use for
`feat/<scope>`	New user-visible behavior
`fix/<scope>`	Bug fixes
`refactor/<scope>`	Code structure changes, no behavior change
`chore/<scope>`	Tooling, deps, CI, cleanup
`docs/<scope>`	Documentation only
`build/<scope>`	Build system changes
`ci/<scope>`	CI workflow changes
`test/<scope>`	Test additions or fixes
`deps/<scope>`	Dependency updates

Spec-driven work is the exception and takes no prefix from that table: a numeric spec prefix (005-tak-v2-protocol) or the timestamp form YYYYMMDD-HHMMSS-feature-name that /speckit.git.feature creates. Both are valid — don't reject one.

release/* and automation/* are reserved for maintainers and automated workflows.

Keep the slug short and kebab-case, e.g. fix/r8-animation-release, chore/koin-application-migration.

Rebase Variant

When the user says "rebase #NNNN" or "dust off PR NNNN":

git fetch upstream --prune
gh pr checkout <NNNN>          # checks out the PR head locally
git branch --show-current      # confirm this is the PR you meant, before any push
git rebase upstream/main
# Resolve conflicts, then:
git push --force-with-lease

Never use plain --force. Always --force-with-lease to avoid clobbering collaborator pushes.

Read that branch name before you push. A mistyped <NNNN> is a valid PR number belonging to someone else, and --force-with-lease will not save you: it only refuses when the remote ref moved after you fetched it, which is exactly not the case here. The lease is intact and the wrong branch gets rewritten.

Post-Branch Checklist

Branch name carries a conventional prefix, or is a spec-driven name (numeric or YYYYMMDD-HHMMSS-) per Branch Naming above.
ANDROID_HOME exported (see the bootstrap in .skills/project-overview/SKILL.md).
Optional: run ./gradlew assembleDebug once to catch environment regressions before editing.

Tip: Delegate Long Audits to a Subagent

If the user's opening prompt is a sweeping audit or investigation (e.g. "audit changes since v2.7.13 for regressions", "investigate why animations are broken on release"), dispatch the Explore subagent (read-only, broad fan-out) so file dumps stay out of the main context and you get back just the conclusion; use the gradle-runner subagent for heavy ./gradlew runs. See CLAUDE.md → "Delegate to keep context lean".

new-branch