Market Skill

Thin wrapper that routes market sizing research requests to the market-agent.

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.

Context Pointers

Reference (do not load eagerly):

• Path: .claude/context/core/formats/subagent-return.md
• Purpose: Return validation
• Load at: Subagent execution only

Note: This skill is a thin wrapper. Context is loaded by the delegated agent, not this skill.

Trigger Conditions

This skill activates when:

Direct Invocation

• User explicitly runs /market command
• User requests market sizing in conversation

Implicit Invocation (during task implementation)

When an implementing agent encounters any of these patterns:

Plan step language patterns:

• "Analyze market size"
• "Calculate TAM/SAM/SOM"
• "Market sizing analysis"
• "Estimate addressable market"

Target mentions:

• "TAM", "SAM", "SOM"
• "total addressable market"
• "market opportunity"
• "market sizing"

When NOT to trigger

Do not invoke for:

• Competitive analysis (use skill-analyze)
• GTM strategy (use skill-strategy)
• General business research (use skill-researcher)
• Revenue projections (not market sizing)

Execution Flow

Stage 1: Input Validation

Validate required inputs:

• task_number - Must be provided and exist in state.json
• industry - Optional, string
• segment - Optional, string
• mode - Optional, one of: VALIDATE, SIZE, SEGMENT, DEFEND

bash
1# Lookup task
2task_data=$(jq -r --argjson num "$task_number" \
3  '.active_projects[] | select(.project_number == $num)' \
4  specs/state.json)
5
6# Validate exists
7if [ -z "$task_data" ]; then
8  return error "Task $task_number not found"
9fi
10
11# Extract fields
12language=$(echo "$task_data" | jq -r '.language // "founder"')
13status=$(echo "$task_data" | jq -r '.status')
14project_name=$(echo "$task_data" | jq -r '.project_name')
15description=$(echo "$task_data" | jq -r '.description // ""')
16
17# Validate mode if provided
18if [ -n "$mode" ]; then
19  case "$mode" in
20    VALIDATE|SIZE|SEGMENT|DEFEND) ;;
21    *) return error "Invalid mode: $mode. Must be VALIDATE, SIZE, SEGMENT, or DEFEND" ;;
22  esac
23fi

Stage 2: Preflight Status Update

Update task status to "researching" BEFORE invoking subagent.

Update state.json:

bash
1jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
2   --arg status "researching" \
3   --arg sid "$session_id" \
4  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
5    status: $status,
6    last_updated: $ts,
7    session_id: $sid
8  }' specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json

Update TODO.md: Use Edit tool to change status marker to [RESEARCHING].

Stage 3: Create Postflight Marker

bash
1padded_num=$(printf "%03d" "$task_number")
2mkdir -p "specs/${padded_num}_${project_name}"
3
4cat > "specs/${padded_num}_${project_name}/.postflight-pending" << EOF
5{
6  "session_id": "${session_id}",
7  "skill": "skill-market",
8  "task_number": ${task_number},
9  "operation": "research",
10  "reason": "Postflight pending: status update, artifact linking, git commit",
11  "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
12}
13EOF

Stage 4: Prepare Delegation Context

json
1{
2  "task_context": {
3    "task_number": N,
4    "project_name": "{project_name}",
5    "description": "{description}",
6    "language": "founder"
7  },
8  "industry": "optional industry hint",
9  "segment": "optional segment hint",
10  "mode": "VALIDATE|SIZE|SEGMENT|DEFEND or null",
11  "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json",
12  "metadata": {
13    "session_id": "sess_{timestamp}_{random}",
14    "delegation_depth": 1,
15    "delegation_path": ["orchestrator", "market", "skill-market"]
16  }
17}

Stage 5: Invoke Agent

CRITICAL: You MUST use the Task tool to spawn the agent.

Required Tool Invocation:

Tool: Task (NOT Skill)
Parameters:
  - subagent_type: "market-agent"
  - prompt: [Include task_context, industry, segment, mode, metadata_file_path, metadata]
  - description: "Market sizing research with TAM/SAM/SOM"

The agent will:

• Present mode selection if not pre-selected
• Use forcing questions to gather market data
• Create research report at specs/{NNN}_{SLUG}/reports/
• Write metadata file
• Return brief text summary

Stage 6: Parse Subagent Return

bash
1padded_num=$(printf "%03d" "$task_number")
2metadata_file="specs/${padded_num}_${project_name}/.return-meta.json"
3
4if [ -f "$metadata_file" ] && jq empty "$metadata_file" 2>/dev/null; then
5    status=$(jq -r '.status' "$metadata_file")
6    artifact_path=$(jq -r '.artifacts[0].path // ""' "$metadata_file")
7    artifact_type=$(jq -r '.artifacts[0].type // ""' "$metadata_file")
8    artifact_summary=$(jq -r '.artifacts[0].summary // ""' "$metadata_file")
9else
10    status="failed"
11fi

Stage 7: Update Task Status (Postflight)

If status is "researched", update state.json and TODO.md.

Update state.json:

bash
1jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
2   --arg status "researched" \
3  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
4    status: $status,
5    last_updated: $ts
6  }' specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json

Update TODO.md: Use Edit tool to change status marker to [RESEARCHED].

Stage 8: Link Artifacts

Add artifact to state.json with summary.

IMPORTANT: Use two-step jq pattern to avoid escaping issues.

bash
1if [ -n "$artifact_path" ]; then
2    # Step 1: Filter out existing research artifacts (use "| not" pattern)
3    jq '(.active_projects[] | select(.project_number == '$task_number')).artifacts =
4        [(.active_projects[] | select(.project_number == '$task_number')).artifacts // [] | .[] | select(.type == "research" | not)]' \
5      specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
6
7    # Step 2: Add new research artifact
8    jq --arg path "$artifact_path" \
9       --arg type "$artifact_type" \
10       --arg summary "$artifact_summary" \
11      '(.active_projects[] | select(.project_number == '$task_number')).artifacts += [{"path": $path, "type": $type, "summary": $summary}]' \
12      specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
13fi

Update TODO.md: Add research artifact link using count-aware format.

Strip specs/ prefix for TODO.md (TODO.md is inside specs/): todo_link_path="${artifact_path#specs/}"

Use count-aware artifact linking format per .claude/rules/state-management.md "Artifact Linking Format".

Stage 9: Git Commit

bash
1git add -A
2git commit -m "task ${task_number}: complete research
3
4Session: ${session_id}
5
6Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

Stage 10: Cleanup

bash
1rm -f "specs/${padded_num}_${project_name}/.postflight-pending"
2rm -f "specs/${padded_num}_${project_name}/.postflight-loop-guard"
3rm -f "specs/${padded_num}_${project_name}/.return-meta.json"

Stage 11: Return Brief Summary

Market sizing research completed for task {N}:
- Mode: {mode}, {questions_asked} forcing questions completed
- Problem: {brief problem statement}
- Entity count: {value} from {source}
- Research report: specs/{NNN}_{SLUG}/reports/01_{short-slug}.md
- Status updated to [RESEARCHED]
- Changes committed
- Next: Run /plan {N} to create implementation plan

Return Format

Brief text summary (NOT JSON).

Expected successful return:

Market sizing research completed for task 234:
- Mode: SIZE, 8 forcing questions completed
- Problem: Streamline deploy coordination for mid-market SaaS
- Entity count: 500,000 mid-market SaaS companies globally (Gartner)
- Research report: specs/234_market_sizing_fintech/reports/01_market-sizing.md
- Status updated to [RESEARCHED]
- Changes committed with session sess_1736700000_abc123
- Next: Run /plan 234 to create implementation plan

Error Handling

Input Validation Errors

Return immediately if task not found.

Metadata File Missing

Keep status as "researching" for resume.

User Abandonment

Return partial status with progress made.

Git Commit Failure

Non-blocking: Log failure but continue.