<!-- SYNCED COPY — do not edit here. Canonical: common-docs/skills/task-hygiene/SKILL.md This file is distributed to every consuming repo by common-docs/meta/scripts/sync_skills.py. Edit the canonical, run the sync, and commit each repo. Edits made here are overwritten and lost. -->

Task Hygiene

Maintenance of the four-file task system in every repo. Run the full sequence or exactly one step; steps are independent, never assume an earlier one ran.

Invocation

/task-hygiene (all steps, 0–7) or /task-hygiene <n|name> (that step, after step 0).

#	Name	One-liner
0	bootstrap	Verify/create the four files; always runs first
1	cleanup	Move clearly-done items to condensed completed entries
2	dedupe	Merge duplicates, same-root-cause pairs, defect↔task overlaps
3	promote	Propose ≤3 defect→task promotions to Arman at a time
4	analyze	Full code analysis of named items; stamp the entries
5	enrich	Add concise pointers that make tasks easier to execute later
6	docs	Fix documentation the above revealed as stale
7	excavate	Hunt buried work items in docs; file the orphans

The four files

Adapt to where a repo keeps them; never force moves.

File	Role
FOUND_DEFECTS.md (root)	Holding area. Unapproved discoveries with evidence. NOT a worklist.
CURRENT_ERRORS.md (root)	Error-dump inbox. Arman pastes raw logs; every line gets a home. Not in aidream — run aidream-error-systems.md there instead.
.matrx/AGENT_TASKS.md	The only approved worklist.
.matrx/ARMAN_TASKS.md	Steps only Arman can perform. A decision is not a row here: it goes through ask-arman.

Never read, write, or list any .arman/ directory. Never edit docs under any official/ directory — file the correction instead. The repo's own CLAUDE.md wins on conflict.

Conventions

• Dates: absolute YYYY-MM-DD on every entry.
• Defect IDs: the ledger's real scheme, claimed from the maximum — defect ownership § Entry IDs. Only open entries carry an ID, and every open entry sits under ## OPEN.
• Admission test for a friction entry: reproducible on a fresh checkout AND fixable in the repo. Never file your own sandbox or permission errors, shell mistakes, transient flakes, local corrupted state, third-party limits with no workaround, or secrets.
• Priority: P0 breaks users/data now · P1 this week · P2 can wait · P3 polish.
• Defect statuses: open / needs-hw-verification / blocked-external / rejected.
• Analysis stamp, exactly one per entry: Unverified — from docs/logs only (the default) or Analyzed <date> — verified in code: <finding>. A task from an unanalyzed defect says "code analysis pending".

Lifecycle

• Fixed while in holding: delete the defect entry at once and add - [x] <what> — fixes {ID} (<date>, commit) to AGENT_TASKS Completed.
• Completed items condense to one line; detail lives in git. Compress anything done more than ~2 weeks ago.
• Rejected registry at the bottom of FOUND_DEFECTS: - {ID} — <reason> — <date> — delete when: <condition>. Check it before re-filing; step 1 deletes lines whose condition has happened.
• Cross-repo routing: a defect belonging to another local repo is filed in that repo's own files, noting who found it. Repo absent → file locally as blocked-external.
• Headless runs: step 3 needs Arman live. Otherwise write the prepared batch into ## Pending Arman review in FOUND_DEFECTS. Never stall, never self-approve.

Step 0 — Bootstrap

Check the four files exist; create any missing one from templates.md (never CURRENT_ERRORS.md in aidream). No Task Tracking section in the repo CLAUDE.md → add a brief one. Equivalent files under other names → use them, update headers, don't relocate.

Step 1 — Cleanup

Mechanical only. AGENT_TASKS and ARMAN_TASKS done items → one line in Completed/Done. FOUND_DEFECTS fixed entries → fixed-while-in-holding (never record twice). Prune the Rejected registry.

Step 2 — Combine

Merge same-problem pairs, one-root-cause symptom groups, and any defect that already exists as an open task (fold its evidence into the task, delete the defect). CURRENT_ERRORS signatures duplicating an entry → link by ID. Union evidence, never drop it.

Step 3 — Promote

Before promoting, record two checks on the entry: already built? (search by domain concept; found → delete with a pointer to the code) and still real? (reproduce it; not reproducible → needs-hw-verification or delete with evidence). Present at most 3 to Arman, each: title · priority · one-paragraph why · defect ID replaced · analysis stamp. Approved → move to AGENT_TASKS; rejected → a Rejected line. Then the next ≤3.

Step 4 — Analyze

Read the code; confirm or refute; root cause, blast radius, fix sketch. Update the entry in place with the stamp and file:line evidence. A wrong claim is corrected or deleted.

Step 5 — Enrich

Add only what makes execution cheap: exact paths, the pinning test, the related FEATURE.md, gotchas from sibling tasks. An entry that already suffices gets nothing.

Step 6 — Docs

Grep for claims touched by recently completed work, verify in code, then fix per the docs skill.

Step 7 — Excavate buried work

1. Candidates (grep): filenames TASK-*, *PLAN*, *ROADMAP*, *HANDOFF*, NEXT_*, KNOWN_*, *_INITIATIVE* in the root and docs/ (skip official/, .arman/); content not yet built|not yet wired|planned|follow-up|TODO|deferred.
2. Orphan filter (grep): a candidate whose basename appears in any tracked surface (the four files, root CLAUDE.md, docs/handoffs/, nearby FEATURE.md) is dropped. Cap ~10, oldest first.
3. Judgment: one small read-only agent reads each orphan's first ~60 lines: undone work? one-line summary? superseded (evidence)?
4. File: live work → one FOUND_DEFECTS entry marked "BURIED WORK RESCUED" with the path; dead docs → step 6. Never drop a candidate silently.

A repeat run skips anything already filed.

CURRENT_ERRORS lifecycle (not aidream)

Dumps are batch snapshots: Arman often cannot re-test for hours.

1. Raw exports land at the bottom of Inbox.
2. Fingerprint each error (ignore timestamps and frame noise), dedupe against Unique errors, and give every new signature a home: fix now if quick (tell Arman at once), FOUND_DEFECTS, an agent task (step 3), or ARMAN_TASKS.
3. Clear the Inbox after triage.
4. Resolved rows stay until a shipped build confirms (~2 weeks), then go. A returning error gets a new row citing the old ID. The file only shrinks.

In aidream, tool-call failures are mostly harness defects (faulty tools, poor instructions) — codebase improvements, not agent mistakes.