skill-funds

# Funds Skill Thin wrapper that delegates funding analysis work to `funds-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 "present" with task_type="funds" - /funds command with task number - Present extension is available --- ## Workflow Type Routing This skill routes to funds-agent with one of four analysis modes: | Analysis Mode | Preflight Status | Success Status | TODO.md Markers | |---------------|-----------------|----------------|-----------------| | LANDSCAPE | researching | researched | [RESEARCHING] -> [RESEARCHED] | | PORTFOLIO | researching | researched | [RESEARCHING] -> [RESEARCHED] | | JUSTIFY | researching | researched | [RESEARCHING] -> [RESEARCHED] | | GAP | researching | researched | [RESEARCHING] -> [RESEARCHED] | **Note**: All modes follow the same status transition since they produce research-type output. --- ## Input Parameters ### Required Parameters - `task_number` - Task number (must exist in state.json with language="present" and task_type="funds") - `session_id` - Session ID from orchestrator ### Optional Parameters - `topic` - Topic for legacy standalone mode (--quick) - `mode` - Analysis mode override (LANDSCAPE, PORTFOLIO, JUSTIFY, GAP) --- ## Execution Flow ### Stage 1: Input Validation Validate required inputs: - `task_number` - Must be provided and exist in state.json - Task must have language="present" and task_type="funds" ```bash # 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 // "present"') status=$(echo "$task_data" | jq -r '.status') project_name=$(echo "$task_data" | jq -r '.project_name') description=$(echo "$task_data" | jq -r '.description // ""') task_type=$(echo "$task_data" | jq -r '.task_type // ""') # Validate language is "present" if [ "$task_type" = "present" | not ]; then return error "Task $task_number has language '$task_type', expected 'present'" fi # Validate task_type is "funds" if [ "$task_type" = "funds" | not ]; then return error "Task $task_number has task_type '$task_type', expected 'funds'" fi # Validate status (only block terminal states) if [ "$status" = "completed" ] || [ "$status" = "abandoned" ] || [ "$status" = "expanded" ]; then return error "Task is in terminal state [$status]" fi ``` --- ### 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): ```bash source .claude/scripts/skill-base.sh padded_num=$(printf "%03d" "$task_number") skill_name="skill-funds" operation="research" ``` `operation="research"` (not `"funds_analysis"`) is required here: `update-task-status.sh`'s `target_status` vocabulary has no `funds_analysis` value, so this skill maps onto the plain `research` operation. The marker's `operation` field now reads `"research"` rather than `"funds_analysis"`. --- ### Stage 3a: Calculate Artifact Number ```bash # Read next_artifact_number from state.json next_num=$(jq -r --argjson num "$task_number" \ '.active_projects[] | select(.project_number == $num) | .next_artifact_number // 1' \ specs/state.json) # Use current number for research artifacts (advances sequence) artifact_number=$next_num artifact_padded=$(printf "%02d" "$artifact_number") # Increment next_artifact_number bash .claude/scripts/state-write.sh \ '(.active_projects[] | select(.project_number == $num)).next_artifact_number = $next' \ --session-id "$session_id" \ --argjson num "$task_number" \ --argjson next "$((next_num + 1))" ``` --- ### Stage 4: Prepare Delegation Context Extract forcing_data from task metadata and prepare delegation context: ```bash # Extract forcing_data from task forcing_data=$(echo "$task_data" | jq '.forcing_data // {}') mode=$(echo "$forcing_data" | jq -r '.mode // "LANDSCAPE"') ``` Prepare delegation context for the subagent: ```json { "session_id": "sess_{timestamp}_{random}", "delegation_depth": 1, "delegation_path": ["orchestrator", "funds", "skill-funds"], "timeout": 3600, "task_context": { "task_number": N, "task_name": "{project_name}", "description": "{description}", "task_type": "present", "task_type": "funds" }, "mode": "{selected_mode from forcing_data}", "forcing_data": "{forcing_data object}", "artifact_number": "{artifact_padded}", "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json" } ``` --- ### Stage 4b: Read and Inject Format Specification Read the summary format file and prepare it for injection into the subagent prompt: ```bash format_content=$(cat .claude/context/formats/summary-format.md) ``` The format content will be included as a delimited section in the Stage 5 prompt. --- ### 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: "funds-agent" - prompt: [Include task_context, delegation_context, mode, forcing_data, artifact_number, metadata_file_path, AND the format specification from Stage 4b] - description: "Execute funding analysis for task {N}" ``` **Format Injection**: Include the format specification from Stage 4b in the prompt as a clearly-delimited section: ``` <artifact-format-specification> ## CRITICAL: Summary Format Requirements You MUST follow this format specification exactly when writing the implementation summary. Non-compliance will be caught by postflight validation. {format_content from Stage 4b} </artifact-format-specification> ``` **DO NOT** use `Skill(funds-agent)` - this will FAIL. The subagent will: - Load funding analysis context files - Parse forcing_data and mode - Execute mode-specific analysis (web research, funder database queries) - Create research report and optional XLSX/JSON outputs - Write metadata to `specs/{NNN}_{SLUG}/.return-meta.json` - Return a brief text summary (NOT JSON) --- ### Stage 5a: Validate Subagent Return Format If the subagent's text return parses as valid JSON, log a warning (v1 pattern instead of v2 file-based pattern). Non-blocking -- continue to read metadata file regardless. --- ### Stage 5b: 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 5b). Do NOT skip these stages for any reason. ### Stage 6: Read Metadata File Read the metadata file: ```bash metadata_file="specs/${padded_num}_${project_name}/.return-meta.json" if [ -f "$metadata_file" ] && jq empty "$metadata_file" 2>/dev/null; then meta_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" meta_status="failed" fi ``` **Handle in_progress status**: If metadata file shows `status: "in_progress"`, the subagent was interrupted: ```bash if [ "$meta_status" = "in_progress" ]; then partial_stage=$(jq -r '.partial_progress.stage // "unknown"' "$metadata_file") partial_details=$(jq -r '.partial_progress.details // ""' "$metadata_file") echo "Subagent interrupted at stage: $partial_stage" echo "Details: $partial_details" fi ``` --- ### Stage 6a: Validate Artifact Content If subagent status indicates success and `artifact_path` is non-empty, validate the artifact: ```bash if [ "$meta_status" = "researched" ]; then if [ -n "$artifact_path" ] && [ -f "$artifact_path" ]; then echo "Validating artifact..." if ! bash .claude/scripts/validate-artifact.sh "$artifact_path" report --fix; then echo "WARNING: Artifact has format issues (non-blocking). Review output above." fi fi fi ``` --- ### Stage 7: Update Task Status (Postflight) **Postflight Status Mapping**: | Meta Status | Final state.json | Final TODO.md | |-------------|-----------------|---------------| | researched | researched | [RESEARCHED] | | partial | researching | [RESEARCHING] | | failed | (keep preflight) | (keep preflight marker) | **Update state.json** (if status changed to success): ```bash if [ "$meta_status" = "researched" ]; then bash .claude/scripts/state-write.sh \ '(.active_projects[] | select(.project_number == $num)) |= . + { status: $status, last_updated: $ts }' \ --session-id "$session_id" \ --argjson num "$task_number" \ --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ --arg status "researched" fi ``` **Update TODO.md**: Use Edit tool to change status marker to `[RESEARCHED]`. **On partial/failed**: Keep status at preflight level for resume. --- ### Stage 8: Link Artifacts Add artifact to state.json with summary. **IMPORTANT**: Use two-step jq pattern to avoid Issue #1132 escaping bug. ```bash