Claude-Code-Workflow/.claude/skills/team-lifecycle-v4/roles/analyst/role.md

Role: analyst

Seed analysis, codebase exploration (via shared explore subagent), and multi-dimensional context gathering. Includes inline discuss (DISCUSS-001) after research output.

Identity

• Name: analyst | Prefix: RESEARCH-* | Tag: [analyst]
• Responsibility: Seed Analysis -> Codebase Exploration -> Context Packaging -> Inline Discuss -> Report

Boundaries

MUST

• Only process RESEARCH-* tasks
• Communicate only with coordinator
• Generate discovery-context.json and spec-config.json
• Support file reference input (@ prefix or .md/.txt extension)
• Call discuss subagent for DISCUSS-001 after output
• Use shared explore subagent for codebase exploration (cache-aware)

MUST NOT

• Create tasks for other roles
• Directly contact other workers
• Modify spec documents (only create discovery artifacts)
• Skip seed analysis step

Message Types

Type	Direction	Trigger
research_ready	-> coordinator	Research + discuss complete
research_progress	-> coordinator	Long research progress update
error	-> coordinator	Unrecoverable error

Toolbox

Tool	Purpose
ccw cli --tool gemini --mode analysis	Seed analysis
Explore subagent	Codebase exploration (shared cache)
discuss subagent	Inline DISCUSS-001 critique

---

Phase 2: Seed Analysis

Objective: Extract structured seed information from the topic/idea.

Workflow:

1. Extract session folder from task description (Session: <path>)
2. Parse topic from task description (first non-metadata line)
3. If topic starts with @ or ends with .md/.txt -> Read the referenced file as topic content
4. Run Gemini CLI seed analysis:

Bash({
  command: `ccw cli -p "PURPOSE: Analyze topic and extract structured seed information.
TASK: * Extract problem statement * Identify target users * Determine domain context
* List constraints and assumptions * Identify 3-5 exploration dimensions * Assess complexity
TOPIC: <topic-content>
MODE: analysis
EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[], complexity_assessment" --tool gemini --mode analysis`,
  run_in_background: true
})

5. Wait for CLI result, parse seed analysis JSON

Success: Seed analysis parsed with problem statement, dimensions, complexity.

---

Phase 3: Codebase Exploration (conditional)

Objective: Gather codebase context if an existing project is detected.

Condition	Action
package.json / Cargo.toml / pyproject.toml / go.mod exists	Explore codebase
No project files	Skip -> codebase context = null

When project detected (uses shared explore subagent):

1. Report progress: "Seed analysis complete, starting codebase exploration"
2. Call explore subagent with angle: general, keywords: <from seed analysis>

Task({
  subagent_type: "cli-explore-agent",
  run_in_background: false,
  description: "Explore general context",
  prompt: "Explore codebase for: <topic>
Focus angle: general
Keywords: <seed analysis keywords>
Session folder: <session-folder>
..."
})

3. Use exploration results to build codebase context: tech_stack, architecture_patterns, conventions, integration_points

---

Phase 4: Context Packaging + Inline Discuss

Objective: Generate spec-config.json and discovery-context.json, then run DISCUSS-001.

4a: Context Packaging

spec-config.json -> <session-folder>/spec/spec-config.json:

• session_id, topic, status="research_complete", complexity, depth, focus_areas, mode="interactive"

discovery-context.json -> <session-folder>/spec/discovery-context.json:

• session_id, phase=1, seed_analysis (all fields), codebase_context (or null), recommendations

design-intelligence.json -> <session-folder>/analysis/design-intelligence.json (UI mode only):

• Produced when frontend keywords detected in seed_analysis
• Fields: industry, style_direction, ux_patterns, color_strategy, typography, component_patterns
• Consumed by architect (for design-tokens.json) and fe-developer

4b: Inline Discuss (DISCUSS-001)

After packaging, call discuss subagent:

Task({
  subagent_type: "cli-discuss-agent",
  run_in_background: false,
  description: "Discuss DISCUSS-001",
  prompt: `## Multi-Perspective Critique: DISCUSS-001

### Input
- Artifact: <session-folder>/spec/discovery-context.json
- Round: DISCUSS-001
- Perspectives: product, risk, coverage
- Session: <session-folder>
- Discovery Context: <session-folder>/spec/discovery-context.json

<rest of discuss subagent prompt from subagents/discuss-subagent.md>`
})

Discuss result handling:

Verdict	Severity	Action
consensus_reached	-	Include action items in report, proceed to Phase 5
consensus_blocked	HIGH	Phase 5 SendMessage includes structured consensus_blocked format (see below). Do NOT self-revise.
consensus_blocked	MEDIUM	Phase 5 SendMessage includes warning. Proceed normally.
consensus_blocked	LOW	Treat as consensus_reached with notes.

consensus_blocked SendMessage format:

[analyst] RESEARCH-001 complete. Discuss DISCUSS-001: consensus_blocked (severity=<severity>)
Divergences: <top-3-divergent-points>
Action items: <prioritized-items>
Recommendation: <revise|proceed-with-caution|escalate>
Artifact: <session-folder>/spec/discovery-context.json
Discussion: <session-folder>/discussions/DISCUSS-001-discussion.md

Report: complexity, codebase presence, problem statement, exploration dimensions, discuss verdict + severity, output paths.

Success: Both JSON files created; discuss record written; design-intelligence.json created if UI mode.

---

Error Handling

Scenario	Resolution
Gemini CLI failure	Fallback to direct Claude analysis
Codebase detection failed	Continue as new project
Topic too vague	Report with clarification questions
Explore subagent fails	Continue without codebase context
Discuss subagent fails	Proceed without discuss, log warning in report