Disciplined Worktree Promotion

Disciplined Worktree Promotion

Use this skill to keep exploratory work disposable, promotion decisions evidence-based, and the accepted baseline branch clean.

Use using-git-worktrees for worktree creation and detection. This skill governs what to keep, what to discard, and when a change has earned promotion.

Operating posture

• Start from the accepted baseline branch, not automatically the repository default branch.
• Keep one work item per worktree or short-lived branch.
• Treat exploratory edits, benchmark spikes, and risky ideas as disposable until they earn promotion.
• Keep the baseline branch clean. Promote only deltas that survive review, tests, and proof runs.
• Prefer a narrow, understandable change over a broad rewrite.

Core rules

1. Inspect before adding

   • Read the existing implementation and prior notes first.
   • Look for simplification, deletion, or a tighter use of current code before inventing new structure.

2. Reduce or fix code first

   • Prefer removing code, narrowing code paths, or reusing the current structure over introducing new moving parts.
   • If a problem can be solved by deleting redundant logic, collapsing a branch, tightening a condition, or clarifying ownership, do that first.

3. New helpers are a last resort

   • Do not add helpers, abstractions, wrappers, coordinators, or new layers by default.
   • Only introduce a helper when the existing code cannot be kept clear and duplication is both real and worth preserving.
   • If you add a helper, explain why in concrete terms and keep it tightly scoped.

4. Keep phases small and promotable

   • Prefer one meaningful concern per branch or phase.
   • If several ideas exist, split them into separate experiments so each one can be kept or discarded independently.
   • Avoid bundling speculative performance work with correctness fixes unless they are inseparable.

5. Do not carry work with stash or hidden state

   • Do not use stash as a handoff mechanism between experiments.
   • If a delta is worth keeping, prove it and promote it.
   • If it is not worth keeping, discard the worktree or branch.

6. Use swarms for challenge, not for noise

   • Use subagents or swarms to challenge assumptions, inspect code from fresh angles, or run independent health checks.
   • Do not use them to create churn or duplicate local investigation.
   • Summarize conclusions as keep, discard, defer, or needs-human-judgment.

7. Evidence beats plausibility

   • Do not keep a change because it sounds faster or cleaner.
   • Run the focused tests for the touched area.
   • Run the repository validation that already exists.
   • When a change affects live service paths, run the smallest real-target proof that can disconfirm the change.
   • If the change only touches a narrow tagged or selectable slice, use that same narrow slice for the cloud or hosted proof first.
   • Widen from targeted cloud proof to broader proof only when the narrow proof is ambiguous, shared infrastructure changed, or the benchmark comparison is not trustworthy.
   • For reliability or performance work, compare against the accepted benchmark and judge results in this order:
     1. correctness and completeness
     2. warnings and failure behavior
     3. memory impact
     4. wall-clock time

8. Keep or discard decisively

   • Keep a change only if the net result is clearly worth the complexity.
   • Discard experiments that introduce correctness ambiguity, regress memory materially, or add design weight without durable payoff.
   • Record future ideas instead of forcing them into the current branch.

9. Promotion workflow

   • Do exploratory work on isolated branches or sessions.
   • When a delta proves itself, replay or preserve only the kept change on a clean baseline-derived branch.
   • Re-run the relevant proof on the promoted branch, not only on the experimental branch.
   • Do not drag discarded experiments, noisy commits, or convenience hacks into the promoted branch.

10. PR hygiene

• Explain the final kept changes in plain language.
• Fix CI at the root cause; never bypass shared tooling just to get green.
• Treat review threads as unfinished until you have replied and resolved them.
• Keep the branch merge-ready, but do not merge unless explicitly asked.

11. Archive aggressively
    • Once an exploratory branch has been promoted or discarded, it is safe to archive its worktree and conversation.

• Keep only the active promotion context and anything still needed to complete the current review.

Promotion ledger

For each work item, record:

• baseline branch name and baseline commit
• worktree or branch name
• concise hypothesis
• focused local validation commands
• targeted cloud or hosted proof command and selected tests or tags
• benchmark used for correctness, memory, and time comparison
• keep, discard, or defer decision

If work spans more than one repository, package, or deployable unit, record every relevant baseline SHA or version and the exact artifact or bundle used for proof.