with one click
skill-researcher
Conduct general research using web search, documentation, and codebase exploration. Invoke for general research tasks.
Menu
Conduct general research using web search, documentation, and codebase exploration. Invoke for general research tasks.
Scan codebase for FIX:/NOTE:/TODO:/QUESTION: tags and create structured tasks with interactive selection. Invoke for /fix-it command.
Interactive repository analysis and project-overview.md generation via task creation. Invoke for /project-overview command.
Research blockers and spawn new tasks to overcome them, updating parent task dependencies
Archive completed and abandoned tasks with CHANGE_LOG.md updates and memory harvest suggestions
Execute general implementation tasks following a plan. Invoke for general implementation work.
Create phased implementation plans from research findings. Invoke when a task needs an implementation plan.
| name | skill-researcher |
| description | Conduct general research using web search, documentation, and codebase exploration. Invoke for general research tasks. |
| allowed-tools | Agent, Bash, Edit, Read, Write |
Thin wrapper that delegates general research to general-research-agent subagent.
IMPORTANT: This skill implements the skill-internal postflight pattern. After the subagent returns, this skill handles all postflight operations (status update, artifact linking, git commit) before returning. This eliminates the "continue" prompt issue between skill return and orchestrator.
Reference (do not load eagerly):
.claude/context/formats/return-metadata-file.md - Metadata file schema.claude/context/patterns/postflight-control.md - Marker file protocol.claude/context/patterns/file-metadata-exchange.md - File I/O helpers.claude/context/patterns/jq-escaping-workarounds.md - jq escaping patterns (Issue #1132)Note: This skill is a thin wrapper with internal postflight. Context is loaded by the delegated agent.
This skill activates when:
Validate required inputs:
task_number - Must be provided and exist in state.jsonfocus_prompt - Optional focus for research direction# Lookup task
task_data=$(jq -r --argjson num "$task_number" \
'.active_projects[] | select(.project_number == $num)' \
specs/state.json)
# Validate exists
if [ -z "$task_data" ]; then
return error "Task $task_number not found"
fi
# Extract fields
task_type=$(echo "$task_data" | jq -r '.task_type // "general"')
status=$(echo "$task_data" | jq -r '.status')
project_name=$(echo "$task_data" | jq -r '.project_name')
description=$(echo "$task_data" | jq -r '.description // ""')
Update task status to "researching" BEFORE invoking subagent.
.claude/scripts/update-task-status.sh preflight "$task_number" research "$session_id"
This atomically updates state.json (status, timestamps, session_id), TODO.md task entry, and TODO.md Task Order section. If the script exits non-zero, abort and keep current status.
Create the marker file to prevent premature termination:
# Ensure task directory exists
padded_num=$(printf "%03d" "$task_number")
mkdir -p "specs/${padded_num}_${project_name}"
cat > "specs/${padded_num}_${project_name}/.postflight-pending" << EOF
{
"session_id": "${session_id}",
"skill": "skill-researcher",
"task_number": ${task_number},
"operation": "research",
"reason": "Postflight pending: status update, artifact linking, git commit",
"created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"stop_hook_active": false
}
EOF
Read next_artifact_number from state.json (or fall back to directory scanning for legacy tasks):
# Read next_artifact_number from state.json
artifact_number=$(jq -r --argjson num "$task_number" \
'.active_projects[] | select(.project_number == $num) | .next_artifact_number // 1' \
specs/state.json)
# Fallback for legacy tasks: count existing artifacts
if [ "$artifact_number" = "null" ] || [ -z "$artifact_number" ]; then
padded_num=$(printf "%03d" "$task_number")
count=$(ls "specs/${padded_num}_${project_name}/reports/"*[0-9][0-9]*.md 2>/dev/null | wc -l)
artifact_number=$((count + 1))
fi
artifact_padded=$(printf "%02d" "$artifact_number")
Retrieve relevant memories from the memory system to inject into the delegation context.
Skip if: clean_flag is true in the delegation context (from --clean command flag).
# Check clean_flag
if [ "$clean_flag" != "true" ]; then
memory_context=$(bash .claude/scripts/memory-retrieve.sh "$description" "$task_type" "$focus_prompt" 2>/dev/null) || memory_context=""
fi
# memory_context will be empty string if:
# - clean_flag is true (skipped)
# - memory-index.json missing or empty
# - no keywords matched any entries
# - script exited with error
If memory_context is non-empty, it will be injected into the Stage 5 prompt alongside the format specification from Stage 4b. If empty, no memory block is injected.
Prepare delegation context for the subagent:
{
"session_id": "sess_{timestamp}_{random}",
"delegation_depth": 1,
"delegation_path": ["orchestrator", "research", "skill-researcher"],
"timeout": 3600,
"task_context": {
"task_number": N,
"task_name": "{project_name}",
"description": "{description}",
"task_type": "{task_type}"
},
"artifact_number": "{artifact_number from Stage 3a}",
"focus_prompt": "{optional focus}",
"effort_flag": "{effort_flag from command, null if not set}",
"model_flag": "{model_flag from command, null if not set}",
"roadmap_path": "specs/ROADMAP.md",
"metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json"
}
Note: The artifact_number field tells the agent which sequence number to use for artifact naming (e.g., 01, 02).
Model/Effort Flags: If model_flag is set (haiku, sonnet, opus), pass it as the model parameter on the Agent tool to override the agent's frontmatter default. If effort_flag is set (fast, hard), include it as prompt context for reasoning depth guidance.
Read the report format file and prepare it for injection into the subagent prompt. This ensures the subagent always has the full format specification in its context, regardless of whether it reads the file itself.
format_content=$(cat .claude/context/formats/report-format.md)
The format content will be included as a delimited section in the Stage 5 prompt (see below).
CRITICAL: You MUST use the Agent tool to spawn the subagent.
Required Tool Invocation:
Tool: Agent (NOT Skill, NOT Plan)
Parameters:
- subagent_type: "general-research-agent"
- prompt: [Include task_context, delegation_context, focus_prompt, metadata_file_path,
AND the format specification from Stage 4b as shown below]
- description: "Execute research for task {N}"
Format Injection: Include the format specification from Stage 4b in the prompt as a clearly-delimited section:
<artifact-format-specification>
## CRITICAL: Report Format Requirements
You MUST follow this format specification exactly when writing the research report.
Non-compliance will be caught by postflight validation.
{format_content from Stage 4b}
</artifact-format-specification>
Place this section AFTER the delegation context JSON and BEFORE any other instructions.
Memory Context Injection: If memory_context from Stage 4a is non-empty, include it in the prompt as a separate block:
{memory_context from Stage 4a -- already wrapped in <memory-context> tags}
Place the memory context block AFTER the format specification and BEFORE the task-specific instructions. Do NOT inject an empty <memory-context> block when no memories were retrieved.
DO NOT use Skill(general-research-agent) - this will FAIL.
The subagent will:
specs/{NNN}_{SLUG}/reports/specs/{NNN}_{SLUG}/.return-meta.jsonCRITICAL: If you performed the work above WITHOUT using the Agent tool (i.e., you read files,
wrote artifacts, or updated metadata directly instead of spawning a subagent), you MUST write a
.return-meta.json file now before proceeding to postflight. Use the schema from
return-metadata-file.md with status value "researched" and the appropriate artifact information.
If you DID use the Agent tool (Stage 5), skip this stage -- the subagent already wrote the metadata.
The following stages MUST execute after work is complete, whether the work was done by a subagent (Stage 5) or inline (Stage 5b). Do NOT skip these stages for any reason.
Read the metadata file:
metadata_file="specs/${padded_num}_${project_name}/.return-meta.json"
if [ -f "$metadata_file" ] && jq empty "$metadata_file" 2>/dev/null; then
status=$(jq -r '.status' "$metadata_file")
artifact_path=$(jq -r '.artifacts[0].path // ""' "$metadata_file")
artifact_type=$(jq -r '.artifacts[0].type // ""' "$metadata_file")
artifact_summary=$(jq -r '.artifacts[0].summary // ""' "$metadata_file")
memory_candidates=$(jq -c '.memory_candidates // []' "$metadata_file")
else
echo "Error: Invalid or missing metadata file"
status="failed"
fi
If subagent status is "researched" and artifact_path is non-empty, validate the report artifact against format requirements. This is non-blocking -- warnings are logged but do not prevent postflight from completing.
if [ "$status" = "researched" ] && [ -n "$artifact_path" ] && [ -f "$artifact_path" ]; then
echo "Validating report artifact..."
if ! bash .claude/scripts/validate-artifact.sh "$artifact_path" report --fix; then
echo "WARNING: Report artifact has format issues (non-blocking). Review output above."
fi
fi
Note: The --fix flag attempts auto-repair of missing metadata fields. Validation failures are logged but do not block status update or git commit.
If status is "researched", update status and increment artifact number:
# Step 1: Update status (state.json, TODO.md task entry, TODO.md Task Order)
if [ "$status" = "researched" ]; then
.claude/scripts/update-task-status.sh postflight "$task_number" research "$session_id"
fi
# Step 2: Increment next_artifact_number (research advances the sequence)
jq '(.active_projects[] | select(.project_number == '$task_number')).next_artifact_number =
(((.active_projects[] | select(.project_number == '$task_number')).next_artifact_number // 1) + 1)' \
specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
Note: Research is the only operation that increments next_artifact_number. Plan and implement use (current - 1) to stay in the same "round".
On partial/failed: Keep status as "researching" for resume (do not call the script).
If the agent emitted memory candidates, append them to the task's state.json entry using append semantics (merge with any existing candidates from prior operations).
if [ "$memory_candidates" != "[]" ] && [ -n "$memory_candidates" ]; then
# Append new candidates to existing array (append semantics, not overwrite)
jq --argjson new_candidates "$memory_candidates" \
'(.active_projects[] | select(.project_number == '$task_number')).memory_candidates =
((.active_projects[] | select(.project_number == '$task_number')).memory_candidates // []) + $new_candidates' \
specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
fi
Note: Uses // [] fallback so this works whether or not the task already has candidates. Append semantics ensure research and implementation candidates coexist.
Add artifact to state.json with summary.
IMPORTANT: Use two-step jq pattern to avoid Issue #1132 escaping bug. See jq-escaping-workarounds.md.
if [ -n "$artifact_path" ]; then
# Step 1: Filter out existing research artifacts (use "| not" pattern to avoid != escaping - Issue #1132)
jq '(.active_projects[] | select(.project_number == '$task_number')).artifacts =
[(.active_projects[] | select(.project_number == '$task_number')).artifacts // [] | .[] | select(.type == "research" | not)]' \
specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
# Step 2: Add new research artifact
jq --arg path "$artifact_path" \
--arg type "$artifact_type" \
--arg summary "$artifact_summary" \
'(.active_projects[] | select(.project_number == '$task_number')).artifacts += [{"path": $path, "type": $type, "summary": $summary}]' \
specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
fi
Regenerate TODO.md from state.json (state.json artifact update was done in the step above):
bash .claude/scripts/generate-todo.sh || echo "WARNING: generate-todo.sh failed (non-fatal)" >&2
This regenerates TODO.md from state.json with correct bracket-only [path] format artifact links. Never use markdown [name](path) format for artifact links. If the script exits non-zero, log a warning but continue (regeneration errors are non-blocking).
Fire TTS and WezTerm tab coloring after artifact linking is complete:
lifecycle_script=".claude/scripts/lifecycle-notify.sh"
if [ -f "$lifecycle_script" ]; then
bash "$lifecycle_script" "$STATE_STATUS" &
fi
Non-blocking: called in background after artifacts are linked. Speaks "Tab N STATUS" (e.g., "Tab 3 researched") to announce the lifecycle transition.
Remove marker and metadata files:
rm -f "specs/${padded_num}_${project_name}/.postflight-pending"
rm -f "specs/${padded_num}_${project_name}/.postflight-loop-guard"
rm -f "specs/${padded_num}_${project_name}/.return-meta.json"
Return a brief text summary (NOT JSON). Example:
Research completed for task {N}:
- Found {count} relevant patterns and resources
- Identified implementation approach: {approach}
- Created report at specs/{NNN}_{SLUG}/reports/MM_{short-slug}.md
- Status updated to [RESEARCHED]
Return immediately with error message if task not found.
If subagent didn't write metadata file:
Return partial status if subagent times out (default 3600s). Keep status as "researching" for resume.
After the agent returns, this skill MUST NOT:
The postflight phase is LIMITED TO:
update-task-status.sh for status updates (state.json + TODO.md)next_artifact_number via jqReference: @.claude/context/standards/postflight-tool-restrictions.md
This skill returns a brief text summary (NOT JSON). The JSON metadata is written to the file and processed internally.
Example successful return:
Research completed for task 412:
- Found 8 relevant patterns for implementation
- Identified lazy context loading and skill-to-agent mapping patterns
- Created report at specs/412_general_research/reports/MM_{short-slug}.md
- Status updated to [RESEARCHED]
Example partial return:
Research partially completed for task 412:
- Found 4 codebase patterns
- Web search failed due to network error
- Partial report created at specs/412_general_research/reports/MM_{short-slug}.md
- Status remains [RESEARCHING] - run /research 412 to continue