last30days Skill

The method for citing sources depends on whether the host environment supports hidden links (like Claude Code) or visible URLs (like Codex, Cursor, or Gemini CLI).

1. Hidden-link hosts (e.g., Claude Code)

• Detection: CLAUDECODE environment variable is set.
• Format: Use inline Markdown links for every citation: [name](url).
• Example: per [Rolling Stone](https://www.rollingstone.com/...) or [r/hiphopheads](https://reddit.com/r/hiphopheads).

2. Visible-URL hosts (e.g., Codex, Cursor, Gemini CLI, raw CLI)

• Detection: CLAUDECODE environment variable is unset.
• Format: Use plain text labels without Markdown links to avoid "URL soup."
• Example: per Rolling Stone or per r/hiphopheads.

General Citation Rules:

• Never use raw URL strings (e.g., per https://...).
• Never use empty links (e.g., [Name]()).
• If a URL is missing for a specific source, fall back to a plain label.

To run research through a configured remote API instead of local sources, set both LAST30DAYS_API_KEY and LAST30DAYS_API_BASE (the endpoint URL).

Important considerations:

• Privacy Exception: If --corpus or LAST30DAYS_CORPUS_DIRS is configured, the engine bypasses the hosted backend and runs locally to ensure file-derived input is not forwarded.
• Output Format: Remote endpoints do not return the local Report object. To get the server's response, use the flags --emit=json --json-profile=raw.
• Error Handling:
  • Exit Code 3: The API has asked a clarifying question. The question and options will be printed to stderr. You must present these to the user and re-run the command with the chosen angle included in the topic.
  • HTTP 402 (Insufficient Credits): The engine will print the account balance, the amount needed, and a billing link. Relay these details to the user verbatim; do not fall back to WebSearch-only synthesis.

export LAST30DAYS_API_KEY="your_key"
export LAST30DAYS_API_BASE="https://api.example.com"
python3 scripts/last30days.py --emit=json --json-profile=raw <topic>

The project maintains a strict distinction between two types of CI checks:

1. Standard PR CI Gates: These are deterministic, offline-safe, and contract-shaped. They include pytest (offline-safe), plugin-contract checks, version-consistency contracts, and linting (e.g., ruff). These run automatically on every PR.
2. Search-Quality Evaluation: This is non-deterministic and requires live API access. It is not included in the default validate.yml workflow to avoid high costs, latency, and flaky signals.

Best Practices for Contributors/Maintainers:

• Do not wire evaluate_search_quality.py into the default validate.yml workflow.
• Do use workflow_dispatch (manually-dispatched workflows) or label-gated runs to trigger evaluations.
• Do run the evaluation locally before submitting a PR to get signal on quality changes.
• Do request a manual evaluation during code review if a PR affects the retrieval or ranking logic.

Reddit search is performed using the OpenAI Responses API with the web_search tool, specifically filtered to the reddit.com domain. The process involves:

1. Subject Extraction: The model strips noise words to find the core topic.
2. Patterned Searching: It searches using three patterns: "{topic} site:reddit.com", "reddit {topic}", and "{topic} reddit".
3. JSON Extraction: The model returns title, url, subreddit, date, and relevance.
4. Validation: URLs must contain both /r/ and /comments/ to ensure they are real threads.

Model Fallback Chain: If an access error occurs (HTTP 400/403), the system automatically falls back through this chain: gpt-5.2 → gpt-5.1 → gpt-5 → gpt-4.1 → gpt-4o → gpt-4o-mini.

{
  "model": "gpt-5.2",
  "tools": [{
    "type": "web_search",
    "filters": { "allowed_domains": ["reddit.com"] }
  }],
  "input": "Search Reddit for threads about {topic}..."
}

The Checkpointed Discovery Protocol is an architecture pattern used when the primary consumer of a tool is a frontier reasoning model (an Agent) rather than a programmatic client. Instead of the tool performing its own LLM-based judgment (which can lead to silent failures or degraded heuristic fallbacks), the tool pauses at specific stages and persists state into versioned checkpoint files. The hosting model (the Agent) is then responsible for performing the semantic judgment (naming, classification, scoring) between tool invocations.

This protocol is mandated by LAW 11: "YOU ARE THE JUDGE" in the project's SKILL.md.

The Three-Leg Pipeline Workflow

1. Leg 1: Nomination

   • Command: --discover --nominate-only
   • Action: Sweeps sources and writes a nominations bundle.
   • Host Task: The host model reads the bundle and writes a judgments file.

2. Leg 2: Enrichment

   • Command: --discover --judgments <file>
   • Action: Resumes using the provided judgments file, performs deep enrichment, and writes a pending report.
   • Host Task: The host model reads the report and writes an angles file.

3. Leg 3: Finalization

   • Command: --discover --finalize [--angles <file>]
   • Action: Renders the final report offline.

When to use this pattern

• When the tool's consumer is an Agent (e.g., Claude Code, Codex, Gemini).
• When a pipeline stage requires semantic judgment that only an LLM can provide.
• When you want to avoid silent heuristic fallbacks for keyless users.
• When you need to persist state across multiple CLI invocations while a host model performs reasoning in between.

# Leg 1: Generate nominations
last30days --discover --nominate-only

# Leg 2: Resume with host-provided judgments
last30days --discover --judgments <path_to_judgments_file>

# Leg 3: Finalize report
last30days --discover --finalize [--angles <path_to_angles_file>]

The system uses fuzzy matching to identify topics even when LLM-generated names drift between runs.

Key Behaviors:

• Annotate-only: A fuzzy match only adds context to the rendered output (e.g., Pipeline: surfaced Nth time, marked covered). It never merges or rewrites existing rows in the database. This prevents a false-positive match from causing unrecoverable data loss by collapsing two distinct stories into one.
• Threshold: Matching is performed using entity_key token overlap or anchor-token overlap. The default threshold is 0.6.
• Two-Phase Matching: To prevent a topic from matching a sibling row created in the same run (which would falsely report it as a repeat), the system performs a two-phase operation:
  1. Phase 1: Match all topics in the current report against the database to compute priors.
  2. Phase 2: Record the surfacings for the current run.

This ensures that if a single report contains two similar topics, neither is incorrectly flagged as a 'repeat' of the other.

# Threshold constant in skills/last30days/scripts/store.py
DISCOVERY_QUEUE_OVERLAP_THRESHOLD = 0.6

The last30days-skill project is built on three core abstractions that define how an agent interacts with the research capabilities:

• Skill: The unit of distribution. It is a self-contained package following the Agent Skills format, consisting of a SKILL.md (the agent-facing prose contract) and a scripts/ directory (the executable code).
• Engine: The implementation layer. Specifically, the Python script scripts/last30days.py that performs the actual research. The SKILL.md instructs the agent on which flags to pass to the Engine (e.g., --plan, --subreddits, --emit=compact), and the Engine returns a specific output shape that the agent must pass through.
• Harness: The agent runtime (e.g., Claude Code, Cursor, GitHub Copilot, Gemini CLI) that loads the Skill and executes it on the user's behalf.

To ensure a Skill is "multi-harness," avoid hardcoding paths specific to one runtime and ensure all Engine flags are properly integrated into the SKILL.md instructions.