Invocation Input

Read arguments supplied by the active harness. If none were supplied, use --stale. If the host supplied an unsubstituted argument placeholder, ask for one supported scope before inventorying, spawning workers, or writing.

Refresh Research

Orchestrate parallel research-curator agents to bulk-refresh research entries in ./research/. Detects staleness, skips fresh entries, updates only what qualifies. Safe to run repeatedly.

Arguments

Supplied arguments control scope:

• --all — Refresh every entry regardless of staleness
• --stale (default) — Refresh entries past their review date
• --category <name> — Refresh all entries in one category (e.g., --category agent-frameworks)
• --layer <0|1|2> — Refresh entries whose frontmatter carries a matching metadata.layer (0=process, 1=language, 2=stack). The current entry template stores no layer field, so this matches only entries that carry one. See plugins/development-harness/docs/sdlc-layers/.
• --dry-run — Report what would be refreshed; do not spawn agents

Workflow

Step 1: Inventory and Staleness Detection

Glob ./research/**/*.md (exclude README.md). For each entry, parse:

1. YAML frontmatter — extract metadata.layer value (string "0", "1", or "2"; null if absent).
2. Freshness tracking — extract Last Verified and Next Review dates from the frontmatter freshness_tracking mapping (last_verified, next_review); when absent, from a body Freshness Tracking section (legacy entries).

flowchart TD
    Start([Read entry]) --> ParseFM[Parse YAML frontmatter<br>Extract metadata.layer]
    ParseFM --> HasFreshness{Freshness tracking found in frontmatter or legacy body section?}
    HasFreshness -->|No| Stale1[STALE: no tracking]
    HasFreshness -->|Yes| ComputeDays[Compute Days Old = today minus Last Verified]
    ComputeDays --> PastDue{Next Review Recommended < today?}
    PastDue -->|Yes| Stale2[STALE: past review date]
    PastDue -->|No| TooOld{Last Verified > 6 months ago?}
    TooOld -->|Yes| Stale3[STALE: too old]
    TooOld -->|No| Fresh[FRESH: N days until next review]

Build inventory table: | File | Category | Layer | Last Verified | Next Review | Days Old | Stale? |

The Days Old column holds an integer: today's date minus the Last Verified date in days. If Last Verified is absent or unparseable, render as —.

The Layer column holds the metadata.layer value or — if absent.

Step 2: Apply Scope Filter

Apply filters sequentially. Filters combine with AND logic — each filter narrows the set from the previous step.

1. Base set: Start with all inventoried entries.
2. Staleness filter (default unless --all):
   • --all — keep all entries (no staleness filter)
   • --stale (default) — keep only entries marked STALE in Step 1
3. Category filter (optional): --category <name> — keep only entries whose category directory matches <name>.
4. Layer filter (optional): --layer <0|1|2> — keep only entries where metadata.layer equals the requested value. Entries without layer metadata (— in inventory) are excluded.
5. Dry-run check: --dry-run — display the filtered target list and stop without spawning agents.

If zero entries remain after all filters: report "No entries match the applied filters." and stop. When --layer was specified and zero entries match, additionally report: "No entries found for layer {N}. Only entries carrying metadata.layer in their YAML frontmatter can be targeted by --layer."

When the --stale filter excludes entries because they are FRESH, list each excluded entry before continuing to Step 3:

Skipped (fresh):
  ./research/{category}/{name}.md — N days until next review (last: YYYY-MM-DD, vX.Y.Z)
  ./research/{category}/{name}.md — N days until next review (last: YYYY-MM-DD, vX.Y.Z)

This listing appears regardless of whether --dry-run is active. Under --all (no staleness filter), no entries are excluded by staleness, so this block does not appear.

Step 3: RT-ICA Pre-Flight

RT-ICA: Research Refresh
Goal: Refresh {N} research entries with current data from primary sources
Conditions:
1. At least one primary-source search/read route is available in this session
   (for example Ref-local search/read, another authenticated documentation reader, or an
   accessible upstream repository clone). Do not require Exa when it is unavailable.
2. Outbound network access is available for the selected route, or the worker can report the
   exact unavailable source without inventing content.
3. ./research/ is writable and entry files are parseable markdown.
4. GitHub metadata is gathered only when needed and an authenticated route is available;
   repository-clone content remains the documented fallback.
Decision: {APPROVED | BLOCKED}

If no primary-source search/read route is available, report BLOCKED with every unavailable route and stop before spawning workers. Otherwise approve the available route and let the curator's native source-access fallback govern individual inaccessible sources; never use training-data knowledge as a fallback.

Step 4: Baseline, Then Spawn Curators in Waves

Capture the curator's Mode Routing baseline before any write. Then route the refresh through its Rerun Mode: split targets into sequential waves of five, launch the available research-curator role once per entry with --rerun ./research/{category}/{name}.md, and wait for every result before starting the next wave. On Claude Code select the available project agent; on Codex select the native research-curator role. Preserve the exact prompt and structured result. Apply the curator's Failure Recovery to every failed, timed-out, or unchanged worker result before it enters Step 5.

After each wave, log results:

Wave {N} complete: {M}/{total} succeeded
  updated -- ./research/agent-frameworks/agno.md (v0.3->v0.5)
  failed  -- ./research/developer-tools/orbstack.md -- error: [reason]

Outcome categories: Updated (content changed) and Failed (agent could not complete, or left the target unchanged, which the curator treats as a failed refresh).

Step 5: Validate, Review, README, Commit

After all waves complete, follow the curator's Rerun Mode from the Validation Gate onward over the updated entries, then its Post-Actions. Entry Review, cross-referencing, README rows and the commit rules are the curator's and are not restated here. No Overlap Scan runs on refresh.

Step 6: Summary Report

# Research Refresh Report

**Date**: {YYYY-MM-DD}
**Scope**: {--all | --stale | --category X | --layer N}
**Total scanned**: {N} | **Targeted**: {M} | **Skipped (fresh)**: {K} ({min}–{max} days until next review)

## Results

| Outcome | Count | Notes |
|---------|-------|-------|
| Updated | {N} | |
| Failed | {N} | |
| Skipped (fresh) | {K} | {min}–{max} days until next review |

When K = 0, omit the Skipped (fresh) row. When K = 1, Notes column: `{N} days until next review`.
When K = 0 in the header: `**Skipped (fresh)**: 0`. When K = 1: `**Skipped (fresh)**: 1 ({N} days until next review)`.

## Updates

| Entry | Category | Change Summary |
|-------|----------|----------------|
| {name} | {category} | {version bump, snapshot change} |

## Failures

| Entry | Error |
|-------|-------|
| {name} | {reason} |

## Curator Output

Append the curator's [Rerun Mode Output](../research-curator/SKILL.md#rerun-mode-output) verbatim: Entry Review verdicts, with-issues counts, and Cross-References Added.

## Next Actions

- Due for review in 30 days: {list}
- Categories with no recent updates: {list}
- Failed entries to retry: {list}

Error Handling

• No entries match filter — report "All entries are fresh. Nothing to refresh." and stop
• No entries match --layer filter — report "No entries found for layer {N}. Only entries carrying metadata.layer in their YAML frontmatter can be targeted by --layer." and stop
• Agent failures, timeouts, unchanged targets, shared-cause outages — follow the curator's Failure Recovery; include remaining failures in the summary Failures table

Related

• research-curator — single-entry and batch research operations; this skill reuses its Rerun Mode, validation, review, relay, and post-actions.
• Research execution route — Claude Code selects the available research-curator project agent; Codex selects .codex/agents/research-curator.toml. The selected role inherits the parent session's model, tools, permissions, and MCP configuration.