Lean Research Skill
Thin wrapper that delegates Lean research to lean-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.
Trigger Conditions
This skill activates when:
- Task type is "lean4" or "lean" (either accepted)
- Research involves Mathlib, theorems, or proofs
- Lean-specific MCP tools are needed
Execution Flow
Stage 1: Input Validation
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 // ""')
Stage 2: Preflight Status Update
Update task status to "researching" BEFORE invoking subagent.
Update state.json:
bash .claude/scripts/state-write.sh \
'(.active_projects[] | select(.project_number == $num)) |= . + {
status: $status,
last_updated: $ts,
session_id: $sid
}' \
--session-id "$session_id" \
--argjson num "$task_number" \
--arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
--arg status "researching" \
--arg sid "$session_id"
Update TODO.md: Use Edit tool to change status marker from [NOT STARTED] or [RESEARCHED] to [RESEARCHING].
# WARN-only: reports lean-lsp MCP registration drift without blocking dispatch. Two
# invocations: the no-flag call keeps the human-readable transcript message unchanged; the
# --dispatch-block call separately captures the evidence-tier block for Stage 3's
# lean_readiness field, so the finding reaches the subagent instead of being discarded after
# printing to the transcript. Not latency-critical on this (non-/orchestrate) path.
lean_readiness=""
if [ -x .claude/scripts/lean-mcp-preflight-check.sh ]; then
bash .claude/scripts/lean-mcp-preflight-check.sh || true
lean_readiness="$(bash .claude/scripts/lean-mcp-preflight-check.sh --dispatch-block 2>/dev/null)" || lean_readiness=""
fi
Stage 3: Prepare Delegation Context
Prepare delegation context for the subagent:
{
"session_id": "sess_{timestamp}_{random}",
"delegation_depth": 1,
"delegation_path": ["orchestrator", "research", "skill-lean-research"],
"timeout": 3600,
"task_context": {
"task_number": N,
"task_name": "{project_name}",
"description": "{description}",
"task_type": "lean"
},
"focus_prompt": "{optional focus}",
"lean_readiness": "{Stage 2's captured --dispatch-block output; empty string when the probe is absent or this is not a Lean project}",
"metadata_file_path": "specs/{N}_{SLUG}/.return-meta.json"
}
Stage 4: 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: "lean-research-agent"
- prompt: [Include task_context, delegation_context, focus_prompt, metadata_file_path]
- description: "Execute Lean research for task {N}"
When lean_readiness is non-empty, include it verbatim in the subagent prompt — the field is
useless if the prompt composer drops it.
DO NOT use Skill(lean-research-agent) - this will FAIL.
The subagent will:
- Search Mathlib using lean_leansearch, lean_loogle, lean_leanfinder
- Verify theorems with lean_local_search and lean_hover_info
- Analyze findings and synthesize recommendations
- Create research report in
specs/{N}_{SLUG}/reports/ - Write metadata to
specs/{N}_{SLUG}/.return-meta.json - Return a brief text summary (NOT JSON)
Stage 4b: Self-Execution Fallback
CRITICAL: 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 the appropriate status value for this operation.
If you DID use the Agent tool, skip this stage -- the subagent already wrote the metadata.
Postflight (ALWAYS EXECUTE)
The following stages MUST execute after work is complete, whether the work was done by a subagent or inline (Stage 4b). Do NOT skip these stages for any reason.
Stage 5: Parse Subagent Return
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")
else
echo "Error: Invalid or missing metadata file"
status="failed"
fi
Stage 6: Update Task Status (Postflight)
If status is "researched", update state.json and TODO.md:
Update state.json:
bash .claude/scripts/state-write.sh \
'(.active_projects[] | select(.project_number == $num)) |= . + {
status: $status,
last_updated: $ts,
researched: $ts
}' \
--session-id "$session_id" \
--argjson num "$task_number" \
--arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
--arg status "researched"
Update TODO.md: Use Edit tool to change status marker from [RESEARCHING] to [RESEARCHED].
On partial/failed: Keep status as "researching" for resume.
Stage 7: Link Artifacts
Add artifact to state.json with summary.
if [ -n "$artifact_path" ]; then
bash .claude/scripts/state-write.sh \
'(.active_projects[] | select(.project_number == $num)).artifacts += [{"path": $path, "type": $type, "summary": $summary}]' \
--session-id "$session_id" \
--argjson num "$task_number" \
--arg path "$artifact_path" \
--arg type "$artifact_type" \
--arg summary "$artifact_summary"
fi
Update TODO.md: Link artifact using count-aware format. Apply the four-case Edit logic from @.claude/context/patterns/artifact-linking-todo.md with field_name=**Research**, next_field=**Plan**.
Stage 8: Git Commit
Commit changes with session ID:
bash .claude/scripts/git-commit-scoped.sh \
--message "task ${task_number}: complete research" \
--session "${session_id}" \
--honest-index-rows "${task_number}" \
-- "specs/${padded_num}_${project_name}/reports/" \
"specs/${padded_num}_${project_name}/.return-meta.json" \
"specs/TODO.md" \
"specs/state.json"
Stage 9: Return Brief Summary
Return a brief text summary (NOT JSON). Example:
Research completed for task {N}:
- Found {count} relevant Mathlib theorems
- Identified proof strategy: {strategy}
- Created report at specs/{N}_{SLUG}/reports/MM_{short-slug}.md
- Status updated to [RESEARCHED]
- Changes committed
Error Handling
Input Validation Errors
Return immediately with error message if task not found.
Metadata File Missing
If subagent didn't write metadata file:
- Keep status as "researching"
- Report error to user
Git Commit Failure
Non-blocking: Log failure but continue with success response.
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:
- Re-run Lean searches - All MCP searches are done by agent
- Re-verify type signatures - Verification is done by agent
- Edit research reports - Artifact creation is agent work
The postflight phase is LIMITED TO:
- Reading agent metadata file
- Updating state.json via jq
- Updating TODO.md status marker via Edit
- Linking artifacts in state.json
- Git commit
Return Format
This skill returns a brief text summary (NOT JSON). The JSON metadata is written to the file and processed internally.