linear-housekeeping

name	linear-housekeeping
description	Orchestrate full Linear housekeeping — triage ticket status, organize orphans into epics, then sync MASTER_TICKET_PLAN.md. Human checkpoint between triage and apply.
version	1.0.0
level	intermediate
debug	false
category	workflow
tags	["linear","housekeeping","triage","epics","documentation"]
author	OmniClaude Team

Linear Housekeeping

Dispatch Requirement

When invoked, dispatch to a polymorphic-agent:

Agent(
  subagent_type="onex:polymorphic-agent",
  description="Linear housekeeping",
  prompt="Run the linear-housekeeping skill. <full context>"
)

CRITICAL: subagent_type MUST be "onex:polymorphic-agent" (with the onex: prefix).

Overview

Parent skill that chains linear-triage → human review checkpoint → linear-epic-org → ticket-plan --sync into a single coherent workflow.

Announce at start: "I'm using the linear-housekeeping skill for a full ticket audit."

Imports: @_lib/contracts/helpers.md

Quick Start

/linear-housekeeping
/linear-housekeeping --dry-run        # preview all changes, write nothing
/linear-housekeeping --threshold 7   # use 7-day staleness threshold (default 14)
/linear-housekeeping --skip-triage   # skip triage, go straight to epic-org + sync
/linear-housekeeping --sync-only     # only run ticket-plan --sync (fastest)

Workflow Phases

Phase 1: linear-triage      (assess + mark done tickets)
          ↓
          Human checkpoint  (review TriageReport, confirm stale flags)
          ↓
Phase 2: linear-epic-org    (group orphans into epics, human gate for ambiguous)
          ↓
Phase 3: ticket-plan --sync (regenerate or patch MASTER_TICKET_PLAN.md)
          ↓
         Done

---

Phase 1: Triage

Dispatch linear-triage:

Skill("onex:linear-triage", args="--threshold-days {threshold}")

On completion, display the TriageReport summary.

If --dry-run: pass --dry-run to linear-triage. Continue to Phase 2 without pause. Otherwise: pause for human review.

Human Checkpoint (after triage)

Present the summary and ask:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Triage complete. Review before continuing:

✅ Marked done:  {N} tickets (applied)
⚠️  Stale flags: {K} tickets (not applied — see below)
🔗 Orphans:      {M} tickets (will be addressed in Phase 2)

STALE TICKETS FLAGGED (review needed):
{list of stale tickets with age and recommendation}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Continue to Phase 2 (epic organization)?
Type "y" to continue, "stop" to exit, or review stale tickets first.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Stale ticket handling: The user may ask to archive/cancel specific stale tickets during this review. Handle those immediately via Linear MCP before proceeding to Phase 2.

---

Phase 2: Epic Organization

If triage found orphaned tickets (or --skip-triage was used with known orphans):

Skill("onex:linear-epic-org", args="--triage-report {report_path}")

linear-epic-org handles its own human gate for ambiguous groupings. See that skill for the full interaction flow.

If no orphans found, skip Phase 2 with a note:

Phase 2: No orphaned tickets found — skipping epic organization.

---

Phase 3: Ticket Plan Sync

After triage and epic-org are complete (tickets marked done, epics created), the MASTER_TICKET_PLAN.md will be out of sync. Always run sync as the final step.

Skill("onex:ticket-plan", args="--sync")

Mode is auto-selected by ticket-plan --sync based on file age. Pass --mode full after a session with many changes to ensure a clean state.

---

Flags

Flag	Effect
--dry-run	Pass through to all three sub-skills. No Linear writes, no file writes.
--threshold N	Set staleness threshold in days (default 14). Passed to linear-triage.
--skip-triage	Skip Phase 1. Jump to Phase 2 (epic-org) and Phase 3 (sync).
--sync-only	Skip Phases 1 and 2. Only run ticket-plan --sync.
--no-epic-org	Skip Phase 2. Run triage → sync without epic organization.
--full-sync	Pass --mode full to ticket-plan --sync (force full regeneration).

---

Recommended Cadence

Frequency	Command
Weekly	/linear-housekeeping — full triage + org + sync
Daily / after PR merges	/linear-housekeeping --sync-only — refresh the doc
After epic sprint planning	/linear-housekeeping --no-epic-org — triage + sync
New project start	/linear-housekeeping --full-sync — clean slate

What weekly triage now catches (after OMN-3577 remediation):

• Tickets with a closed PR where work landed in a sibling PR → auto-closed as mark_done_superseded
• Epics where all children are Done → auto-closed as mark_done_epic

Running weekly limits zombie ticket accumulation to at most one week of drift.

---

Example Session

> /linear-housekeeping

I'm using the linear-housekeeping skill for a full ticket audit.

Phase 1: Running linear-triage (threshold: 14 days)...
[triage runs, marks OMN-2068 done, flags 4 stale tickets, finds 7 orphans]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Triage complete. Review before continuing:
✅ Marked done:  1 ticket  (OMN-2068 — FK scan, PR merged)
⚠️  Stale flags: 4 tickets  (age >30d, recommend review)
🔗 Orphans:      7 tickets  (will be addressed in Phase 2)

STALE TICKETS:
  OMN-1452  (89d)  omniintelligence  → recommend: review_and_close
  OMN-407   (95d)  omnibase_core     → recommend: keep_open
  OMN-554   (32d)  omnibase_core     → recommend: keep_open
  OMN-917   (61d)  omnibase_core     → recommend: review_and_close
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Continue to Phase 2?

> y

Phase 2: Running linear-epic-org (7 orphans)...
[epic-org presents groupings, user approves, 2 epics created]

Phase 3: Running ticket-plan --sync (patch mode)...
Updated 3 rows, added 2 new epic sections.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Housekeeping Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tickets marked done:   1
Epics created:         2
Tickets linked:        7
Doc rows updated:      3
Doc sections added:    2

Stale tickets (need your review): 4
  → Review and archive manually or rerun triage after decisions.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Error Handling

Failure	Behavior
linear-triage fails	Report error, stop. Do not proceed to Phase 2.
linear-epic-org fails	Report error. Skip to Phase 3 (sync still safe).
ticket-plan --sync fails	Report error. Triage and epic changes already applied in Linear — just retry --sync-only.
Linear API rate limit	Pause 60s, retry once. If still failing, save state and exit with resume instructions.

---

See Also

• linear-triage skill — Phase 1: status assessment
• linear-epic-org skill — Phase 2: epic organization
• ticket-plan --sync — Phase 3: doc sync
• @_lib/contracts/helpers.md — TicketContract, EpicContract schemas
• docs/tracking/MASTER_TICKET_PLAN.md — the output document