菜单
Hook-driven proactive research pipeline. Runs automatically via UserPromptSubmit — there is no slash command to trigger it. This page documents how it works, how to disable it, and the env-var knobs.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | proactive-research |
| description | Hook-driven proactive research pipeline. Runs automatically via UserPromptSubmit — there is no slash command to trigger it. This page documents how it works, how to disable it, and the env-var knobs. |
Every substantive user prompt is fed through a 3-stage background pipeline
that detects external-knowledge gaps in the project wiki and fills them by
dispatching /wiki-ingest against canonical URLs.
user prompt
↓ proactive-research-extract.sh (UserPromptSubmit hook, ≤50ms)
│ filters: WIKI_DRIVER guard, opt-in gate, AGENT_ID guard,
│ slash-command, MIN_TOKENS, rate-limit
│ spawns: detached driver subprocess
↓
proactive-research-driver.sh (background, fire-and-forget)
├─ Step 1: claude -p '/wiki-query <prompt>' (Sonnet)
│ → markdown with Answer / Evidence / Gaps
├─ Step 2: curl Haiku messages API
│ system: templates/classifier.md
│ user: wiki-context + sanitized prompt
│ → {worthy, reason, sources:[{topic,url}, ...]}
└─ Step 3: for each source.url:
claude -p '/wiki-ingest <url>' (Sonnet, detached)
Cost per worthy prompt: 1 Sonnet /wiki-query + 1 Haiku curl + N Sonnet
/wiki-ingest. Cost per not-worthy prompt that cleared the token gate:
1 Sonnet /wiki-query + 1 Haiku curl, then stop.
The hook contract is fire-and-return: filter, fork, exit. All real work happens in the detached driver. The hook never touches an LLM and never writes a queue entry.
The driver invokes claude -p to run /wiki-query and /wiki-ingest. Each
of those would re-trigger UserPromptSubmit and fork-bomb us if not
guarded. The driver runs with WIKI_DRIVER=1 exported into its env; the
producer hook short-circuits at the top when this is set. Removing this
guard breaks the architecture.
Before any external call, the prompt is run through
wiki_sanitize_for_external in wiki-common.sh:
/Users/..., /home/..., /opt/..., etc.).simple-secrets-scan.sh regex set.git ls-files (best-effort).With PROACTIVE_RESEARCH_PRIVACY_STRICT=1, the driver fails closed if
any <repo-local> placeholder is still present after sanitization.
| Variable | Default | Effect |
|---|---|---|
PROACTIVE_RESEARCH_ENABLED | 0 | Opt-in gate — set to 1 per project to enable the producer hook. |
PROACTIVE_RESEARCH_MIN_TOKENS | 7 | Producer skips prompts under this token count (tiktoken if importable, else char/4). |
PROACTIVE_RESEARCH_RATE_LIMIT_PER_HR | 20 | Producer drops prompts beyond this count per UTC hour. |
PROACTIVE_RESEARCH_MAX_SOURCES | 4 | Driver caps the number of /wiki-ingest dispatches. |
PROACTIVE_RESEARCH_PRIVACY_STRICT | 0 | Driver skips if a repo-local identifier remains after sanitization. |
The driver also requires ANTHROPIC_API_KEY for the Haiku curl call. If
unset, the driver logs and exits without dispatching.
Driver stdout/stderr append to ~/.claude/proactive-research/log with one
line per stage:
[2026-05-03T19:41:02Z] driver session:abc12345 step1 /wiki-query: ...
[2026-05-03T19:41:08Z] driver session:abc12345 step2 classify (Haiku)
[2026-05-03T19:41:09Z] driver session:abc12345 WORTHY=true reason="..." sources=2
[2026-05-03T19:41:09Z] driver session:abc12345 dispatch /wiki-ingest https://...
The producer hook also emits a single PROACTIVE driver spawned (tokens=N)
line per dispatch into the wiki's log.md.
Proactive research is opt-in (off by default). To enable for a project,
add PROACTIVE_RESEARCH_ENABLED=1 to the project's .claude/settings.json
env block (or to the shell env). The hook short-circuits silently when
unset, so leaving it off has zero cost.
To temporarily disable on an opted-in project: unset PROACTIVE_RESEARCH_ENABLED
or override via PROACTIVE_RESEARCH_ENABLED=0.
${CLAUDE_PLUGIN_ROOT}/handlers/proactive-research-extract.sh — producer hook.${CLAUDE_PLUGIN_ROOT}/handlers/proactive-research-driver.sh — driver subprocess.${CLAUDE_PLUGIN_ROOT}/templates/classifier.md — Haiku classifier system prompt./wiki-ingest — explicit, foreground source ingestion (the curated path
the driver dispatches into)./wiki-query — synthesis with citations (the driver's Step 1)./wiki-lint — wiki health check.Resolve ambiguous user prompts by choosing whether to answer now, answer with assumptions, ask 1–2 high-value clarification questions, replan, or stop. Use when the best response depends on hidden intent, audience, scope, constraints, risk, output format, or desired depth.
Analyzes an approved plan and decomposes it into a dependency-ordered task graph via a two-phase TaskCreate and TaskUpdate pass. Detects linear DEPENDS ON chains (shared worktree), identifies independent work streams (parallelized), and executes the full worktree-isolated run. Also handles Branch B (learnings from session context). **AUTOMATICALLY INVOKE** only when: - The PostToolUse(ExitPlanMode) hook has injected its schedule-tasks nudge in this turn (i.e., the user just approved a plan), AND the user has not signaled they want to defer execution. - /schedule-plan-tasks is invoked explicitly. - The user explicitly says "schedule tasks", "execute the plan", "decompose plan into tasks" — only when a plan exists at ~/.claude/plans/*.md AND ExitPlanMode has already been approved in this session. **DO NOT auto-invoke** while plan mode is active, while review-plan is iterating, or before the user has approved ExitPlanMode. **References:** JIT-loaded from `${CLAUDE_SKILL_DIR}/references/`
Headless `claude -p` test harness V2 — runs a fixture's literal prompt through real Claude sessions (k replicas in parallel), grades each replica on five string views plus structured tool-call / tool-result / run-health / LLM-judge condition families, then quorum-aggregates row verdicts. Use when an LLM-driven prompt needs behavioral verification beyond contract-string parser tests.
Universal plan review: senior-engineer directive + deterministic count-based severity rule. AUTOMATICALLY INVOKE when: - MANDATORY_PRE_EXIT_PLAN directive applies (before ExitPlanMode) - User says "review plan", "check plan", "plan ready?" - Any plan file needs review NOT for: Code review of existing files (use /gas-suite:gas-review or /review-fix)
Compare an agent or skill prompt against its test harness skill for phase-model, skip-condition, and wiring consistency. Reports mismatches and identifies which file is authoritative.
TDD-based prompt migration — given a target agent/skill prompt and a remediation list from prompt-audit, writes failing tests first, then updates the prompt to make them pass, and commits both in a single atomic commit.