laoujin/scout/scout-triage

Scout triage — auditing Atlas research health

Overview

Scout's pipeline can leave damage on Atlas that the site renders silently: a perfectly-good page wearing a false failure flag, a dead expedition with no survivor, a child page missing from its parent's manifest, a backfillable-but-blank cost footer. This skill sweeps `atlas/research/`, classifies every finding, then drives remediation — page by page, with judgment, not blind fixes.

Detection is mechanical (scan.py); remediation is judgment (is this flagged page real content or a genuine failure?) and stays with you.

When to use

• After a batch of expeditions fires (e.g. a michelin-weekend series) — catch failures before they pile up.
• Periodically, as a health check ("is anything missing or broken?").
• When the Atlas index shows a ⚠ badge, an empty Cost/Duration footer, or a card with no cover.
• When you suspect a Scout regression — a category that should be extinct (false flags, dup-URL aborts) reappearing means a code fix regressed.

Step 1 — run the scan (detection)

python3 scout/skills/scout-triage/scan.py atlas/research      # or: ATLAS_DIR=... scan.py
python3 scout/skills/scout-triage/scan.py atlas/research --json   # machine-readable

Read-only. Groups findings by category, most-severe first, with a one-line summary: count. A clean tree prints clean — no triage findings.

Step 2 — triage each category

The judgment call that matters: GENUINE_FAILURE vs FALSE_FLAG. Both carry a failure status. The discriminator is body size — tiny body = content is gone (re-run); substantial body = the flag is lying (clean it). The scan splits them by char count; eyeball the page before acting when it's near the threshold.

Step 3 — record and remediate

1. Write/refresh `atlas/TRIAGE.md`: ## Open items first (what still needs a decision), # Fixed at the bottom (what you resolved, with links to verify). One concern per row; keep verify links.
2. Propose fixes grouped by category. Get approval before mutating — many fixes touch two repos: page/manifest edits land in `atlas/`, root-cause fixes land in `scout/` code. Per Scout boundaries, never git/gh/push without asking.
3. If a category that should be extinct reappears, treat it as a Scout regression, not just cleanup — these root causes were already fixed (ledger-validation non-fatal, dup-URL accepted, result-read non-fatal, the orphaned-JSON jq exit). A fresh occurrence means a code fix regressed; fix the cause in scout/, add a test, then clean the symptom in atlas/.

Common mistakes

• Deleting a `FALSE_FLAG` page because it "failed" — it has real content behind the flag. Read the body first.
• Backfilling cost on a `lost` page — there's no .scout-result.json to read; the number is unrecoverable, and that's fine (the content isn't affected).
• Fixing the symptom only. Stripping a false flag fixes one page; making the cause non-fatal in Scout prevents the next hundred.
• Editing the leaf but not the parent/manifest. A status lives in three places (leaf frontmatter, parent children:, manifest.json); a half-fix still renders the ⚠.