agentleFS
pigweed-projectpigweed-project/pigweed/.agents/skills/freshen/SKILL.md

freshen

Skill566 starsChanged 14 days agoApache-2.0View on GitHub

Safely rebase or fast-forward the active Pigweed worktree onto its target branch (origin/main), resolve Pigweed dual-build and code conflicts, preserve Gerrit Change-Id footers, and verify local build/format health.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 2 are distinctive, and 11 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use /freshen standalone whenever a worktree or CL is behind origin/main, or invoke it as the first stage of /crank.

    line 17
  2. Very specific:

    Record a rollback anchor first: Before any mutating Git command, capture PRE_FRESHEN_SHA=$(git rev-parse HEAD) and log it.

    line 24
  3. Very specific:

    Never clobber Change-Id: footers: Every rebased or amended commit MUST retain its exact original Change-Id: I...

    line 28
  4. Very specific:

    Respect target branch memory: Do not blindly rebase onto origin/main if the CL targets a feature or release branch (e.g., sandbox/*).

    line 31
  5. Very specific:

    Stay inside the active checkout: Do not create ad-hoc temporary checkouts or git worktree directories just to rebase—doing so invalidates …

    line 34
  6. Very specific:

    Run ./gh sense (or inspect its output if already called by /crank) and record a rollback anchor before any mutating Git command:

    line 44
  7. Very specific:

    If git rebase <UPSTREAM> stops with conflicts, inspect every conflicted file (git diff --name-only --diff-filter=U) and resolve using …

    line 76
  8. Very specific:

    Keep upstream (origin/main) version bumps and pin updates, then re-apply only the specific dependency additions introduced by the local …

    line 87
  9. Distinctive:

    Before editing conflicted code, inspect how upstream changed the file:

    line 90
  10. Very specific:

    Verify with git log -1 --format=%B HEAD that the original Change-Id: footer is intact.

    line 103
  11. Distinctive:

    If upstream deleted the target module or replaced the subsystem architecture such that a mechanical/semantic rebase would require a …

    line 107
  12. Very specific:

    Verify git rev-parse HEAD equals PRE_FRESHEN_SHA.

    line 110
  13. Very specific:

    Run ./pw format (or ./pw format --fix).

    line 120

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Freshen Worktree & Rebase (/freshen)

/freshen brings the current Pigweed worktree and branch up to date with its upstream target branch (defaulting to origin/main) without losing warm Bazel caches, clobbering Gerrit Change-Id: footers, or silently breaking dual-build (BUILD.bazel / BUILD.gn / CMakeLists.txt) parity.

Use /freshen standalone whenever a worktree or CL is behind origin/main, or invoke it as the first stage of /crank.


Strict Invariants

  1. Record a rollback anchor first: Before any mutating Git command, capture PRE_FRESHEN_SHA=$(git rev-parse HEAD) and log it. If an irreconcilable conflict occurs, abort (git rebase --abort) and verify HEAD matches PRE_FRESHEN_SHA.
  2. Never clobber Change-Id: footers: Every rebased or amended commit MUST retain its exact original Change-Id: I... line so Gerrit links new patchsets to the existing Change List (CL).
  3. Respect target branch memory: Do not blindly rebase onto origin/main if the CL targets a feature or release branch (e.g., sandbox/*). Query ./gh pr view --json branch first when a CL exists.
  4. Stay inside the active checkout: Do not create ad-hoc temporary checkouts or git worktree directories just to rebase—doing so invalidates the local Bazel output_base.

Step-by-Step Workflow

Step 1: Sense Branch, Dirty State & Rebase Verdict

Run ./gh sense (or inspect its output if already called by /crank) and record a rollback anchor before any mutating Git command:

PRE_FRESHEN_SHA=$(git rev-parse HEAD)
echo "PRE_FRESHEN_SHA=${PRE_FRESHEN_SHA}"
./gh sense

./gh sense computes an in-memory 3-way merge check (git merge-tree --write-tree HEAD origin/main) and outputs a Rebase: verdict:

  • REBASE_SKIP_KEEP_CQ: The branch merges cleanly with origin/main in memory, has zero unresolved comments/drafts, and already has active/passing CQ+1 tryjobs. Skip rebasing unless the user explicitly requested a standalone /freshen—uploading a trivial rebased patchset would reset active CQ tryjobs for zero benefit!
  • REBASE_CONFLICT or REBASE_RECOMMENDED: Proceed to Step 2 (git fetch origin
    • rebase onto origin/<target_branch>).

Step 2: Select the Freshen Mode

Choose the appropriate mode based on local state:

Local StateModeExact Action
Clean & Merged / Synced (ahead == 0 or CL state == "MERGED", clean tree)Fast-Forward / NextIf preparing the checkout for a specific new bug or CL, run ./gh sense --prepare [<target>]. If simply fast-forwarding onto origin/main, run git fetch origin && git merge --ff-only origin/main (or ./gh wt next if using ./gh wt).
Dirty Working Tree (git status --porcelain non-empty)Autostash + RebaseStash tracked and untracked changes before rebasing: git stash push -u -m "freshen-autostash-${PRE_FRESHEN_SHA}", run git fetch origin && git rebase <UPSTREAM>, then git stash pop and resolve any stash overlap.
Unmerged Local Commit(s) / Active CL (ahead > 0, CL state == "NEW" or unuploaded)Target-Aware RebaseRun git fetch origin && git rebase <UPSTREAM>.
Already Mid-Rebase / Mid-Merge (.git/rebase-merge or MERGE_HEAD exists)Conflict RecoveryInspect conflicted files (git diff --name-only --diff-filter=U) and proceed directly to Step 3.

Step 3: Pigweed-Aware Conflict Resolution

If git rebase <UPSTREAM> stops with conflicts, inspect every conflicted file (git diff --name-only --diff-filter=U) and resolve using Pigweed domain rules:

  1. Build File Conflicts (BUILD.bazel, BUILD.gn, CMakeLists.txt):
    • Never blindly pick --ours or --theirs when both upstream and the local commit added targets, srcs, hdrs, or deps.
    • Combine both additions, keep lists (srcs, hdrs, deps, public) sorted alphabetically, and ensure any new source/header added in BUILD.bazel is identically reflected in BUILD.gn (and CMakeLists.txt if present in that module).
  2. MODULE.bazel / MODULE.bazel.lock / CIPD Tool Rolls:
    • Keep upstream (origin/main) version bumps and pin updates, then re-apply only the specific dependency additions introduced by the local commit.
  3. C++ / Rust / Python Header or API Refactorings:
    • Before editing conflicted code, inspect how upstream changed the file:
      git log -n 5 -p <UPSTREAM> -- <conflicted_file>
    • Adapt the local change to the new upstream API (e.g., updated pw::Result signatures, pw_async2 dispatcher changes, renamed headers) while honoring Pigweed style (C++17 compatibility, no dynamic allocation in core modules, #pragma once).
  4. Commit Continuity & Change-Id: Preservation:
    • Stage resolved files (git add <files>) and run:
      GIT_EDITOR=true git rebase --continue
    • Verify with git log -1 --format=%B HEAD that the original Change-Id: footer is intact.

Escape Hatch for Irreconcilable Conflicts

If upstream deleted the target module or replaced the subsystem architecture such that a mechanical/semantic rebase would require a ground-up redesign:

  1. Run git rebase --abort.
  2. Verify git rev-parse HEAD equals PRE_FRESHEN_SHA.
  3. Report the exact upstream commit (git log -1 <UPSTREAM> -- <path>) that superseded or conflicted with the change so /crank or the user can decide whether to abandon or re-architect.

Step 4: Post-Freshen Verification

Whenever commits were rebased (ahead > 0 after rebase):

  1. Format Check: Run ./pw format (or ./pw format --fix). If formatting modified any files in a single-commit CL, fold them into HEAD without touching the commit message:
    git add -u && git commit --amend --no-edit
  2. Targeted Build & Test: Identify the affected Pigweed module(s) from git diff --name-only <UPSTREAM>...HEAD and run hermetic Bazel tests:
    bazelisk test --noshow_progress --noshow_loading_progress //<module>/...
  3. Structured Summary: Report:
    • Previous vs. new HEAD SHA and number of upstream commits integrated.
    • Conflicts resolved (if any) and how they were resolved.
    • Verification status (./pw format and bazelisk test results).
    • Note that the rebased commit has not been pushed yet (unless invoked inside /crank, which handles pushing in its CI loop).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.