deep-research

Deep Research — plan first, then multi-channel pull + synthesis

Use when normal web search isn't enough — you need to triangulate across very different source types (reasoning-model lenses and raw platform signal) and surface contradictions, not just retrieve the top-ranked summary.

The edge is QUALITY: native, full-breadth social/community depth — this tool reads the platforms from inside (live X, Telegram communities, the full Reddit archive) and backs every load-bearing claim with a real quote, an author handle, and a clickable live link. A web-index researcher sees only the indexed scraps. "Free/cheaper" is not the pitch — quality is.

STEP 0 — RESEARCH PLAN (mandatory, before any run)

Never fire the connectors cold. Every skill invocation creates one self-contained bundle in the project from which the skill was launched. The meaningful research plan must exist inside that bundle before connector work starts. The rule is: "when you invoke research — the research plan first, then the run."

1. Capture the launch directory before resolving plugin paths, then probe the live connectors from that directory. Never cd into the plugin and accidentally make it the research owner. Resolve SKILL_DIR from the absolute directory containing the loaded SKILL.md; this path is supplied during skill discovery on Codex and other hosts. Do not assume CLAUDE_PLUGIN_ROOT exists, and never execute the placeholder below—replace it with the discovered absolute directory in every shell call:

   LAUNCH_CWD="$(pwd -P)"
   SKILL_DIR="<absolute directory containing the loaded SKILL.md>"
   SCRIPT="$SKILL_DIR/scripts/deep-research.py"
   test -f "$SCRIPT"
   printf 'launch_cwd=%s\n' "$LAUNCH_CWD"
   (cd "$LAUNCH_CWD" && python3 "$SCRIPT" --list-connectors \
       --launch-cwd "$LAUNCH_CWD")
   

   Record the printed absolute path. Shell variables may not survive between tool calls, so later calls must reassign LAUNCH_CWD to this captured literal; do not recalculate it after visiting another directory.
2. Resolve the topic (this is where the quality comes from — borrowed from last30days' pre-research idea). Don't search raw keywords; first name the concrete entities:
   • people → exact @handles (X/GitHub/Bluesky)
   • communities → exact subreddits (r/…), HN, specific orgs
   • repos → owner/name
   • is this a forecastable event? → Polymarket is worth including
   • is this a skills/tech-trend question? → the hiring channel shows whether the job market is heating up on it (resolve the query to 1–2 sharp terms, e.g. RAG, context engineering, not a long phrase)
3. Pick channels + aim each one. Decide which of the 18 connectors run and why each — which channel covers which facet. Write a per-channel query where the default topic string isn't the sharpest aim.
4. Name the contradictions you expect to test — the value of the run is in the disagreements, so say up front what tension you're probing.
5. Show the compact plan, then reserve exactly one run directory through the runner. Use the resolved topic, not an unexpanded placeholder:

   LAUNCH_CWD="/absolute/path/printed-in-step-1"
   SKILL_DIR="/absolute/directory/containing/the/loaded/SKILL.md"
   SCRIPT="$SKILL_DIR/scripts/deep-research.py"
   TOPIC="RESOLVED TOPIC"
   RUN_DIR="$(cd "$LAUNCH_CWD" && python3 "$SCRIPT" "$TOPIC" \
       --allocate-run --launch-cwd "$LAUNCH_CWD")"
   printf 'run_dir=%s\n' "$RUN_DIR"
   

   The default owner is the launch directory's Git top-level, or the captured launch directory outside Git. If a monorepo's Git root is broader than the actual project, pass the intended owner explicitly during allocation:

   LAUNCH_CWD="/absolute/path/printed-in-step-1"
   SKILL_DIR="/absolute/directory/containing/the/loaded/SKILL.md"
   SCRIPT="$SKILL_DIR/scripts/deep-research.py"
   TOPIC="RESOLVED TOPIC"
   PROJECT_ROOT="/absolute/path/to/intended/project"
   RUN_DIR="$(cd "$LAUNCH_CWD" && python3 "$SCRIPT" "$TOPIC" \
       --allocate-run --launch-cwd "$LAUNCH_CWD" \
       --project-root "$PROJECT_ROOT")"
   printf 'run_dir=%s\n' "$RUN_DIR"
   

   Allocation writes only _topic.txt, which binds the reservation to the exact topic. It does not start connectors.
6. Write research-plan.md inside the absolute run path printed in step 5 before starting connectors. Use the normal file-writing tool, not a placeholder shell echo. The plan must name the resolved topic/entities, research questions and scope, selected channels with rationale, exact per-channel queries, expected contradictions, and what evidence would answer the request. Record the captured launch directory and any explicit project-root choice.
7. Run connectors into that exact directory. Do not allocate a second run and do not derive a path independently:

   LAUNCH_CWD="/absolute/path/printed-in-step-1"
   SKILL_DIR="/absolute/directory/containing/the/loaded/SKILL.md"
   SCRIPT="$SKILL_DIR/scripts/deep-research.py"
   TOPIC="RESOLVED TOPIC"
   RUN_DIR="/absolute/path/printed-in-step-5"
   (cd "$LAUNCH_CWD" && python3 "$SCRIPT" "$TOPIC" \
       --launch-cwd "$LAUNCH_CWD" --output-dir "$RUN_DIR" --prepared-run)
   

   Add --only, --skip, and repeated --q name:query options from the written plan. Afterward, read the reports and write synthesis.md beside research-plan.md; if a brief is useful, render it there too:

   SKILL_DIR="/absolute/directory/containing/the/loaded/SKILL.md"
   SCRIPT="$SKILL_DIR/scripts/deep-research.py"
   RUN_DIR="/absolute/path/printed-in-step-5"
   python3 "$SCRIPT" --render-html "$RUN_DIR/synthesis.md" \
       --html-out "$RUN_DIR/brief.html"