agentleFS
mediajunkiemediajunkie/piper-morgan-product/.claude/skills/cleanup-dev-active/SKILL.md

cleanup-dev-active

Skill8 starsChanged 11 days agoApache-2.0View on GitHub

Triage and archive stale files from dev/active/. Use during session

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

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

    When dev/active/ exceeds ~15 files

    line 21
  2. Distinctive:

    Document has formal structure (Status / Author / Date / Version / etc.)

    line 125
  3. Distinctive:

    Use the destination from Step 2's decision tree:

    line 158
  4. Distinctive:

    Add to session log:

    line 195
  5. Distinctive:

    Light triage: Every session wrap-up (move obviously completed files)

    line 235
  6. Distinctive:

    PM-initiated: When PM says "clean up" or "sort dev/active"

    line 237

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

cleanup-dev-active

Triage files in dev/active/ — archive completed/superseded work, keep only what's genuinely in progress.

When to Use

  • During session wrap-up when you notice dev/active/ is cluttered
  • During weekly docs audit (#937-series)
  • When dev/active/ exceeds ~15 files
  • PM asks to "clean up dev/active" or "sort the working directory"

Principle

dev/active/ is a workbench, not a filing cabinet. Files land here during active work and should move out when the work is done. The accumulation pattern is: agent creates file → work completes → file stays because nobody moves it.

Procedure

Step 1: Inventory

# List files with last-modified dates
for f in dev/active/*; do
  if [ -f "$f" ]; then
    modified=$(git log -1 --format='%ai' -- "$f" 2>/dev/null | cut -d' ' -f1)
    echo "$modified | $(basename "$f")"
  elif [ -d "$f" ]; then
    echo "DIR      | $(basename "$f")/"
  fi
done | sort

Step 2.0: Omnibus-coverage guard (MANDATORY — check BEFORE the decision tree)

A cycle log is durable-capture-pending, not forensic, until its day's omnibus exists.

Per-fire cycle logs (dev/active/cycle-log-{role}-YYYY-MM-DD.md) are the only granular record of any work that was displaced from a role's session log (see methodology-41 / the CLAUDE.md "displacement trap" rule — June 3–8 2026 displaced ~15 role-days across 6 roles). The omnibus is what makes that content durable: create-omnibus reads the cycle logs at synthesis and captures their substance into docs/omnibus-logs/YYYY-MM-DD-omnibus-log.md. Archiving or deleting a cycle log before that omnibus exists can permanently lose displaced work.

The guard — for every cycle-log-{role}-YYYY-MM-DD.md you're about to archive/delete:

DATE=$(echo "$f" | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}')
if [ -f "docs/omnibus-logs/$DATE-omnibus-log.md" ]; then
  echo "OK to archive: $DATE omnibus exists (content captured)"
else
  echo "⛔ HOLD: no omnibus for $DATE yet — cycle log is the live record; do NOT clean"
fi
  • Omnibus exists → the cycle log is now genuinely forensic → Destination 4 (archive to dev/YYYY/MM/DD/), same as the omnibus's own Step 10.
  • No omnibus yet → HOLD the cycle log in dev/active/ (Destination 3) regardless of age. It is load-bearing until covered. Flag the missing omnibus to Docs/PM (a cycle log with no omnibus past its day is itself a signal the omnibus is overdue or the gate is stuck).

This guard is the durability-net layer of the four-layer displacement defense (skill v1.5 dual-surface = source-catch; detector hook = reactive-net; m-31/m-41/CLAUDE.md = framing; this guard = protect-already-displaced-from-loss). It protects the reassuring half of the displacement audit ("June 3–8 isn't lost — it's in the omnibi") from having a cleanup time-bomb under it.

Step 2.1: Live-artifact / active-use guard (MANDATORY — check before filing anything to Destination 4)

"Old-looking" and "dead" are not the same state, and a classifier keyed only on dev/active/ residency + age can't tell them apart. The #1486 batch-15 sweep (2026-09-02, commit 9ee51dbaf) archived dev/active/honest-mvp-ledger-2026-08-08.html — PM's live sprint tracker, published at a canonical artifact URL PM opens regularly and Lead updates on most deploys — as "forensic-only." It sat archived 8 days, found only when PM asked for a restructure and the path 404'd. Restored in ea51eac09 (2026-09-10). Lead's diagnosis: two cheap signals would have caught it before any file is filed to Destination 4.

Before archiving any candidate to dev/YYYY/MM/DD/, check both:

  1. Is it published? — grep the file's basename across session logs and memos for "artifact" or a claude.ai/code/artifact URL. A file whose content is served at a live artifact/URL is by definition not forensic, regardless of how old it looks.
    grep -rl "$(basename "$f")" dev/ mailboxes/*/sent/ 2>/dev/null | xargs grep -l "artifact\|claude\.ai/code/artifact" 2>/dev/null
  2. Was it modified recently by an active role? — a file with commits in the last ~2 weeks, especially PM-requested ones, is in active use even if it "looks" like a stale working doc.
    git log --since="2 weeks ago" --oneline -- "$f"

Either signal fires → HOLD in dev/active/ (Destination 3), do not archive. If genuinely unsure whether a hit is load-bearing, ask PM rather than guess — same discipline as the <3-days-old dropbox rule below. This guard sits alongside Step 2.0's omnibus-coverage guard as a second protect-already-in-use check that runs before Destination 4 is ever chosen.

Step 2: Categorize Each File — Destination Decision Tree

The single most-important call: distinguish forensic-only working docs from forward-looking artifacts that still need to live somewhere active. A "completed" file isn't automatically forensic — many "completed" drafts have a forward life (next publish date, ratification target, canonical-doc-on-deck status). Filing forward-looking work to a dated archive makes it invisible right when the next-cycle agent needs it.

Five possible destinations, in priority order — check each in this sequence and stop at the first match:

#DestinationSignal questionsAction
1docs/public/comms/drafts/ — forward-looking publish draftsDoes the title appear in docs/internal/planning/comms/editorial-calendar.csv with status=queued + a future pubDate? Is the filename weekly-ship-*-draft-* or *-draft-* matching a queued title? Frontmatter (image: / alt: / caption:) populated?Move to docs/public/comms/drafts/ (with git mv) so it stays alongside other in-flight publish work
2docs/internal/{appropriate-location}/ — new canonical referenceMethodology doc / ADR proposal / pattern proposal / briefing / discipline note structured for canonical reference (formal sections, versioned, has Status field)? Will agents reference this forward (not as historical context but as authoritative source)?Move to canonical doc-tree location (consult docs/NAVIGATION.md if unsure)
3Keep in dev/active/ — continuously-updated workspaceContinuously-updated tracker (cio-innovation-backlog.md, cio-standing-items.md, comms-open-topics.md, exec-open-items-tracker.md, agent workspace subdirectory)? PM-day-of research (<3 days old)? publish-package/ mid-publish?Keep in dev/active/
4dev/YYYY/MM/DD/ — forensic-only archiveOne-time working artifact tied to a closed task: investigation report, audit finding, sent-memo draft, Phase 0 audit doc, gameplan, retest result, intermediate Pattern-Sweep deliverable, etc.? Will future agents only need this for historical reference (not forward citation)?Archive to dev/YYYY/MM/DD/ (use the file's last-modified date)
5Delete — true duplicateMultiple versions with (1), (2) suffixes where canonical exists elsewhere? Empty stub file with canonical version at correct location?git rm the duplicate; keep the canonical

Special cases that need PM confirmation:

  • File < 3 days old that PM may have dropped in (PM uses dev/active/ as a dropbox) → ask before moving
  • Cross-project files (Klatch, etc. — recognizable by filename) PM may have downloaded → ask before moving
  • Unknown purpose that doesn't fit any category → ask PM

Destination tells — what to look for

Forward-looking publish drafts (Destination 1): the failure-mode-to-avoid case. Symptoms a file is forward-looking publish material:

  • Filename includes -draft- AND a date that hasn't passed (e.g., weekly-ship-042-draft-2026-05-10.md filed on 2026-05-12 — the pubDate is May 13, not 10; the in-filename date is the workDate)
  • Title appears in editorial-calendar.csv with status=queued
  • File has full frontmatter (image: / alt: / caption:) — drafts ready to publish carry this; forensic working docs don't
  • Lives in dev/active/ (not yet in docs/public/comms/drafts/) because it was drafted there
  • Calendar lookup: grep -i '{title}' docs/internal/planning/comms/editorial-calendar.csv — if the row's pubDate is future and status is queued, this is Destination 1 not Destination 4

Canonical reference docs (Destination 2): symptoms:

  • Filename matches a canonical-doc convention (e.g., methodology-*.md, pattern-*.md, adr-*.md, briefing-*.md)
  • Document has formal structure (Status / Author / Date / Version / etc.)
  • Content reads as authoritative reference, not as a working memo or investigation
  • Currently in dev/active/ because it was drafted there, but the canonical home is docs/internal/{path}/

Workspace trackers (Destination 3): stay in dev/active/:

  • cio-innovation-backlog.md, cio-standing-items.md — CIO updates continuously
  • comms-open-topics.md — Comms updates continuously
  • exec-open-items-tracker.md — Exec updates continuously
  • publish-package/ — active publishing artifacts
  • non-doc-files/ — PM workspace dir
  • session-end-warnings.log — gitignored, per-seat, and REAL. Preserve it. ⚠️ Corrected 2026-08-01: on 07-30 I annotated this as "has NEVER existed," from a git log query against a gitignored path — a check that returns empty regardless. The hook fires; HOST's seat holds a logged tier=HARD firing from 2026-07-29. Absent in your worktree means no firing on your seat, not a dead mechanism.
  • Recent PM-dropped research files (<3 days old)

Forensic archives (Destination 4): typical archive shapes:

  • {issue-number}-issue-audit.md / {issue-number}-gameplan.md / {issue-number}-phase-1-design.md — Phase 0/1 working artifacts after issue closes
  • floor-fabrication-investigation.md / host-role-health-check-*.md — incident-specific investigations
  • workstream-{ship-number}-{role}-{date}.md — sent workstream memos (after Ship publishes)
  • canonical-retest-*.{py,md,csv} — retest run artifacts
  • pattern-{evolution|library-index|meta-synthesis|novelty|usage}-*.md — Pattern Sweep intermediate deliverables
  • cio-pattern-promotion-analysis-*.md — completed promotion analysis reports
  • merge-keeper-*.md — completed merge-keeper sweep reports
  • memo-*-{date}.md in dev/active/ — drafted memos that already got distributed via mailboxes/{role}/sent/

Step 3: Execute Moves

First, check what still points at the files you are about to move (#1719). A move once broke 22 live references in CLAUDE.md, briefings, a skill and operations docs, all found by hand afterwards:

scripts/check-move-refs.sh dev/active/file-one.md dev/active/file-two.md   # exit 1 lists live references

Fix each listed reference in the same commit as the move, or leave the file where it is. Dated session logs, omnibuses and mailboxes are history and are not listed.

Use the destination from Step 2's decision tree:

# Destination 1: forward-looking publish drafts → docs/public/comms/drafts/
git mv dev/active/weekly-ship-NNN-draft-YYYY-MM-DD.md docs/public/comms/drafts/

# Destination 2: canonical reference → docs/internal/{appropriate-location}/
git mv dev/active/methodology-NN-name.md docs/internal/development/methodology-core/

# Destination 4: forensic-only → dev/YYYY/MM/DD/
mkdir -p dev/YYYY/MM/DD
git mv dev/active/NNNN-issue-audit.md dev/YYYY/MM/DD/

# Destination 5: true duplicate → delete
git rm "dev/active/file (1).md"

Before staging the moves, run the discipline opening per feedback_clear_index_before_staging_on_shared_main.md:

git reset HEAD  # clear any pre-existing index residue
# ... then execute the per-file git mv / git rm commands above ...
git diff --cached --name-only  # READ EVERY LINE — verify only intended moves are staged

Step 4: Verify

# Count remaining files
ls dev/active/ | wc -l  # Target: <15

# Confirm no broken references
grep -r "dev/active/archived-file" docs/ .claude/  # Should be empty

Step 5: Report

Add to session log:

### dev/active/ cleanup
- Before: N files
- Archived: X files to dev/YYYY/MM/DD/
- Deleted: Y duplicates
- Kept: Z active files
- After: Z files

What to Keep (Safe List)

These types of files belong in dev/active/:

  • Files for work with an upcoming deadline (conference talks, scheduled publishes)
  • publish-package/ — active publishing workflow artifacts
  • Agent workspace directories (e.g., pa/) for active agents
  • Specs or plans PM is actively reviewing

What to Archive (Common Accumulations)

Note: PM's browser downloads to this folder, so files from other projects (Klatch, etc.) or duplicate downloads with (1), (2) suffixes will periodically appear. These are not Piper Morgan work products — archive or delete after confirming with PM.

These commonly pile up and should be moved:

  • Superseded briefing drafts (v0.1 when v0.2 is in docs/briefing/)
  • Onboarding prompts after agent launch is complete
  • Proposals after issues are filed
  • Session logs that belong in dev/YYYY/MM/DD/ (rare — create-session-log usually puts them in the right place)
  • Completed tracker spreadsheets

Anti-Patterns

Don'tWhyDo Instead
Delete files without checkingMay be PM's in-progress workArchive to dated directory
Move files PM dropped here recentlyPM uses dev/active/ as a dropboxAsk before moving files < 3 days old
Clean up during active sprint workContext switching wastes timeDo it at session boundaries
Move agent workspace directoriesOther agents depend on the pathOnly move if agent is decommissioned

Frequency

  • Light triage: Every session wrap-up (move obviously completed files)
  • Full cleanup: Weekly audit or when file count > 15
  • PM-initiated: When PM says "clean up" or "sort dev/active"

Lesson Learned (May 12 → May 15 iteration)

The Ship #042 draft incident (May 12 cleanup, 62f5cd0a): weekly-ship-042-draft-2026-05-10.md was filed from dev/active/ to dev/2026/05/10/ (Destination 4 / forensic archive) when the correct destination was docs/public/comms/drafts/ (Destination 1 / forward-looking publish draft headed for May 13 publication). The filename's 2026-05-10 was the workDate, not the pubDate — the draft was queued for publication 3 days later. Filing it to the dated archive made it invisible right when the next-cycle agent needed to publish it.

The fix: the decision-tree in Step 2 now puts Destination 1 first in priority order, with explicit calendar-lookup signal. When in doubt about a *-draft-* file: grep the editorial calendar before archiving. If the title appears with status=queued and a future pubDate, the destination is docs/public/comms/drafts/, not the dated archive.

General principle: a "completed" file isn't automatically forensic. Many "completed" drafts have a forward life. The decision tree's priority order (publish-drafts → reference → workspace → forensic → delete) reflects that forensic is the last destination considered, not the default.

Lesson Learned (2026-09-10) — the live-artifact miss

The honest-mvp-ledger incident: batch 15 of the #1486 sweep (9ee51dbaf, 2026-09-02) archived dev/active/honest-mvp-ledger-2026-08-08.html to dev/2026/08/29/ as forensic-only. It was PM's live sprint tracker, published at a canonical artifact URL and updated by Lead on most deploys — the opposite of forensic. It sat archived 8 days before PM's own 404 surfaced it (restored in ea51eac09). Lead's diagnosis, relayed 2026-09-10: the sweep's classifier keyed on dev/active/ residency + age, and neither signal distinguishes "old-looking" from "no longer in use" — a continuously-updated tracker can look exactly like dead weight to an age-only check.

The fix: Step 2.1 above, added the same day — check publication status and recent-commit activity before anything is filed to Destination 4, not just for trackers already on the Destination-3 safe list. The safe list (What to Keep) names specific known trackers; Step 2.1 catches the ones nobody thought to name in advance.

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.