mvanhorn__last30days-skill/CONCEPTS.md

Concepts

Shared vocabulary for last30days-skill. Terms here have a precise project-specific meaning — distinct enough from their general technical sense that a new contributor would need them defined to follow conversations, PR descriptions, or the SKILL.md contract.

The package

Skill

A self-contained agent-instructions package consisting of a SKILL.md prose contract plus a sibling scripts/ directory containing the executable code the SKILL.md invokes. The package conforms to the Agent Skills open format and installs across every major harness (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and 50+ others) via npx skills add, harness-native plugin installers, or per-harness skill directories. A Skill is the unit of distribution; the Skill is the product.

Engine

The Python script (scripts/last30days.py) the Skill's SKILL.md invokes to do the actual research work. The Engine and SKILL.md have a contract: SKILL.md tells the model which flags to pass (--plan, --competitors-plan, --x-handle, --subreddits, --emit=compact, etc.), and the Engine produces a specific output shape (badge line, ranked evidence clusters, emoji-tree footer) that the model is contractually required to pass through. The Engine is implementation; the SKILL.md prose is the agent-facing surface.

Harness

The agent runtime that loads Skills and invokes them on the user's behalf. Claude Code is the most common Harness for this Skill but not the only one — Codex, Cursor, GitHub Copilot, Gemini CLI, and the rest of the Agent Skills ecosystem also count. "Multi-harness" describes a Skill that works correctly across every Harness it installs into; features written without multi-harness awareness (e.g., engine flags with no SKILL.md integration, or paths hardcoded to one Harness's install layout) regress on Harnesses other than the one they were tested against.

Research pipeline

Primary entity

The brand or proper-noun core of a research topic — the topic with its Intent modifier stripped. It is what the research is about, as distinct from how the user phrased the search.

Intent modifier

A trailing word or phrase in a topic that expresses what the user wants to know rather than what the topic is ("review", "use cases", "pricing"). Stripped when deriving the Primary entity.

Entity grounding

The check that a candidate item plausibly mentions the Primary entity before final ranking. Grounding keys on the head token (first word) of the Primary entity rather than the full phrase — trailing words are usually search descriptors, so requiring them falsely demotes on-entity items.

An item that fails grounding receives a decisive entity-miss demotion, designed so engagement cannot rescue off-entity content. Because the demotion is decisive, the grounding bar is deliberately conservative: its failure modes degrade toward "no penalty," never toward burying on-entity signal.

Subquery stream

One source's ranked result list for one planner subquery. A run fans out into several subqueries, and each subquery queries each source separately, so the same thread can appear in several streams. A stream orders and truncates its own items and assigns them positional labels, so a label is only meaningful inside its stream; identity across streams is the item's normalized URL.

Candidate

The fused unit of evidence that ranking, clustering, and rendering operate on: every copy of one item across all Subquery streams, merged by normalized URL into a single record that carries the copies' combined rank evidence. When copies of the same item differ in what they carry (one stream fetched its comments, another did not), the candidate keeps the richer version rather than the first one seen.

Keyless path

The research flow available with no API keys: source data is gathered by scraping and RSS rather than authenticated APIs, and ranking falls back to local scoring instead of LLM-based reranking. This is the free tier of the Skill; lexical quality safeguards like Entity grounding matter most here, because no LLM is available to judge relevance semantically.

Comment-enrichment slots

The small, depth-dependent budget of Reddit posts whose comments get fetched in the Keyless path (4 / 8 / 12 per subquery at quick / default / deep). Slot selection is relevance-aware and comment-first: posts that pass Entity grounding claim slots first, and within that tier the most-commented threads go first, so the budget is not spent on high-engagement posts that final ranking will demote or on near-empty threads.

Engagement keeper

A Reddit thread that clears the relevance floor, passes Entity grounding, and ranks in the top three of its stream by upvotes plus comments. Keepers survive per-stream truncation regardless of their local rank score, and the fused candidate pool reserves a few slots (2 / 3 / 4 by depth) for the same class of thread, so the month's most-discussed on-topic threads reach the ranked output even when their title overlap with the query is weak. When the Primary entity's head token is generic ("ai", "new"), the floor rises so viral off-topic threads cannot claim the slots.

Discovery

Discovery

The topic-less research mode: instead of researching a named topic, it finds what is worth researching. On a reasoning-model host it runs as a three-leg host-judged protocol: leg 1 sweeps the river listings and writes a nominations bundle, the host judges every Nomination (name, junk, worthiness) into a judgments file, leg 2 resumes from the bundle and runs the Enrichment passes, and leg 3 applies host-written content angles and renders the brief. Headless/cron runs keep the one-shot form - same sweep and enrichment, deterministic heuristics in place of the judge, no angles. Either way every surviving topic must clear the Confidence floor before it is shown. Global Discovery (no domain given) sweeps every river feed's own hot list with no keyword gate; domain Discovery scopes and keyword-gates the sweep.

Nomination

A named candidate topic produced by Discovery's listing sweep: clustered items from the river feeds, given a short searchable name plus a Junk shape flag and a content-worthiness score that blends into its seed rank. On protocol runs the hosting model judges all three via the judgments file - the engine's deterministic heuristics only fill rows the host left absent; on headless one-shot runs deterministic distillation supplies the name and junk flag and no worthiness signal exists. A Nomination is only a candidate - its blended seed rank decides which topics deserve an Enrichment pass and the display order of survivors; the Confidence floor judgment and the displayed velocity score are computed from the enriched evidence, never the seed score. The Nomination's name doubles as its Enrichment pass search query and its research handoff, so naming happens before enrichment, never at render time.

Handoff checkpoint

The persisted state that lets Discovery's protocol pause for host judgment and resume in a later invocation: the nominations bundle (the full judge pool with its seed evidence, written by leg 1, awaiting the host's judgments) and the pending report (the enriched, floored, ranked round written by leg 2, awaiting the host's angles). A checkpoint is identity-bound - every host-written file must echo the checkpoint's bundle id, and a mismatch is a fix-the-id-and-retry error, never a redo of the expensive leg - and time-bound by its own TTL so a stale round is rejected rather than resumed. Checkpoints also carry provenance the resume legs enforce: mock and real state never cross, degraded sweep coverage survives into later legs instead of reading as clean, and an explicitly scoped store is the only place its checkpoints are looked for. Structurally empty checkpoint state is treated as corruption and fails closed - it never becomes an authoritative-looking empty result.

Enrichment pass

A full research-pipeline run executed on one Nomination's topic name during Discovery. This is what gives a trend card the whole multi-source corpus (community comments, prediction markets, keyword-driven sources that have no hot-list of their own) instead of thin listing evidence. Enrichment passes run in parallel against a wall-clock budget; a pass that fails or outruns the budget downgrades its topic to nomination-only evidence, never fails the run.

Confidence floor

The absolute evidence bar every Discovery topic must clear before it may rank: an engagement junk-gate first, then either independent cross-source corroboration or a genuinely strong single-source spike. Topics with a Junk shape get a stricter read: the single-source spike bypass is off, and their corroboration is counted against the seed listing sources the sweep actually found - never the enriched corpus, because an Enrichment pass makes almost any topic look multi-source. The floor is absolute, not relative to the current pool - a relative bar would degrade with the pool, which is the failure it exists to prevent. Its thresholds are deliberately tunable; the behavior contract is only that sub-floor evidence never ranks.

Nothing-solid

The honest empty outcome of a Discovery run in which zero topics cleared the Confidence floor. A first-class result, not an error: the run reports that nothing in the window was strong enough to call a trend, and names the closest sub-floor candidate (the weak signal, preferring a non-junk-shaped one) so the user knows where the signal petered out. Rendering junk instead of Nothing-solid is the named failure this outcome replaced.

Junk shape

A classification applied to a Nomination whose leading item reads as a help-me question, beginner ask, or personal musing rather than a story - the post shapes that engagement alone cannot distinguish from news. Its force depends on who flagged it: a host junk verdict is authoritative and excludes the Nomination from Enrichment passes outright (it can still appear as the weak signal in a Nothing-solid brief), while a heuristic junk shape on a row the host never judged only removes the Confidence floor's single-source bypass, so that topic surfaces solely with independent seed-source corroboration.

Topic queue

The persistent memory of what Discovery has surfaced: each surfaced topic is recorded per research store, so later runs can annotate repeats ("surfaced Nth time") and the user can mark stories Covered. On by default for every real Discovery run, with an engine toggle to disable; mock runs never write it.

Identity in the queue is annotate-only: a new topic name that closely matches an earlier row (exact normalized match, else entity overlap) annotates the rendered card but never merges or rewrites rows - a false match costs one noisy line, never a hidden story. Queue annotations always describe the state before the current run, and a failed queue write degrades to a warning; it must never destroy a finished run's output.

Covered

The user-set status on a Topic queue row meaning "I already produced content for this story." Set by marking a topic covered by its exact name; surfaced is the only other status. A resurfacing never un-covers a row, and a new name that fuzzily matches a Covered row is born Covered - so the mark survives the judge (now the hosting model) renaming the same story across runs instead of silently re-pitching it.

X source routing

X backend chain

The ordered list of X backends the Engine tries for one run when none is pinned, failing over to the next when one returns nothing. On an ordinary host the chain puts the free browser-session path first and the key-based backends after it. The chain is defined once and read everywhere it is described or predicted, so what doctor says the run will use and what the run actually uses cannot disagree.

Opt-in backend

An X backend that is never part of the unpinned X backend chain and runs only when explicitly selected by the backend pin. The point is that a leftover login or an ambient credential on the machine can never silently claim the X lane, or spend metered credits, on a host that never asked for it. On ordinary hosts the Grok CLI and the direct X API bearer are Opt-in backends.

Extras host

A host class (Linux, a Mac mini, or a machine that opted in explicitly) where the ordinary browser-session extract cannot reach a usable Chrome profile, so the Engine tries additional ways to obtain a complete X session before giving up on the free X path. Membership is decided from named signals only, never inferred from the home directory, PATH, or which Harness is running; a MacBook is never an Extras host unless it opts in.

Official X policy

The host-conditional X routing rule that applies when the Harness identifies itself as a Grok Bot host through the host signal: the unpinned X backend chain contains only licensed backends (the direct X API bearer, xAI's licensed X search, and the X API through X's own CLI), no browser session is discovered or read, and every onboarding, doctor, and repair message names only those paths. The Engine trusts the host's self-identification and never sniffs the host. A backend pin keeps its exclusive meaning on such a host and is the only way to select a backend outside the official chain.

Host-fetched lane

An X result the hosting model fetched itself, through its own X connector, and handed to the Engine as a file (the X connector envelope, passed with --x-posts), which then serves as the run's X source in place of the X backend chain. The envelope is strict at the top level (a malformed, stale, or off-topic file fails closed), lenient per row (a bad row is dropped and counted), and trusted for nothing beyond a numeric post id and a grammar-valid handle: citations are rebuilt by the Engine, never copied from the file. It is single-serve (one run, consumed once) and accepted on any host; a session-level lane signal tells planning that X is available before the file exists.

Flagged ambiguities

• "Enrichment" is used for two distinct things: Comment-enrichment slots (fetching comments for already-ranked Reddit posts in the Keyless path) and Discovery's Enrichment pass (a full research run per Nomination). Context disambiguates; prefer the full term when writing.