--- name: scout-loop description: The super-loop that closes the research→backlog loop — it chains the outward CRAWLERS (the daily `idea-scout` arXiv/GitHub feed, the industry scans, the RESEARCH/CONCEPT corpus) into the STUDY pipeline (`/study-repo` → `/field-borrow`) and runs the whole thing on a cadence. The crawler surfaces repo-shaped leads into a needs-triage queue and stops; turning any one into scoped, witnessed, license-clean backlog is still a manual pass someone has to remember to run. This skill is that seam, automated: once per pass it CRAWLS the freshest outward signal, SELECTS the single highest-value repo-shaped lead, STUDIES it with `/study-repo` (clone into scratch, pin the SHA, read the code not the pitch, decompose small), WITNESSES each borrow with `/field-borrow` (`fak_feature_query`/`fak index` → PRESENT/PARTIAL/ABSENT), FILES the surviving PARTIAL/ABSENT borrows as small independently-shippable leaves under the right epic, and REGISTERS a dated `CONCEPT-STUDY-*` note. It re-implements none of those tools — it orders them, and holds the honesty boundary: a crawl is not a borrow, a study is not a ship. Set it to run unattended with `tools/register_scout_loop.ps1` (plan-by-default, `-Launch` the opt-in). Use when the operator says "keep scouting for new research and turn it into backlog", "run the study loop on new repos", "combine the crawlers with study-repo", "auto-triage the idea-scout queue into real tickets", or "set the research loop running". allowed-tools: Read, Bash, Write metadata: opencode: claude-only # the commit-by-explicit-path, honesty-boundary, no-monolith, and scratch-only-clone discipline are load-bearing and not portable per-skill --- # /scout-loop — crawl the field, study the best lead, file witnessed backlog > **The research→backlog super-loop.** fak already has an outward crawler > (`tools/idea_scout.py` files deduped `idea-scout` triage issues from arXiv + > GitHub) 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 | |---|---|---|---| | `idea-scout` (`tools/idea_scout.py`) | an outward **feed** | automated arXiv/GitHub scan + 3-rung dedup | files raw `idea-scout` **triage** issues | | [`/study-repo`](../study-repo/SKILL.md) | one **repo URL** | clone → read the code → decompose | files many small witnessed leaves | | [`/field-borrow`](../field-borrow/SKILL.md) | one **named capability** | dogfood `fak_feature_query`/`fak index` | files one grounded issue | | [`/industry-score`](../industry-score/SKILL.md) | the **field taxonomy** | coverage + parity-debt scorecard | a scorecard (files nothing) | | [`/super-loop`](../super-loop/SKILL.md) | 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. ## The pass — one lead, end to end ### 1 — CRAWL: read the freshest outward signal (don't re-fetch what's cached) The crawler already ran; read its output rather than re-scanning arXiv: ```bash # The idea-scout triage queue — repo/paper leads already deduped + filed: gh issue list --search "label:idea-scout" --state open --limit 30 --json number,title,body,url python tools/industry_scorecard.py --json # competitive map: where parity-debt is highest python tools/industry_freshness_cadence.py --json # what's gone stale / newly moved in the field ``` Also skim the durable corpus for a lead someone already flagged but never studied: `docs/notes/RESEARCH-*` and `docs/notes/CONCEPT-*`. The crawler is the feeder (`docs/dispatch-loop.md` framing: the dispatch loop *resolves*, idea-scout *feeds*); `scout-loop` sits between them — it *consumes the feed and produces the studied backlog* the dispatch loop can then resolve. ### 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. 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) Invoke [`/study-repo`](../study-repo/SKILL.md) 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`](../field-borrow/SKILL.md)'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--.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`. ```powershell .\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).