agentleFS
mmnto-aimmnto-ai/totem/.claude/skills/postmerge/SKILL.md

postmerge

Skill18 starsChanged 53 days agoApache-2.0View on GitHub

Post-merge workflow — extract lessons and compile rules (manual sequence, wrap is retired)

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the post-merge steps directly instead.

    line 8
  2. Very specific:

    After merging PRs, run the following sequence.

    line 10
  3. Very specific:

    Use as many characters of the hash as needed to unambiguously match one rule.

    line 49
  4. Very specific:

    Do NOT: use git checkout HEAD -- .totem/compiled-rules.json to revert the entire rules file.

    line 58

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

totem wrap is retired pending mmnto-ai/totem#1361 (it silently overwrites hand-crafted committed docs via the totem docs step). Run the post-merge steps directly instead.

After merging PRs, run the following sequence. Replace $ARGUMENTS with the merged PR numbers (space-separated, e.g. 1345 1347 1348).

  1. Extract lessons from the merged PR(s): pnpm exec totem lesson extract $ARGUMENTS --yes
  2. Sync the semantic index (usually already handled by the post-merge git hook, but running it explicitly is cheap and safe): pnpm exec totem sync
  3. Compile new rules locally and export to AI tool configs. Do NOT pass --cloud; the cloud worker is Gemini-only (migration to Claude declined — mmnto-ai/totem#1221, closed not-planned). Local compile routes to the orchestrator.overrides.compile role in totem.config.ts (currently Claude Sonnet 5): pnpm exec totem lesson compile --export
  4. Review the newly compiled rules. Step 3's output prints a count like N/M (100%) ... X compiled, Y skipped, Z failed. For each of the X newly compiled rules, inspect them in .totem/compiled-rules.json and verify:

    • The astGrepPattern or pattern is not over-broad (does it fire on legitimate code the rule is not trying to flag?)
    • The pattern does not reference hallucinated package names, type names, or file paths that do not exist in the repo
    • The lessonHeading accurately describes the rule's behavior

    For any rule that fails these checks, archive it with the atomic totem lesson archive <hash> --reason "<specific failure mode>" command (mmnto-ai/totem#1587). The command flips the rule's status to archived, stamps archivedAt on first transition, refreshes compile-manifest.json's output_hash, and regenerates the copilot and junie exports so the archived rule stops flowing into downstream AI tool configs — all in one invocation.

    pnpm exec totem lesson archive 8dbddb67 --reason "Pattern fires on every throw-in-catch; lesson's real scope is post-scaffold hooks only"

    Use as many characters of the hash as needed to unambiguously match one rule. The command matches on lessonHash prefix; ambiguous prefixes print the candidates and exit non-zero with no mutation. Idempotent on rerun — archivedReason refreshes, archivedAt is preserved. The mmnto-ai/totem#1345 archive filter in loadCompiledRules silences archived rules at lint time while preserving them in the ledger for future compile-worker prompt regression analysis.

    Do NOT use git checkout HEAD -- .totem/compiled-rules.json to revert the entire rules file. Reverting rules while keeping the new lessons on disk creates a manifest inconsistency (manifest.input_hash reflects the new lessons, output_hash reflects the reverted rules, verify-manifest fails on push). This is the symmetric counterpart of the mmnto-ai/totem#1337 bug. Archive-in-place via totem lesson archive is the intended curation surface; reverting is not.

    Empirical baseline: approximately 2 of every 6 auto-compiled rules are bad (1.14.1 postmerge), and the 2026-04-11 PM postmerge hit 4 of 5. The compile-worker prompt rewrite conversation lives under Strategy #73 and Strategy #62. Every archivedReason is feedback that informs that rewrite.

  5. Format everything compile and archive touched: pnpm run format
  6. Stage only the artifacts we keep: new lessons, the mutated rules file, the refreshed manifest, and the regenerated exports. Do NOT stage docs/wiki/roadmap.md or docs/reference/architecture.md unless you hand-edited them deliberately (those are totem docs targets and a postmerge run should not rewrite them): git add .totem/lessons/ .totem/compiled-rules.json .totem/compile-manifest.json .github/copilot-instructions.md .junie/skills/totem-rules/rules.md
  7. Commit: git commit -m "chore: totem postmerge lessons for $ARGUMENTS"
  8. Report: how many lessons extracted, how many rules compiled, how many were archived with totem lesson archive and their reasons, and whether any new tickets were filed for rules that need source- lesson refinement before they can be re-compiled cleanly.

Historical note. Postmerge curation scripts at scripts/archive-bad-postmerge-*.cjs (first introduced on mmnto-ai/totem#1366, last used on mmnto-ai/totem#1625) are retired. Those scripts hand-mutated compiled-rules.json and relied on a subsequent totem lesson compile --export call to refresh the manifest, but that no-op path only detected input-hash drift — not output-hash drift from inline mutations (the exact gap mmnto-ai/totem#1587 closed). totem lesson archive replaces them with one atomic call that handles the mutation + manifest refresh + export regeneration in a single step. The scripts were deleted from HEAD in the 2026-07 repo-surface cleanup (run-and-delete policy, CONTRIBUTING § Repo Tooling Policy); recover them from git history via the PR anchors above if audit archaeology ever needs them.

For an output-hash-only refresh without archiving (e.g., after manual edits to compiled-rules.json for other lifecycle reasons), use pnpm exec totem lesson compile --refresh-manifest — the no-LLM primitive that backs the atomic archive command.

The retirement error from totem wrap prints the same sequence at runtime (without step 4's curation detail), so if you forget the steps, run pnpm exec totem wrap <prs> for the short form.

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.