research-prospect

name	research-prospect
description	Scan active projects and surface /deep-research topic strings per project. Reads MEMORY.md to enumerate projects, fans out parallel Explore agents (one per project) to identify 2-3 high-value research topics each, then renders a grouped copy-pasteable menu. Use when you want token-rich research tasks to hand off to separate windows, or when you want to understand what research would most improve each project.
user-invocable	true

research-prospect

Scan each active project for research gaps and produce a ready-to-run /deep-research menu, grouped by project.

When to use

• You want high-token tasks to distribute across multiple windows.
• You want to understand what research would most improve each project before starting a deep-work session.
• You need a menu of specific, grounded research questions rather than a brainstorm.

When NOT to use

• You already know the topic — skip straight to /deep-research "<topic>".
• You want a deep investigation of one specific project — ask for that directly instead.
• MEMORY.md "Active projects" is known to be stale — run /session-wrap first to update it.

Arguments

Arg	Required	Default	Description
--projects <list>	no	all active projects from MEMORY.md	Comma-separated project names or directory paths. Example: --projects Alpha4Gate,toybox
--session-wrap	no	off	After rendering the menu, invoke /session-wrap with all topics listed as next-step options.

---

Steps

Step 1: Resolve project list

If --projects was provided: parse it as a comma-separated list. Each item is either a project name (look up under <workspace>/<name>/) or an absolute path.

If --projects was not provided: read MEMORY.md from ~/.claude/projects/<project>/memory/MEMORY.md. Locate the "Active projects" section. Extract every project name listed there. For each, derive its directory: check <workspace>/<name>/ (case-insensitive). Capture the one-line MEMORY.md entry for each project — this feeds the agent as background context.

Warn and skip any project whose directory cannot be resolved. Do not halt.

Emit one line before Step 2: Scanning N projects: <names>.

---

Step 2: Fan out parallel Explore agents

Dispatch all agents in a single parallel message — one Explore agent per project. Do not wait for one to finish before dispatching others. Parallel dispatch is the primary throughput gain of this skill; sequential dispatch is a defect.

Each agent receives the following prompt (fill in the bracketed fields):

Investigate <PROJECT_NAME> at <PROJECT_DIR> to identify 2-3 specific /deep-research topics that would meaningfully improve the project.

Background from workspace memory: <MEMORY_LINE — the one-line MEMORY.md entry, or "not in memory" if absent>

Read in this order (stop when you have enough context):
1. <PROJECT_DIR>/CLAUDE.md — stack, commands, known gotchas
2. <PROJECT_DIR>/documentation/master_plan.md or plan.md — current phase/step status
3. git -C "<PROJECT_DIR>" log --oneline -15 — recent work
4. Any open investigation docs under <PROJECT_DIR>/documentation/investigations/

Focus on: algorithmic gaps, known plateaus, open architectural questions, techniques the plan defers to "future phases", quality or accuracy limitations surfaced in UAT, or infrastructure decisions where research would inform a go/no-go gate.

Return ONLY a JSON object (no prose before or after it):

{
  "project": "<PROJECT_NAME>",
  "current_state": "<one sentence: what is built and where it is stuck>",
  "research_topics": [
    {
      "title": "<research question phrased as a /deep-research argument — 12-25 words, specific and searchable>",
      "why": "<1-2 sentences citing a specific gap in the codebase, plan, or recent git history>",
      "depth": "high|medium"
    }
  ]
}

Rules:
- 2 topics minimum, 3 maximum.
- Titles must work as /deep-research arguments: specific, concrete, not generic phrases like "improve performance" or "better algorithms."
- "why" must cite something observed in the code, plan doc, or git log — not general best-practices reasoning.
- If the directory does not exist or has no readable files, return: {"project": "<name>", "error": "directory not found or empty"}.

Collect all results. Projects that return "error" are logged under a Skipped line in the output but do not halt rendering.

---

Step 3: Render the menu

For each project with valid results, render a group:

## <PROJECT_NAME> — <current_state>

  X1: /deep-research "<title>"
      Why: <why>

  X2: /deep-research "<title>"
      Why: <why>

  X3: /deep-research "<title>"   (if present)
      Why: <why>

Where X is a single-letter prefix: first letter of the first word of the project name, uppercased. If two projects share the same letter, use a two-letter prefix for the second (e.g., VO for void_furnace if VF was already used).

After all groups, emit a flat "QUICK COPY" block:

--- QUICK COPY (one per window) ---
/deep-research "<A1 title>"
/deep-research "<A2 title>"
...

The quick-copy block is mandatory regardless of topic count — it lets the user grab a single line per window without stripping the "Why" annotations.

---

Step 4 (only if --session-wrap flag passed)

Immediately invoke /session-wrap after Step 3 output. Pass the full topic list (all /deep-research "..." invocations, grouped by project) as the next-step options argument. One-sentence transition max before the skill call — do not emit verdict prose summarizing what was found.

---

Output format

• Target: 20–70 lines for the full menu.
• Do not truncate topics to hit a word count. Accuracy over brevity.
• The QUICK COPY block always appears at the end, even if only one project was scanned.

---

Constraints

• Parallel dispatch required. All Explore agents in one message. Sequential dispatch is a defect.
• JSON only from agents. Agents returning prose instead of JSON are treated as parse failures. Log the project as skipped with a note; do not try to extract topics from prose.
• "why" must be grounded. If an agent's "why" reads as generic best-practice advice with no codebase anchor, mark it (unverified — no specific gap cited) rather than presenting it as a confirmed finding.
• Title phrasing discipline. Reject titles that are generic. A usable title names the technique, the constraint, and the domain: "SPRT early-stopping thresholds for small-n win-rate gates in game-playing bot evolution" not "statistical testing for bot evaluation."
• No invented projects. Only scan projects listed in MEMORY.md or explicitly named via --projects.

---

Limitations

• MEMORY.md must be current. Projects not listed under "Active projects" are invisible to this skill unless named via --projects. If MEMORY.md is stale, run /session-wrap first.
• Explore agents read excerpts, not whole files. On large plan.md files (>2000 lines), agents see early sections first. Open investigations buried deep in the plan may be missed. Use --projects <name> with a more focused prompt if a specific project needs deeper coverage.
• Directory name must match MEMORY.md entry exactly. If a project is listed as b2_project_goblin but the directory is goblin/, resolution will fail. Fix MEMORY.md or use --projects <workspace>/goblin.
• Agent JSON format is best-effort. Explore agents are not constrained-output models. If an agent returns valid JSON with the right keys, use it. If it returns close-enough JSON (minor key differences), parse it gracefully. Only escalate to "skipped" if the output is unparseable.