Skill Researcher

Researcher Skill

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.

Context References

Reference (do not load eagerly):

• Path: .claude/context/formats/return-metadata-file.md - Metadata file schema
• Path: .claude/context/patterns/postflight-control.md - Marker file protocol
• Path: .claude/context/patterns/file-metadata-exchange.md - File I/O helpers
• Path: .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.

Trigger Conditions

This skill activates when:

• Task type is "general", "meta", "markdown", "latex", or "typst"
• Research is needed for implementation planning
• Documentation or external resources need to be gathered

Execution Flow

Stage 1: Input Validation

Validate required inputs:

• task_number - Must be provided and exist in state.json
• focus_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 // ""')

Stage 2 + Stage 3: Preflight Status Update and Postflight Marker

Source skill-base.sh once, then follow @.claude/context/patterns/skill-preflight-flow.md in full for Stage 2 (preflight status update) and Stage 3 (marker creation):

source .claude/scripts/skill-base.sh
padded_num=$(printf "%03d" "$task_number")
skill_name="skill-researcher"
operation="research"

This skill supplies the shared block's preconditions: task_number, padded_num, project_name, session_id, operation, skill_name. Follow the shared block's ordering and failure-semantics rules exactly — do not re-inline the update-task-status.sh preflight call or the .postflight-pending heredoc here.

Stage 3a: Read Artifact Number

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

# Reconciliation: scan all task subdirs for max artifact number on disk
# Handles legacy tasks where next_artifact_number may be behind actual files
padded_num=$(printf "%03d" "$task_number")
max_on_disk=$(find "specs/${padded_num}_${project_name}" -name "[0-9][0-9]_*.md" 2>/dev/null \
  | sed 's|.*/\([0-9][0-9]\)_.*|\1|' | sort -n | tail -1)
max_on_disk=${max_on_disk:-0}
# Strip leading zeros to avoid octal interpretation
max_on_disk=$((10#$max_on_disk))
if [ "$artifact_number" -le "$max_on_disk" ]; then
  artifact_number=$((max_on_disk + 1))
  # If reconciliation advanced the number, also sync state.json so subsequent operations stay in sync
  bash .claude/scripts/state-write.sh \
    '(.active_projects[] | select(.project_number == $num)).next_artifact_number = $new_num' \
    --session-id "$session_id" \
    --argjson num "$task_number" --argjson new_num "$artifact_number"
fi

artifact_padded=$(printf "%02d" "$artifact_number")

# Collision check: ensure no existing file uses this prefix in reports/
while ls "specs/${padded_num}_${project_name}/reports/${artifact_padded}_"*.md 2>/dev/null | grep -q .; do
  artifact_number=$((artifact_number + 1))
  artifact_padded=$(printf "%02d" "$artifact_number")
done

Stage 4a: Memory Retrieval (Auto)

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.

Literature Detection and Injection (Stage 4a, shared block)

Follow @.claude/context/patterns/lit-stage4a-flow.md in full to resolve --lit and set lit_context: call literature-lit-flag-resolve.sh, branch on all six directives (LIT_DISABLED, SUBINDEX_PRESENT, GLOBAL_MISSING, PROMPT_NEEDED, AUTONOMOUS_GLOBAL, SPARSE_PROMPT_NEEDED), issue the real four-option AskUserQuestion for the two interactive directives (including the "Search online to ingest" option wired to the STABLE-CONTRACT literature-ingest-online.sh bridge), apply the two-checkpoint sparse re-prompt after "Use global corpus now", and take the deterministic [lit:auto] autonomous fallback when orchestrator_mode == "true" (never calling AskUserQuestion in that case). This skill supplies the shared block's preconditions: lit_flag, description, and orchestrator_mode (read from the delegation context; default "false" when unset).

Note: lit_flag is independent of clean_flag. Using --clean --lit suppresses memory retrieval but still injects literature briefing. Literature briefing is gated solely on lit_flag == "true".

Stage 4: Prepare Delegation Context

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, fable), 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.

Stage 4b: Read and Inject Format Specification

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).

Stage 5: Invoke Subagent

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.

Literature Briefing Injection: If lit_context from Stage 4a is non-empty, include it in the prompt as a separate block:

{lit_context from Stage 4a -- already wrapped in <literature-briefing> tags}

Place the literature briefing block AFTER the memory context block (if any) and BEFORE the task-specific instructions. Do NOT inject an empty <literature-briefing> block when no literature briefing was generated.

DO NOT use Skill(general-research-agent) - this will FAIL.

The subagent will:

• Search codebase for related patterns
• Search web for documentation and examples
• Analyze findings and synthesize recommendations
• Create research report in specs/{NNN}_{SLUG}/reports/
• Write metadata to specs/{NNN}_{SLUG}/.return-meta.json
• Return a brief text summary (NOT JSON)

Stage 5b: Self-Execution Fallback

Follow @.claude/context/patterns/skill-self-execution-fallback.md in full. This skill's success status value for that block's write obligation is "researched".

Postflight (ALWAYS EXECUTE)

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.

Stage 6: Parse Subagent Return (Read Metadata File)

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

Stage 6a: Validate Artifact Content

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.

Stage 7, 7a, 8, 8a, 9: Postflight Status, Memory Candidates, Artifact Linking, Notify, Cleanup

Follow @.claude/context/patterns/skill-postflight-flow.md in full for Stage 7 (postflight status update), Stage 7a (memory-candidate propagation), Stage 8 (artifact linking), Stage 8a (TTS notify), and Stage 9 (cleanup):

field_name='**Research**'
next_field='**Plan**'

This skill supplies the shared block's preconditions: task_number, padded_num, project_name, session_id, operation, status, artifact_path, artifact_type, artifact_summary, memory_candidates, field_name, next_field.

Research-specific addition, NOT covered by the shared block: research is the only operation that increments next_artifact_number (plan and implement stay at current - 1 to share the same round). Run this immediately after the shared block's Stage 7 call, guarded the same way:

if [ "$status" = "researched" ]; then
  bash .claude/scripts/state-write.sh \
    '(.active_projects[] | select(.project_number == '$task_number')).next_artifact_number =
      (((.active_projects[] | select(.project_number == '$task_number')).next_artifact_number // 1) + 1)' \
    --session-id "$session_id"
fi

On partial/failed: Keep status as "researching" for resume (skill_postflight_update already no-ops on a non-success status; the artifact-number increment above is separately guarded on status = "researched").

Stage 10: Return Brief Summary

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]

Error Handling

Input Validation Errors

Return immediately with error message if task not found.

Metadata File Missing

If subagent didn't write metadata file:

1. Keep status as "researching"
2. Do not cleanup postflight marker
3. Report error to user

Subagent Timeout

Return partial status if subagent times out (default 3600s). Keep status as "researching" for resume.

MUST NOT (Postflight Boundary)

After the agent returns, this skill MUST NOT:

1. Edit source files - All research work is done by agent
2. Run build/test commands - Verification is done by agent
3. Use MCP/WebSearch tools - Research tools are for agent use only
4. Analyze or grep source - Analysis is agent work
5. Write reports - Artifact creation is agent work

The postflight phase is LIMITED TO:

• Reading agent metadata file
• Calling update-task-status.sh for status updates (state.json + TODO.md)
• Incrementing next_artifact_number via jq
• Linking artifacts in state.json
• Cleanup of temp/marker files

Reference: @.claude/context/standards/postflight-tool-restrictions.md

Return Format

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 {N}:
- Found 8 relevant patterns for implementation
- Identified lazy context loading and skill-to-agent mapping patterns
- Created report at specs/{NNN}_general_research/reports/MM_{short-slug}.md
- Status updated to [RESEARCHED]

Example partial return:

Research partially completed for task {N}:
- Found 4 codebase patterns
- Web search failed due to network error
- Partial report created at specs/{NNN}_general_research/reports/MM_{short-slug}.md
- Status remains [RESEARCHING] - run /research {N} to continue