Skip to content

TGPSKI/catnip / .agents/skills/catnip-triage

catnip-triage

Verified

Diagnose catnip problems — empty charts, missing repos, a timer that stopped, data that looks wrong, onboarding that will not complete. Resolves coordinate mismatches (which config, which account, which run, which timeframe) before investigating anything deeper. Use when catnip is not behaving as expected.

catnip Triage

Structured diagnosis for catnip. Two tiers: resolve coordinates first, investigate only if they check out.

Why coordinates come first

Almost every catnip complaint that turns out not to be a bug is one of these:

  • the config file being edited is not the config file in effect;
  • the shell and the timer are reading different data directories;
  • the token belongs to a different account than CATNIP_OWNER;
  • the TUI is showing a 1-day window over an account with weekly traffic;
  • the "missing" repository was filtered out on purpose, with the reason written to a file nobody read.

In every one of those, catnip is working exactly as configured. Deep investigation before checking them wastes the session and often "discovers" a bug that does not exist. Tier 1 is designed to close those in under a minute.

Start here

Capture the symptom in the user's own words, verbatim, before doing anything. Then run the one command that reads the whole environment:

catnip doctor --json > /tmp/catnip-doctor.json

That single output carries: which config file is live, which account the token belongs to, whether traffic endpoints answer, how old the newest run is, which analysis artifacts are missing, the state of the history store, and whether the timer is enabled. Read it before asking the user anything you could have read there.

If catnip doctor itself cannot run, that is the finding — go to Phase 1 Step 1.

The coordinate systems

These are catnip's, specifically. Resolve them in this order.

CoordinateWhere it can differHow it presents
Config file$CATNIP_CONFIG · ./catnip.conf · ~/.config/catnip/catnip.conf · none (defaults)"My changes have no effect" — the timer pins one path, the user edits another
Data directoryCATNIP_DATA_DIR per config, or the XDG default"There are no runs" while runs exist under a different root
Accountthe gh token's login vs CATNIP_OWNERRuns succeed and collect nothing, or collect someone else's repos
Repo selectionCATNIP_INCLUDE / EXCLUDE / FORKS / ARCHIVED / PRIVATE"Repo X is missing" — it was rejected, with the reason in reports/skipped.tsv
Runnewest run vs the one the TUI was opened onStale numbers; an argument was passed to catnip tui weeks ago in a script
TimeframeTUI 1d / 1w / 2w / all"My data vanished" — a quiet day at 1d; "history is missing" at 2w
Clockrun IDs are UTC; users read local time"The timer didn't run last night" when it ran at 03:00 UTC = 20:00 local the previous day
systemd scope--user units (correct) vs system units; lingering on/offTimer enabled, no runs after logout

Evidence rules

Label every claim. In this domain the labels matter because catnip produces a great deal of DEFINITIVE evidence that is easy to skip past in favor of a plausible story.

LabelIn catnip, that means
DEFINITIVEcatnip doctor --json, manifest.json, reports/*.tsv, a gh api response, a journal line, a file's existence
CONFIGcatnip config output, the config file, the rendered systemd unit — what should happen
SOCIAL / ANECDOTAL"I definitely ran it yesterday", "it worked last week", "the timer is on"

manifest.json in each run directory is the highest-value single file: owner, repos listed/selected/skipped/fetched, traffic denials, rate-limit before and after, duration. Read it before theorizing about what a run did.

Investigation progress

Keep one artifact per incident. It is the state machine.

File: sessions/{YYYY-MM-DD}-{slug}.md (create sessions/ wherever the user keeps notes; it is not part of the catnip repo)

Artifact statePhase
No artifactPhase 1 — @references/phase-01-intake-coordinates.md
Intake table present, no coordinate verdictContinue Phase 1
Verdict COORDINATE MISMATCHSkip to Phase 3 — @references/phase-03-remediate-document.md
Verdict COORDINATES VERIFIED, no hypothesesPhase 2 — @references/phase-02-investigate.md
Hypotheses present, none eliminatedContinue Phase 2
Root cause identified, not remediatedPhase 3
Actions closedComplete

The recurring hypotheses

Before generating your own, check these — they cover most real catnip faults once coordinates are verified.

HypothesisSuspect whenDiscriminating check
Traffic denied (no push access)Metadata is present, traffic is empty, for some reposcat <run>/reports/traffic-denied.tsv
Token scope lostTraffic empty for every repo; worked beforecatnip doctor → token scopes and traffic access
Timer never firesNewest run is days old, timer "enabled"loginctl show-user $USER --property=Linger, then catnip timer logs
gh not on the unit's PATHService ran and failed instantlycatnip timer logs -n 30
Stats endpoints still coldCode-frequency/contributors views empty on a young repoNormal for a first run; re-run and compare
Analysis stage failedOne TUI panel empty, others finecatnip verify, then catnip analyze and read stderr
Rate limit exhausted mid-runPartial run, some repos missing detailmanifest.json → rate_remaining_after near 0
Data gap from pruningall timeframe has a holecoverage in traffic_daily.json; check whether pruned runs were ingested

Anti-patterns, in this domain

  • Do not re-run catnip run to "see if it fixes itself" before capturing state. A new run rewrites the newest-run pointer and can mask the evidence for what the previous one did.
  • Do not delete a run directory during an investigation. If the history store is also incomplete, that run may hold the only copy of its traffic days.
  • Do not trust "the timer is on." Enabled says nothing about whether the last five runs succeeded. catnip timer status and the journal do.
  • Do not conclude "GitHub is wrong" because catnip's numbers differ from the web UI. GitHub's own graph shows a 14-day window and revises recent days upward; catnip's all reads the history store. Compare like for like — catnip view traffic at 2w.
  • Do not read source before Tier 1 clears. Config and command output only.

Phase files

PhaseFileEnds with
1@references/phase-01-intake-coordinates.mdCOORDINATE MISMATCH or COORDINATES VERIFIED
2@references/phase-02-investigate.mdA surviving hypothesis with definitive evidence
3@references/phase-03-remediate-document.mdA fix, a verification, and a written artifact
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall