/scout-loop — crawl the field, study the best lead, file witnessed backlog

The research→backlog super-loop. fak already has an outward crawler (fak idea-scout plans deduped idea-scout triage issues from arXiv, GitHub, Hacker News, and Reddit; --live is the separate mutation gate) and a study pipeline (/study-repo reads a repo at a pinned @sha and decomposes it; /field-borrow witnesses one capability against fak and files it grounded). Nothing connects them: leads pile up in a triage queue and the deep study→witness→file pass waits for a human to remember it. scout-loop is that seam — it drives the tools we already have, in order, one lead per pass, and can run unattended on a cadence.

This is a meta-skill: it re-implements none of the crawlers or study skills. It orders them and holds the discipline the raw pieces assume — PLAN/witness first, one lead per pass, no monolith, and a crawl is never a ship.

Its place in the family (do not duplicate a sibling)

Skill / tool	Starts from	Mechanism	Terminal action
fak idea-scout	an outward feed	dry-run arXiv/GitHub/HN/Reddit scan + filed-stamp dedup	plans raw triage issues; --live files
/study-repo	one repo URL	clone → read the code → decompose	files many small witnessed leaves
/field-borrow	one named capability	dogfood fak_feature_query/fak index	files one grounded issue
/industry-score	the field taxonomy	coverage + parity-debt scorecard	a scorecard (files nothing)
/super-loop	the ready backlog	launch N detached /goal workers	resolves leaves (witnessed ancestry)
/scout-loop (this)	the crawler output	crawl → select → study → witness → file, cadenced	runs the study pass unattended, one lead per pass

scout-loop is to idea-scout+study-repo what /super-loop is to a single /dos-dispatch: the durable, cadenced front door that runs the proven unit repeatedly and safely. If you were handed one specific repo, skip straight to /study-repo. If you already have a named capability to check, use /field-borrow. Reach for scout-loop when the job is "keep finding new leads and converting them" — the loop, not a single pass.

Durable monitored-source queue

Start each pass from docs/research/monitored-repositories.json, rendered with:

fak study-monitor --due-days 14

Prefer the highest-priority due candidate or watch row before opening a fresh outward search. Exact owner/name is the deduplication key. When outward discovery finds a stronger untracked lead, register its checked revision and last_checked before deep study; after study, update the same row and link its study_note. This makes “most recently checked” queryable rather than recoverable only from filenames or session memory.

The pass — one lead, end to end

1 — CRAWL: capture the first-class scout plan

Run the Go front door from the repo root. Dry-run is the mandatory default:

fak idea-scout --json > idea-scout-plan.json

Inspect candidates, scores, source revisions, dedupe evidence, and planned issue contracts. For a pinned replay or unavailable network, use --candidates FILE. Direct python tools/idea_scout.py use is a legacy/debug comparison only.

Issue creation is a separate explicit gate and requires operator mutation intent:

fak idea-scout --json --live

Do not infer permission to cross that gate from this skill matching. Validate selected contracts through fak-dev issue contract and price any worker launch through fak dispatch before execution.

2 — SELECT: one highest-value repo-shaped lead (never a batch)

From the crawl, pick one lead that is repo-shaped — a GitHub URL, a paper-with-code link, a named codebase — and where the field signal says the parity-debt or novelty is highest. Prefer the fresh-lane leads (a **Why surfaced** line marked trending / very fresh / actively updated): a repo that just appeared or is climbing relative to ours is the highest-novelty, most-perishable lead — study it before it's an incumbent everyone already read. One lead per pass is the anti-storm bound (the same discipline as idea-scout's per-run cap). If nothing fresh is repo-shaped, stop clean — an empty pass is a valid result; never invent a lead to have something to do.

Prefer a lead that is not already studied: grep docs/notes/CONCEPT-STUDY-* and gh issue list --search for its name first, so the loop doesn't re-study a repo a prior pass (or a human) already decomposed.

3 — STUDY: hand the lead to /study-repo (do not restate it)

Require the returned study to expose both the default frontier and the bounded-superset coverage frontier. Do not select leads only because they might replace fak's current default; a lead is also high-value when it serves a credible user/job/constraint cohort through an OPTIONAL-MODULE or RECIPE seam. Deprioritize feature-count novelty, genuinely superseded approaches, and moment-in-time claims without a dated WATCH review trigger. This keeps scouting broad in user coverage but bounded by fak's scope and support economics.

Invoke /study-repo on the selected lead. That skill owns the whole acquisition front-half — shallow-clone into scratch, never the tree, pin the commit @sha, read the CODE (load-bearing modules + tests + recent commits) not the README pitch, extract candidate borrows each grounded at a real path:line@sha, and decide borrow-vs-integrate on the license. Do not re-implement any of that here; drive it.

4 — WITNESS + FILE: /field-borrow's witness step, then file small

For each surviving candidate, run /field-borrow's witness step — dogfood fak_feature_query / fak index docs|leaves|verbs|claims (plus a raw Grep to guard the lexical ranker's false-ABSENT) → classify PRESENT / PARTIAL / ABSENT:

• PRESENT → fak already has it: drop the candidate, record the card. A witnessed "we already had this" is a real, good result — not a miss.
• PARTIAL / ABSENT → ground it in the fak seam (path:line in fak), then file a small independently-shippable leaf under the right epic, carrying both anchors (source path:line@sha + fak seam), the dogfood witness, and a first checkable step. Dedup first (gh issue list --search). Never a monolith — the ship-alone test from /study-repo step 5. Leak-check every body: no absolute path, host, secret, or PII from the foreign clone.

5 — REGISTER: the trail, or it lived only in a transcript

Record the pass in a dated docs/notes/CONCEPT-STUDY-<repo>-<date>.md (URL + pinned @sha, what you read, the borrow · source path:line@sha · witness · inspire|integrate · filed # table), add its INDEX.md line, and commit the docs lane by explicit path with a (fak docs) trailer. This registration — not the issues alone — is what makes the research durable and keeps fak index freshness clean.

6 — CADENCE: set it to run (unattended)

One pass is above; the loop is a cadence of passes. Two shapes:

• In-session (attended). Run steps 1–5 now for one lead, then stop. Re-run for the next lead when you choose.
• Scheduled (unattended). tools/register_scout_loop.ps1 installs a daily Scheduled Task (FleetScoutLoop) that fires one pass via a detached /goal worker reading .claude/goal-prompts/scout-and-study-witnessed.md. Plan by default — installed without -Launch, the fire runs the launcher in -PlanOnly mode and spawns nothing; -Launch is the explicit opt-in. Same safe-by-default contract as register_idea_scout.ps1 and /super-loop.

.\tools\register_scout_loop.ps1                 # install, PLAN-mode daily (spawns nothing)
.\tools\register_scout_loop.ps1 -Action status
.\tools\register_scout_loop.ps1 -Launch -At 10:30   # go live: one detached study pass/day, after the 09:00 idea-scout

Because each fire spawns a Claude session, the launch path keeps the dispatch_preflight.py no-DoS cap intact (launch_goal_detached.ps1 re-checks SPAWN_OK per spawn) — never route around it with -SkipPreflight.

The honesty boundary (do not cross)

• A crawl is not a borrow; a study is not a ship. This loop files triaged, witnessed backlog. It NEVER reports an issue resolved — ancestry (Fixes #N on the trunk) does that. It hands its filed leaves to the dispatch loop / /super-loop, which resolve them.
• Every borrow cites a real path:line@sha in an actually-cloned source, never a README claim — the dos_citation_resolve fabrication class /study-repo exists to catch.
• Witness before file. A PARTIAL/ABSENT is grounded in a dogfood witness; a PRESENT is dropped, not filed. "fak already has this" is a complete pass.
• Decompose, never a monolith. No "adopt everything from repo X" leaf — the ship-alone test decides.
• One lead per pass. The anti-storm bound; the loop's throughput is a cadence, not a batch.
• Clone into scratch, never C:\work\fak. The foreign tree must never be committable (the *scratchpad* gitignore is a backstop, not the plan).

What "done" proves (per pass)

• One repo-shaped lead was cloned and read at a pinned @sha; every filed borrow cites real code.
• Each filed leaf carries a source path:line@sha, a fak seam, a dogfood witness (PRESENT/PARTIAL/ABSENT), and a first checkable step; PRESENT cases were dropped, not re-filed.
• No monolith was filed; the work is small independently-shippable leaves under the right epic.
• The pass is registered: a dated docs/notes/CONCEPT-STUDY-* note + its INDEX.md line; fak index freshness reads clean.
• If unattended: the FleetScoutLoop fire is witnessed in the loop ledger (fak loop status), and no issue was reported "resolved" by the loop.

Anti-patterns

• ❌ Re-implementing the crawl (re-scanning arXiv) or the study (re-reading the clone logic) — drive idea-scout / /study-repo / /field-borrow, don't duplicate them.
• ❌ Studying a batch of leads in one pass — one lead, then stop; the cadence is the throughput.
• ❌ Filing a borrow you did not locate at a real path:line@sha, or the "adopt repo X" monolith.
• ❌ Filing a PRESENT capability fak already ships — the witness step exists to drop it.
• ❌ Cloning the foreign repo into the fak tree, or leaking an absolute path / host / secret from it into a fak ticket.
• ❌ Installing the scheduled task with -Launch before a plan-mode fire is witnessed, or passing -SkipPreflight to route around the no-DoS cap.
• ❌ Reporting a filed leaf as "resolved" — a crawl/study is not a ship; ancestry is.
• ❌ Inventing a lead when the crawl is empty — a clean empty pass is the correct result.

When NOT to use

• You were handed one specific repo. Go straight to /study-repo; the loop is overhead for a single known lead.
• You have a named capability to check. Use /field-borrow directly.
• You want to resolve the backlog, not grow it. That's /super-loop / /dos-dispatch — the resolve side of the loop, which consumes what scout-loop files.
• The idea-scout queue and the field scans are empty/stale with nothing new. Nothing to convert — an empty pass, not a forced study.

Honest limits

• The witness is lexical + a snapshot. fak_feature_query's ranker is substring matching (false-ABSENT risk) and its verdict is true only as of today — re-witness before acting on an old pass (same caveat as /field-borrow / /study-repo).
• The crawl is only as fresh as its feeders. If FleetIdeaScout hasn't run, the triage queue is stale; the loop studies what's there, it does not force a re-scan.
• Composes with, does not replace: idea-scout (the feed), /study-repo (the acquisition front-half it drives), /field-borrow (the witness+file back-half), /industry-score (a witnessed PRESENT/PARTIAL/ABSENT is a coverage row it can absorb), /super-loop (resolves the leaves this loop files).