agentleFS
anthony-chaudharyanthony-chaudhary/fak/.agents/skills/clear-out-wip/SKILL.md

clear-out-wip

Skill49 starsChanged 14 days agoApache-2.0View on GitHub

Clear backed-up local repository work without sweeping up peers - inventory the dirty tree, remove proven generated junk, prioritize coherent slices, ship green partial/enabling work honestly, park or issue the rest, and use stale-work/fleet workflows only after ownership and path contracts are explicit. Use when the operator says "clear out local WIP", "clean up the dirty tree", "get this backlog of changes shipped", "sort out uncommitted work", or asks what can be committed even though the larger feature is not.

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. About 0 are common, 12 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Treat the shared checkout as peer-dirty.

    line 26
  2. Very specific:

    If MERGE_HEAD exists and the merge is not yours, do not finish or abort it.

    line 29
  3. Very specific:

    Never add a .gitignore rule merely to make an unknown path disappear.

    line 36
  4. Distinctive:

    Never ship broken default builds, secrets, generated binaries, private run fuel, misleading claims, or half of a cross-file symbol …

    line 39
  5. Distinctive:

    Do not close a parent issue merely because an independently useful enabling slice shipped.

    line 42
  6. Distinctive:

    Before any mutation, run:

    line 47
  7. Very specific:

    Keep the returned operation_id.

    line 53
  8. Distinctive:

    Run the inventory before editing anything.

    line 57
  9. Very specific:

    If clearing WIP that crosses shared boundaries into companion repository fak-private, run the dual-repo census:

    line 68
  10. Very specific:

    If either checkout has an active MERGE_HEAD, halt and wait for merge quiescence before proceeding.

    line 77
  11. Very specific:

    If a verb differs in the installed build, inspect fak <verb> -h and use its current read-only form.

    line 86
  12. Distinctive:

    Never use broad unignored cleanup, broad wildcard ignores, or removal as a triage shortcut.

    line 115
  13. Distinctive:

    If only a small gap prevents qualification, finish that gap before committing.

    line 166
  14. Very specific:

    Run the narrow witness, then fak validate --mine <path> ...

    line 174
  15. Very specific:

    When clearing WIP spanning shared boundaries (pkg/*) with fak-private, verify boundary leak hygiene (python tools/scrub_public_copy.py …

    line 177
  16. Distinctive:

    Do not batch unrelated maintenance and feature work just because both are ready.

    line 183
  17. Very specific:

    Use /stale-work-loop for candidate adjudication.

    line 197
  18. Distinctive:

    When intent is unclear, complete the safe local spine and render the dry-run receipt.

    line 213
  19. Distinctive:

    Use the installed native dispatcher as the single workflow generator and launcher.

    line 218
  20. Very specific:

    Follow /fleet-wave for liveness and account recovery and /wave-harvest for reconciliation.

    line 268
  21. Distinctive:

    After the last mutation and verification, run:

    line 275
  22. Distinctive:

    before/after dirty path and grouped-unit counts.

    line 287

≈ “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

/clear-out-wip

Reduce backed-up work to the smallest truthful residual set. "Clear out" means every observed path ends in one witnessed disposition: ship, keep active, park, remove generated junk, or file and dispatch. A smaller git status is an outcome, not the objective; never get there by hiding, resetting, stashing, or absorbing another worker's changes.

This is the operator workflow over existing primitives. Use /commit-clean for each ship unit, /stale-work-loop for stale or ownerless candidates, and /fleet-wave only for already-filed, collision-priced follow-on units. Do not recreate those workflows here.

Non-negotiable fences

  • Work on main; do not create a branch, hand-rolled worktree, stash, reset, clean unignored files, or bulk-stage the checkout.
  • Treat the shared checkout as peer-dirty. A path's presence in git status does not make it yours. Mutate or commit only paths whose ownership is evidenced by the operator, current task, a lane/lease record, or a coherent diff you can attribute independently.
  • If MERGE_HEAD exists and the merge is not yours, do not finish or abort it. Leave your edits unstaged and wait. Strictly avoid raw unverified git merges, --autostash, or force-pushes. Integrate upstream advances only through structured convergence (fak sync apply or fak sync reconcile).
  • Dual-repo boundary awareness: when clearing WIP spanning shared interfaces (pkg/*), platform modules, or cross-repo dependencies with fak-private, inventory and coordinate both checkouts. Verify multi-module alignment (go work sync) and ensure zero private leak needles (python tools/scrub_public_copy.py --audit-staged) before declaring enabling or ship-now slices ready to land.
  • Never add a .gitignore rule merely to make an unknown path disappear. Ignore only a reproducible generated class with a named producer; verify no tracked or durable source path matches. Prefer allocating output through fak tree-doctor --scratch-dir/--scratch-path.
  • Never ship broken default builds, secrets, generated binaries, private run fuel, misleading claims, or half of a cross-file symbol dependency. A build tag may protect genuine in-progress source, but is not a way to launder abandoned code into trunk.
  • Do not close a parent issue merely because an independently useful enabling slice shipped. Describe and witness exactly the slice that landed; keep or file the remaining done-condition.

0. Open the lifecycle receipt

Before any mutation, run:

fak wip lifecycle begin --kind clear-out --root .

Keep the returned operation_id. This persists the fak-wip-inventory/1 before snapshot outside the working tree. If capture fails, report the typed WIP_LIFECYCLE_CAPTURE_FAILED condition but continue any safety-critical recovery; never reinterpret capture failure as a zero WIP count.

1. Freeze a read-only census

Run the inventory before editing anything. Save bulky machine output under an allocated scratch path, not a new repository-root filename.

git status --short --branch
git rev-parse --abbrev-ref HEAD
git rev-parse -q --verify MERGE_HEAD
fak sweep --json
fak tree-doctor --json

If clearing WIP that crosses shared boundaries into companion repository fak-private, run the dual-repo census:

# In fak-private checkout:
git status --short --branch
git rev-parse -q --verify MERGE_HEAD
git fetch origin
# Multi-module workspace graph verification:
go work sync

If either checkout has an active MERGE_HEAD, halt and wait for merge quiescence before proceeding. Never abort or finish a peer's merge.

Also inspect lane/lease and WIP records when available:

fak wip list --json
fak worktree worker list --json

If a verb differs in the installed build, inspect fak <verb> -h and use its current read-only form. Do not replace a missing read-only verb with an ad hoc mutation.

Build a path ledger with these columns:

UnitPathsEvidence of ownerIntentDependency seamTest/proofAge/originDisposition

Group paths by one coherent outcome, not merely by directory. Keep unknown ownership as UNKNOWN; do not infer it from timestamps, author names in nearby commits, or apparent quality. Record the before count and grouped unit count so the final reduction is measurable.

2. Retire hygiene debt first, but only proven hygiene

Classify maintenance residue before feature work because it obscures the real queue:

  1. Generated junk: known outputs, temp binaries, logs, caches, or allocated scratch. Preview ignored cleanup with fak tree-doctor --sweep-scratch --dry-run; apply only after every listed path is known disposable. Use fak sweep --clean-junk only for paths that the sweep itself freshly classifies as junk.
  2. Durable generated output: promote a successful reusable artifact up the tooling ladder instead of discarding it. In this repo that means a Go leaf/verb plus witness, not a new Python helper.
  3. Ignore gap: identify the producer, choose the narrowest pattern, prove it does not match tracked/durable files (git ls-files plus a pattern-specific check), edit .gitignore, rerun the producer or equivalent witness, and commit the maintenance change as its own coherent unit.
  4. Unknown or possibly human-authored file: retain it unchanged and route it to ownership adjudication. It is not hygiene.

Never use broad unignored cleanup, broad wildcard ignores, or removal as a triage shortcut.

3. Score units for the next action

Apply this deterministic order; do not prioritize by easiest diff alone:

  1. Safety and trunk health: secret exposure, build breakage, merge residue, generated binary collisions, or an active lease conflict.
  2. Ready-to-ship user value: a coherent outcome with an appropriate green witness.
  3. Enabling value: an independently useful seam that unblocks other work even if the parent feature remains disabled.
  4. Decay risk: old, ownerless, duplicated, or conflict-prone work.
  5. Cosmetic cleanup: formatting or organization with no independent outcome.

Within a tier, prefer highest user/unblock value, then strongest witness, then smallest collision surface. Use the FAK value frame for every proposed ship unit: For / Problem / Today / Better because / Witness. Reject a slice that cannot explain its own value without promising the unfinished parent.

Assign exactly one next action:

  • SHIP_NOW - coherent, owned, truthful, and witnessable now.
  • FINISH_SMALL_GAP - one bounded repair/test makes the coherent unit shippable in this session.
  • SHIP_ENABLER - useful and safe independently, while the larger feature remains openly incomplete.
  • KEEP_ACTIVE - current owner/lease and near-term continuation are evidenced.
  • STALE_ADJUDICATE - ownerless/old/ambiguous; use /stale-work-loop, whose discovery phase does not edit the candidate.
  • PARK - valuable bytes must be preserved but are not active or safely shippable; use the repo's witnessed parking/WIP mechanism, never a stash or mystery archive.
  • DELETE_JUNK - only the generated-junk proof above permits this.
  • FILE_FOLLOWUP - concrete residual work with a done-condition and explicit path tree.

4. Decide whether incomplete work can ship

A parent feature need not be fully enabled for a slice to land. The slice may ship as SHIP_ENABLER only when all rows pass:

GateRequired evidence
Independent valueA caller, operator, or next implementation can use the slice without pretending the parent is done.
Coherent boundaryNamed paths form one leaf and contain both sides of any changed contract.
Safe defaultDefault build/runtime behavior stays green and fail-closed; disabled means honestly unreachable, not silently broken.
Durable witnessFocused test or captured artifact proves the slice's actual claim.
Honest surfaceHelp, docs, claims, issue state, and flags do not advertise unfinished behavior.
Residual trackedThe remaining parent done-condition is already an open issue or is filed before the run ends.

Examples that can qualify: a tested parser used by an existing path, a fail-closed interface plus fake, a disabled-but-selfchecking demo spine, a migration reader landed before its writer, or a narrow .gitignore producer fix. Orphan structs, speculative frameworks, tests for unreachable behavior, and a flag wired to a stub do not qualify.

If only a small gap prevents qualification, finish that gap before committing. Otherwise keep, park, or issue it; do not lower the gates to reduce the dirty count.

5. Ship serially and re-census after every unit

For each SHIP_NOW or SHIP_ENABLER unit:

  1. Confirm ownership and inspect the complete diff for the explicit paths.
  2. Run the narrow witness, then fak validate --mine <path> ... for the committed tip plus only that unit. On this Windows host, use the repository's WSL test path where tests are required.
  3. Follow /commit-clean: preview the subject, ensure local HEAD is converged with upstream without raw merges or --autostash (fak sync apply or fak sync reconcile supporting ROUTE_DISJOINT_INTEGRATE, ROUTE_SUPERSET_MERGE, or ROUTE_HOLD_DIRTY_COLLISION with fak wip park). Commit exactly the paths under the lock, verify the committed path set, and push through the safe sync path (fak sync push).
    • When clearing WIP spanning shared boundaries (pkg/*) with fak-private, verify boundary leak hygiene (python tools/scrub_public_copy.py --audit-staged), run go work sync, and coordinate safe pushes across both repositories (fak sync push in fak, fak-sync push --apply in fak-private). One coherent unit, one commit, one leaf.
  4. Cite the changed module@rev and witness. State parent remains open for an enabling slice.
  5. Rerun fak sweep --json; peers may have changed the tree while the unit landed. Never apply a stale census to the next commit.

Do not batch unrelated maintenance and feature work just because both are ready. Do not repeatedly patch the same issue across several commits; finish its coherent acceptance boundary first.

6. Distribute and start contract-ready residual work

Local dirty paths are not worker fuel. First convert residuals into dedicated issues with:

  • one outcome and done-condition;
  • explicit owned path tree;
  • current candidate/evidence digest;
  • acceptance witness;
  • dependency and collision notes; and
  • retain/update/remove authority where stale work is involved.

Use /stale-work-loop for candidate adjudication. A one-unit or same-path queue is serial work, not a fleet wave. For multiple disjoint issues, use /issue-orchestrator (fak issue-orchestrator --plan-waves) and split overlaps into later waves before generating or starting sessions.

Execution intent

Classify the invocation before launch:

  • Plan-only: "inspect", "triage", "what can ship?", or "plan a clear-out" produces the census, dispositions, issue contracts, and priced wave; it starts no session.
  • Live clear-out: "clear out", "work through", "distribute", "start sessions", "run the backlog", or an unattended/deadline request authorizes the native dry-run -> live launch path for contract-ready residual issues. Local SHIP_NOW units still land serially first.
  • Explicit no-fan-out: "locally", "do not launch", or an equivalent constraint keeps all work serial even if several issues are ready.

When intent is unclear, complete the safe local spine and render the dry-run receipt. Never claim that work was distributed merely because issues or a plan were created.

Generate the guarded wave

Use the installed native dispatcher as the single workflow generator and launcher. Do not handwrite child prompts, spawn raw Codex processes, wrap the whole wave in one parent guard, or mix in the legacy launcher.

fak dispatch wave --help
fak fleet-accounts wave --count <N> --work-kind codex --product codex --json
fak fleet-accounts status --provider codex --json
fak dispatch wave --count <N> --backend codex --work-kind codex --max-workers <C> `
  --goal high-priority --workspace . --json

Choose N from the number of contract-ready issues, not the number of dirty paths. Choose C no higher than the collision-safe concurrency and independently observed host/account headroom. Read the dry-run receipt and require all of the following before launch:

  • selected issue IDs and bounded issue-derived worker fuel;
  • pairwise-safe lane/path leases, with overlaps moved to later waves;
  • distinct admitted account/session slots and a truthful shortfall;
  • guarded worker commands using the Codex backend;
  • implement -> test -> witness -> commit -> push ownership; and
  • typed refusal/downsize reasons for every candidate not started.

A refusal is a recovery input, not permission to retry blindly. Apply the receipt's recovery action, re-price once state changes, and preserve the refusal in the run report.

Start sessions once

For live-clear-out intent and a clean dry run, launch the exact plan once:

fak dispatch wave --count <N> --backend codex --work-kind codex --max-workers <C> `
  --goal high-priority --workspace . --live --json

Record the wave ID plus each issue, lane, account/session slot, PID, and run/log path. --count is the total requested session slots over refill time; --max-workers is the concurrent process ceiling. Do not rerun the launcher to top up. Let the native refill controller use newly available capacity; use fak dispatch auto only when the installed /fleet-wave contract directs it.

Monitor and harvest

Monitor from outside worker-owned trees and judge progress by independently readable state:

fak dispatch status --runs-dir <RUNS_DIR> --json
fak dispatch progress --target <N> --json
fak dispatch closure-audit --workspace . --json

Follow /fleet-wave for liveness and account recovery and /wave-harvest for reconciliation. SHIPPED requires git/read-back, focused green acceptance evidence, issue state, and DOS/commit witnesses; a process exit, worker log, or final message is insufficient. Release leases and account slots after reconciliation, then run another census. Start a later collision wave only from the new state and only while live-clear-out intent remains in force.

6.5. Close the lifecycle receipt

After the last mutation and verification, run:

fak wip lifecycle end --root . --id <operation_id>

The resulting fak-wip-lifecycle/1 receipt links ordered before/after inventory artifacts under one operation identity. Include its receipt_path in the final report.

7. Exit with a residual proof

Repeat the read-only census and reconcile every original unit plus any newly observed path. Report:

  • before/after dirty path and grouped-unit counts;
  • shipped commits with module@rev and focused witness;
  • generated junk removed and the producer/classification that proved disposal;
  • active or parked units with owner and recovery command/location;
  • filed residual issue numbers and any launched/harvested wave;
  • unknown/peer-owned paths explicitly untouched; and
  • the next checkable action.

The run is complete only when every observed unit has a disposition and every named follow-up is an open issue. A still-dirty tree can be a successful clear-out when the residue is owned and typed; a clean-looking tree with hidden, stashed, removed, or untracked obligations is a failure.

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.