Maintenance

You are the maintenance skill — on-demand Lintel-maintenance pass.

What this skill does

Operator-request 5.3 (post Cohort 2 dependency 1.1 usage-log landed): an on-demand maintenance system with 3 modes:

1. --force-compact — clear excess context beyond what's already compacted. The operator allows heavy contexting for heavy tasks, then reclaims on demand.

2. --monitor-paths — watch canonical paths for drift/missing. Would have caught 0.4 (tasks/personas+memory missing per docs/architecture.md). Static-path verification.

3. --simulate-tokens <workflow> — "what would /li:cycle --mode customer-engagement cost?" Depends on 1.1 (usage-log) for real numbers; otherwise heuristics.

Closes operator-request 5.3 + integrates with L-002 (grep-first-pattern adapted for paths).

When to use

• "My Lintel feels sluggish" → /li:maintenance --force-compact
• "Is everything in place?" → /li:maintenance --monitor-paths
• "What would X cost?" → /li:maintenance --simulate-tokens customer-engagement
• "What's rusting?" → /li:maintenance --rust-report (skills with <2 invocations past 30 days, via usage-log)

When NOT to use

• Mid-task work (this pauses for diagnostics)
• Single-file check — /li:doctor --quick is faster
• Pre-implementation cost estimate — /li:cycle --dry-run has inline cost

Workflow per mode

--force-compact

# Identify compactable state:
# 1. /context-save snapshots > N days old → archive
find .claude/runtime/state -name "*.md" -mtime +30 | xargs -r tar -czf ~/.lintel/archive/old-state-$(date +%Y%m%d).tar.gz

# 2. usage records (~/.lintel/audit/usage-*.jsonl), if any exist: archive entries
# older than 90 days (the writer is manual — see /li:usage-log; no auto-rotation)

# 3. Build/draft directories: clean up after successful PRs
find ~/.lintel/draft -mtime +7 -type d -empty -delete

# 4. ~/.lintel/sessions/ stale markers (design-surfaced, bloat counters) — age-gated cleanup here (nothing else cleans them; restored in v5.2)
# (no action)

# 5. Provenance records: keep latest per artifact, archive older
# (specific to /generate-* outputs)

Surface report: "Reclaimed MB. Compaction summary: ..."

--monitor-paths

Static-path manifest (loaded from config or hard-coded):

load-bearing_paths:
  - .claude/memory/lessons.md          # required per docs/architecture.md
  - .claude/memory/personas.md          # required per docs/architecture.md (Cohort 1 0.4)
  - .claude/memory/working-state.md            # required per docs/architecture.md (Cohort 1 0.4)
  - ~/.lintel/profile.yaml     # session-config
  - .claude/runtime/audit/     # observation spine writes here (usage-* stays in ~/.lintel/audit/)
  - skills/                    # canonical skill location
  - agents/                    # canonical agent location

deprecated_paths_check:
  - $HOME/.jstack/             # post Phase A: should be empty or migrated

required_files_in_paths:
  - skills/CATALOG.md          # auto-generated, should exist post-Cohort-2 merge
  - .claude/memory/lessons.md           # canonical lessons

For each path:

• Check existence
• Check writeable (if relevant)
• Check non-empty (if expected)
• Check no-drift (deprecated paths should be empty)

Surface the diff vs expected state. PASS / WARN / FAIL per path.

--simulate-tokens <workflow>

Read mode-presets from skills/cycle/SKILL.md mode_envelopes:

hotfix:           ~5k tokens
customer-engagement: ~40-80k tokens
internal-tool:    ~25-50k tokens
demo-prep:        ~15-25k tokens
research-dive:    ~10-20k tokens

Cross-reference with usage records, if any exist (the usage-log writer is manual, operator-invoked):

• Read ~/.lintel/audit/usage-*.jsonl past 30 days
• Filter by skill-list for the chosen workflow
• Compute median + p95 tokens-est
• Surface: "Estimated: median k tokens (p95: k) based on N prior invocations"

If no usage-log data: fall back to mode-envelope hard-coded estimates.

--rust-report

Read usage records past 30 days, if any exist (writer is manual — without records, report "no usage data" instead of a rust table):

• For each skill in skills/, count invocations
• Flag skills with < 2 invocations as rust candidates
• Group by category: never-invoked / rare / cold / active
• Surface a table for operator review

Pairs naturally with /li:catalog --trends (Cohort 2 1.6 output).

Pause-points

• --force-compact would reclaim > 500MB: confirm via AskUserQuestion (avoid surprise)
• --monitor-paths FAIL on a load-bearing path: surface with a fix recommendation

Integration

Reads:

• ~/.lintel/audit/usage-*.jsonl (Cohort 2 1.1 output)
• .claude/runtime/state/ (snapshot dir)
• ~/.lintel/draft/ (clean targets)
• skills/cycle/SKILL.md mode_envelopes
• Load-bearing path manifest (configurable)

Writes:

• ~/.lintel/archive/old-state-*.tar.gz (compaction outputs)
• .claude/runtime/audit/maintenance-runs.jsonl (audit-trail)
• stdout (report)

Consumed by:

• Operator (manual periodic runs)
• Future: scheduled-task wrapper for weekly auto-run

Anti-patterns

• Aggressive force-compact mid-engagement — keep recent state for 30 days minimum. Operators need to resume from context that isn't just-shipped.
• Path-monitoring without write-safety — this skill READS paths. Modifications go through separate ops.
• Token-simulation without usage-log data — surface an "estimated from defaults only — limited accuracy" warning.

Failure recovery

• Compaction targets locked (open files): skip + log
• Path monitoring permission-deny: warn + continue (partial coverage)
• Token simulation: heuristic fallback if no usage-log data, flag it in the report

Recommended next steps

• Post-monitor-paths FAIL: address each fail individually (most likely missing config or a stale path)
• Post-rust-report: review rust candidates, archive what is genuinely cold
• Post-force-compact: run /li:doctor --quick to verify no inadvertent state loss