Explore

Context Exploration Skill

Purpose

Gather comprehensive context from external sources, codebase patterns, and human input to inform implementation planning.

Usage

/explore

(Must be run after /pull)

What This Skill Does

1. Verify Prerequisites: Confirm current-issue.md exists from /pull
2. Launch Parallel Exploration: Spawn 1-3 concurrent exploration agents based on available context:
   • External Context Explorer (conditional): Fetch Figma designs and Confluence documentation if links exist
   • Codebase Pattern Explorer (always): Find reference implementations and reusable utilities
   • Attachments Explorer (conditional): Analyze screenshots, diagrams, and docs if files exist
3. Ask Clarification Questions: Gather user input on ambiguities and decisions (unlimited questions)
4. Request Additional Context: Ask user for screenshots, external docs, or other helpful context
5. Consolidate Context: Merge findings into exploration-summary.md
6. Report Findings: Display summary and next steps

Instructions

You are coordinating the exploration phase for a JIRA issue. This skill uses a multi-phase exploration approach with parallel agents to gather comprehensive context before planning.

CRITICAL: Your ONLY job is to:

1. Coordinate exploration agents
2. Spawn sub-agents using the Task tool
3. Consolidate exploration findings
4. Report results to the user

DO NOT:

• Fetch JIRA data yourself (use /pull first)
• Perform exploration yourself
• Generate implementation plans (use /plan for that)
• If sub-agents fail, DO NOT retry the work yourself - report the failure to the user

Step 1: Verify Prerequisites

Verify that the JIRA analysis exists:

JIRA_DIR=$(ls -td workflow/jira-to-github/*/ 2>/dev/null | head -1)
if [ ! -f "$JIRA_DIR/current-issue.md" ]; then
  echo "❌ No JIRA analysis found. Run /pull first."
  exit 1
fi
JIRA_KEY=$(basename "$JIRA_DIR")
echo "✓ Found JIRA issue: $JIRA_KEY"

Step 2: Launch Parallel Exploration Agents

CRITICAL: Launch 1-3 exploration agents in parallel using a single message with multiple Task tool calls.

Pre-checks (determine which agents to spawn):

1. Agent 1 (External Context): Only spawn if Figma/Confluence links detected

   JIRA_DIR=$(ls -td workflow/jira-to-github/*/ 2>/dev/null | head -1)
   if grep -q "figma.com\|confluence" "$JIRA_DIR/current-issue.md"; then
     echo "✓ External links found - spawning Agent 1"
     # Spawn Agent 1
   else
     echo "ℹ No Figma/Confluence links found - skipping Agent 1"
     # Skip this agent
   fi
   

2. Agent 2 (Codebase Patterns): Always spawn (core exploration)

3. Agent 3 (Attachments): Only spawn if attachment files exist

   ATTACHMENTS_DIR="$JIRA_DIR/attachments"
   if [ -d "$ATTACHMENTS_DIR" ] && [ "$(ls -A "$ATTACHMENTS_DIR" 2>/dev/null)" ]; then
     echo "✓ Attachments found - spawning Agent 3"
     # Spawn Agent 3
   else
     echo "ℹ No attachments found - skipping Agent 3"
     # Skip this agent
   fi
   

Result: Spawn 1-3 agents based on available context sources.

Agent 1: External Context Explorer (Conditional)

Task Tool Parameters:

• subagent_type: "general-purpose"
• description: "Fetch external documentation"
• model: "haiku" (quick external fetches)

Agent Prompt:

You are the External Context Explorer. Your job is to fetch and analyze external documentation.

CONTEXT FILES:
- JIRA analysis: workflow/jira-to-github/*/current-issue.md

Tasks:
1. Read `current-issue.md` to find Figma and Confluence links in the issue description or technical context

2. If Figma links found: Use Figma MCP to fetch design files
   - Extract component specifications and visual layouts
   - Identify design tokens (colors, spacing, typography, icons)
   - Document component hierarchy and interactions
   - List any design constraints or accessibility requirements

3. If Confluence links found: Use Atlassian MCP to fetch documentation
   - Extract technical specifications and architecture decisions
   - Identify requirements and acceptance criteria details
   - Document integration points and dependencies
   - List technical constraints and security requirements

4. Return findings in structured format:

---
## External Context Findings

### Figma Designs
[If Figma links found, list components and specs. Otherwise: "No Figma links found in current-issue.md"]

**Components**:
- Component Name: [specs, dimensions, states]
- Component Name: [specs, dimensions, states]

**Design Tokens**:
- Colors: [list]
- Typography: [list]
- Spacing: [list]

**Design Constraints**:
- [Constraint 1]
- [Constraint 2]

### Confluence Documentation
[If Confluence links found, summarize technical details. Otherwise: "No Confluence links found in current-issue.md"]

**Technical Specifications**:
- [Key spec 1]
- [Key spec 2]

**Architecture Decisions**:
- [Decision 1]
- [Decision 2]

**Integration Points**:
- [System/API 1]
- [System/API 2]

**Technical Constraints**:
- [Constraint 1]
- [Constraint 2]

### Summary
[1-2 sentences summarizing external context findings]
---

ERROR HANDLING:
- If access denied to Figma/Confluence: Return empty sections gracefully with note
- If links malformed or not found: Note this and continue
- Log errors but do not fail - return whatever context is available

TARGET OUTPUT: 3-5 KB

Agent 2: Codebase Pattern Explorer

Task Tool Parameters:

• subagent_type: "Explore"
• description: "Find codebase patterns"
• model: "haiku" (fast pattern searches)

Agent Prompt:

You are the Codebase Pattern Explorer. Your job is to find relevant patterns and implementations in the codebase.

CONTEXT FILES:
- Target repo: workflow/jira-to-github/*/target-repo.md
- JIRA analysis: workflow/jira-to-github/*/current-issue.md

OPTIMIZATION GOAL: Use file:function references, NOT code examples. Target 4-6 KB output.

Tasks:

1. Read `target-repo.md` to find the repo path and profile:
   - Read the profile at the path specified in `target-repo.md` (e.g., `context/repos/esperanto.md`)
   - Extract the `Context Files` section to find:
     - Root context file path (e.g., `CLAUDE.md`)
     - Primary module context file path (e.g., `@kroger/buy/kroger-hosted-payment-page/README.md`)
   - Read the repo's own CLAUDE.md at `<repo-path>/CLAUDE.md`:
     - Extract project architecture patterns
     - Identify testing approaches and conventions
     - Note error handling standards
     - Document analytics/tracking patterns
     - List any coding standards or rules
   - Read the module context file at `<repo-path>/<primary-module-path>` (if specified in profile):
     - Extract module-specific structure, key files, dependencies
     - Note module-specific testing or validation patterns

   If these context files cover the topics above, SKIP searching for them - reference the files instead.
   This saves 20-30k tokens on redundant exploration.

2. Read `current-issue.md` to understand issue type and requirements

3. Based on issue type, perform targeted searches ONLY:

   DO targeted searches like:
   ✅ Specific files mentioned in current-issue.md
   ✅ Pattern names (e.g., "isBankCard", "useWalletActions")
   ✅ Component names (e.g., "AddCardForm.tsx", "CardList.tsx")
   ✅ One test example file (e.g., "CardList.test.tsx")

   AVOID broad searches like:
   ❌ Generic terms: "card", "wallet", "error", "validation"
   ❌ Patterns already documented in repo CLAUDE.md or module context file
   ❌ Multiple reference implementations (find 1-2 max)

4. Find the following (if NOT already covered by repo CLAUDE.md or module context file):
   - 1-2 reference implementations (similar features/components)
   - Reusable utilities and helper functions
   - Testing patterns (1 test example to follow)
   - Key integration points mentioned in issue

5. Return findings in structured format:

---
## Codebase Pattern Findings

### Repo Context Patterns
[Summarize key patterns from repo CLAUDE.md and module context file. If not found: "Repo context files not found"]

**Architecture**:
- [Pattern 1 from repo CLAUDE.md]
- [Pattern 2 from repo CLAUDE.md]

**Testing Approach**:
- [Testing pattern from repo CLAUDE.md or module context file]

**Error Handling**:
- [Error handling pattern from repo CLAUDE.md]

**Analytics**:
- [Analytics pattern from repo CLAUDE.md]

**Module Context**:
- [Key files and structure from module context file, if loaded]

### Reference Implementations
[List 1-2 similar implementations found in codebase]

| File | Function/Component | Purpose | Key Pattern |
|------|-------------------|---------|-------------|
| path/file.ts:123 | functionName() | Brief purpose | Pattern to follow |
| path/component.tsx:45 | ComponentName | Brief purpose | Pattern to follow |

### Reusable Utilities
[List utilities that can be leveraged]

| File | Function | Purpose |
|------|----------|---------|
| path/utils.ts:67 | helperFunction() | Brief purpose |
| path/hooks.ts:34 | useCustomHook() | Brief purpose |

### Testing Patterns
[List 1 test example to follow]

| Test File | Pattern | Notes |
|-----------|---------|-------|
| path/test.spec.ts:12 | Test pattern name | What to follow |

### Critical Files Identified
[List all files mentioned in searches]
- path/file1.ts
- path/file2.tsx
- path/test.spec.ts

### Summary
[1-2 sentences summarizing codebase patterns found]
---

ERROR HANDLING:
- If target-repo.md not found: Fall back to reading CLAUDE.md at project root
- If repo CLAUDE.md not found: Continue with codebase searches
- If module context file not found or not specified: Continue without module context
- If no reference implementations found: Note this and continue
- If searches return too many results: Pick most relevant 1-2 examples

TOKEN OPTIMIZATION:
- Use tables for efficiency
- Reference files with line numbers, NOT code blocks
- Keep descriptions brief (5-10 words max)
- Single source of truth (no duplicate info)

TARGET OUTPUT: 4-6 KB

Agent 3: Attachments Explorer (Conditional)

IMPORTANT: This agent only spawns if workflow/jira-to-github/<JIRA-NUMBER>/attachments/ exists and contains files.

Check for attachments:

JIRA_DIR=$(ls -td workflow/jira-to-github/*/ 2>/dev/null | head -1)
ATTACHMENTS_DIR="$JIRA_DIR/attachments"
if [ -d "$ATTACHMENTS_DIR" ] && [ "$(ls -A "$ATTACHMENTS_DIR" 2>/dev/null)" ]; then
  echo "✓ Attachments found - spawning Agent 3"
  # Spawn Agent 3
else
  echo "ℹ No attachments found - skipping Agent 3"
  # Skip this agent
fi

Task Tool Parameters:

• subagent_type: "general-purpose"
• description: "Analyze attachment files"
• model: "sonnet" (better at image/PDF analysis)

Agent Prompt:

You are the Attachments Explorer. Your job is to analyze attachment files for this JIRA issue.

CONTEXT FILES:
- JIRA analysis: workflow/jira-to-github/*/current-issue.md
- Attachments directory: workflow/jira-to-github/*/attachments/

Tasks:

1. Read `current-issue.md` to understand issue context

2. List all files in the attachments directory

3. Analyze each attachment file:
   - **Screenshots/Images**: Identify UI components, layouts, states, interactions
   - **PDFs**: Extract technical specifications, diagrams, documentation
   - **Diagrams**: Identify flows, architectures, relationships
   - **Documents**: Extract requirements, specs, or contextual information

4. Look for:
   - Design patterns or component specifications
   - User flows or interaction patterns
   - Technical architecture or integration diagrams
   - Error states or edge cases shown visually
   - Annotations or comments in screenshots
   - Before/after comparisons
   - Expected vs actual behavior demonstrations

5. Return findings in structured format:

---
## Attachments Analysis Findings

### Files Analyzed
[List all attachment files with type and brief description]

| File | Type | Description |
|------|------|-------------|
| screenshot-1.png | Screenshot | Card payment form with validation error |
| architecture.pdf | Diagram | eProtect integration flow |
| mockup.png | Mockup | Updated UI with delete button |

### Screenshots/Mockups
[For each screenshot or mockup, describe what's shown]

**screenshot-1.png**:
- Shows: Card payment form
- Components: Card number input, CVV field, expiry date
- States: Validation error state visible
- Key details: Error message placement below fields

**mockup.png**:
- Shows: Updated card list UI
- Components: Card item with delete button
- Interactions: Delete confirmation modal
- Key details: Icon placement, spacing, hover state

### Documentation Files
[For PDFs, diagrams, or documents, extract key information]

**architecture.pdf**:
- Technical flow: eProtect tokenization process
- Integration points: Payment gateway API, token storage
- Security requirements: PCI DSS compliance, no card data storage
- Error handling: 5 error codes defined with retry logic

### Design Patterns Identified
[List UI/UX patterns observed in attachments]
- Error message placement: Inline below fields (consistent with screenshot-1.png)
- Button styling: Destructive action uses red color (mockup.png)
- Confirmation pattern: Modal dialog for delete actions (mockup.png)

### Technical Specifications Extracted
[List technical details from diagrams or documents]
- eProtect token format: 16-digit alphanumeric (architecture.pdf)
- API endpoint: /api/v1/tokenize (architecture.pdf)
- Error codes: 401, 402, 403, 404, 500 (architecture.pdf)

### Key Information Extracted
[Consolidated insights from all attachments]
- User flow: Add card → Validate → Tokenize → Store token
- Error handling: Show inline errors, retry on network failure
- Security: Never log card data, use tokens for storage
- UI consistency: Follow existing form validation patterns

### Summary
[1-2 sentences summarizing attachment findings]
---

ERROR HANDLING:
- If no attachments found: Return error (should not spawn if no attachments)
- If file cannot be read: Note which file failed, continue with others
- If image/PDF analysis fails: Note failure, continue with other files
- If attachments empty or irrelevant: Note this explicitly

TOKEN OPTIMIZATION:
- Use tables for file lists
- Keep descriptions concise (10-15 words max)
- Reference file names instead of repeating content
- Focus on actionable insights, not exhaustive descriptions

TARGET OUTPUT: 3-5 KB

Step 3: Ask Clarification Questions

After parallel exploration agents complete, analyze findings and ask the user clarification questions.

Process:

1. Read outputs from all completed exploration agents (External Context, Codebase Patterns, Attachments if present)

2. Analyze for ambiguities and questions:

   • Ambiguous requirements or expected behavior
   • Multiple valid implementation approaches
   • Edge cases not clearly defined in acceptance criteria
   • UI/UX decisions needed (if designs incomplete)
   • Integration points that are unclear
   • Security or performance considerations
   • Error handling strategies not specified

3. Use AskUserQuestion tool to ask clarification questions:

   CRITICAL: Ask as many questions as needed - there is NO limit on question count.

   Guidelines:

   • Ask ALL important questions that significantly impact implementation
   • Include specific options when applicable (2-4 options per question)
   • Provide context for why clarification is needed
   • Keep header short (max 12 chars): "Auth method", "Error UI", "Approach"
   • Make questions actionable and specific
   • Use multiSelect: true when choices are not mutually exclusive

   Example question format: { "question": "How should eProtect validation errors be displayed to the user?", "header": "Error UI", "options": [ {"label": "Inline messages", "description": "Show errors below form fields (recommended for better UX)"}, {"label": "Modal dialog", "description": "Display error details in a modal overlay"}, {"label": "Toast notification", "description": "Show brief toast at top of page"} ], "multiSelect": false }

4. If no clarification needed:

   • Explicitly state: "No clarification questions needed - requirements are unambiguous"
   • Proceed to Step 4

5. Document user responses:

   • Record all answers received
   • Note any additional context provided in responses
   • Identify key decisions made from clarifications

Error Handling:

• If user declines to answer: Document which questions were declined
• If user provides "Other" custom input: Document the full custom response
• If AskUserQuestion tool fails: Try once more, then proceed with note about tool error

Step 4: Request Additional Context

After clarification questions are answered (or skipped), explicitly request additional context from the user.

Display this message to user:

📎 Additional Context Request

Do you have any additional context to share for this implementation?

Please provide (if available):

• Screenshots or mockups beyond what's in Figma/attachments
• Links to similar implementations or examples you want referenced
• External documentation (technical specs, API docs, etc.)
• Code repository links or file paths to reference
• Any other context that would help with planning

You can share:

• File paths to screenshots (I can read them)
• URLs to documentation
• Code repository links
• Or simply describe the context

Type your response or "none" to continue without additional context.

IMPORTANT: Wait for user input. Do NOT proceed without asking.

Document user responses:

If user provides context:

• Screenshots: File paths and descriptions
• External references: URLs with brief descriptions
• Code examples: Repository links or file paths
• Other context: Free-form text from user

If user says "none":

• Document: "User confirmed no additional context to provide"

Never document "No additional context provided" without first asking for it.

Step 5: Consolidate Exploration Findings

After all exploration agents complete and human input is gathered:

1. Read outputs from each agent

2. Validate human input was properly gathered:

   • Check that clarification questions were asked (or explicitly skipped with reason)
   • Check that additional context was requested from user
   • If either is missing: Display warning: "⚠️ Warning: Human context gathering may be incomplete. Proceeding with available information."

3. Create consolidated file at: workflow/jira-to-github/<JIRA-NUMBER>/exploration-summary.md

Consolidation Format:

---
# Exploration Summary: <JIRA-KEY>
*Generated: <timestamp>*

---

## External Context
[IF Agent 1 was spawned, paste output from External Context Explorer]
[IF Agent 1 was skipped: "No Figma/Confluence links found in current-issue.md - external context exploration skipped"]

---

## Codebase Patterns
[Paste output from Codebase Pattern Explorer Agent 2]

---

## Attachments Analysis
[IF Agent 3 was spawned, paste output from Attachments Explorer]
[IF Agent 3 was skipped: "No attachments found in workflow directory"]

---

## Human Input

### Clarification Questions
[Questions asked and answers received from Step 3]

**Questions Asked**:
1. **[Question header]**: [Full question text]
   - Options: [list options provided]

2. **[Question header]**: [Full question text]
   - Options: [list options provided]

[OR if no questions: "No clarification questions needed - requirements are unambiguous"]

**Answers Received**:
1. **[Question header]**: [User's answer/selection]
   - Rationale: [Any additional context user provided]

2. **[Question header]**: [User's answer/selection]
   - Rationale: [Any additional context user provided]

### Additional Context
[Context provided by user from Step 4]

**Screenshots/Mockups**:
- [File paths and descriptions OR "User confirmed no additional screenshots"]

**External References**:
- [URLs and descriptions OR "User confirmed no external references"]

**Other Context**:
- [Free-form context provided OR "User confirmed no additional context"]

### Implementation Preferences
[Consolidated preferences from both steps]
- Preference 1: [Brief description]
- Preference 2: [Brief description]

### Key Decisions Made
[Consolidated decisions from clarifications and context]
- Decision 1: [Brief description]
- Decision 2: [Brief description]

---

## Key Constraints
[Consolidated list of ALL constraints from all agents]

**Design Constraints**:
- [Constraint from Figma]
- [Constraint from designs/attachments]

**Technical Constraints**:
- [Constraint from Confluence]
- [Constraint from codebase patterns]

**User Preferences**:
- [Preference from human input]
- [Preference from human input]

---

## Critical Files Identified
[Consolidated list of ALL file references from all agents]

**From External Context**:
- [Files mentioned in Confluence]

**From Codebase Patterns**:
- path/file1.ts
- path/file2.tsx
- path/test.spec.ts

**From Attachments**:
- [Attachment files analyzed]

**From Human Input**:
- [Any files user mentioned]

---

## Summary
[2-3 sentences consolidating key findings across all exploration]

Key Findings:
- External: [1 sentence summary from Agent 1, OR "Skipped - no external links"]
- Patterns: [1 sentence summary from Agent 2]
- Attachments: [1 sentence summary from Agent 3, OR "Skipped - no attachments"]
- Human: [1 sentence summary from Steps 3 & 4]

---
*Exploration completed with X/Y agents spawned (Agent 1: [spawned/skipped], Agent 2: spawned, Agent 3: [spawned/skipped])*

Error Handling:

• If exploration agent fails, include error note in that section
• Continue with available context from successful agents
• Log errors to workflow/jira-to-github/<JIRA-NUMBER>/errors.log
• Display summary: "Exploration completed with X/Y agents spawned"
• Document which agents were skipped and why (no external links, no attachments)

Target Size: 10-20 KB consolidated file (increased due to attachments + separate human steps)

Step 6: Monitor and Report

After all agents complete and consolidation is done:

1. Display summary to user:

✓ Exploration completed (X/3 agents spawned + human input)
  - External Context: [X KB] - [Figma: Y/N, Confluence: Y/N] OR [Skipped - no links found]
  - Codebase Patterns: [X KB] - [Reference impls: N, Utilities: N]
  - Attachments: [X KB] - [Files analyzed: N] OR [Skipped - no files]
  - Clarification Questions: [N questions asked, N answers received]
  - Additional Context: [Provided/Not provided]
  - Consolidated: exploration-summary.md ([X KB])

Agents spawned:
  - Agent 1 (External Context): [Spawned/Skipped]
  - Agent 2 (Codebase Patterns): Spawned
  - Agent 3 (Attachments): [Spawned/Skipped]

Key findings:
  - [Key finding 1]
  - [Key finding 2]
  - [Key finding 3]

Next step: Run /plan to design the implementation approach

2. If any exploration agents failed:
   • Display: "⚠ Exploration completed with X/Y agents spawned, N failed"
   • List which agents failed and why
   • Note that planning can proceed with partial exploration context

Error Handling

If errors occur during any phase:

Phase 1: Exploration Errors

• Agent 1 (External Context) fails: Continue with remaining agents
• Agent 1 (External Context) skipped: No Figma/Confluence links found, this is normal
• Agent 2 (Codebase Patterns) fails: Continue with remaining agents
• Agent 3 (Attachments) fails: Continue with remaining agents, note missing attachment analysis
• Agent 3 (Attachments) skipped: No attachments found, this is normal
• Step 3 (Clarifications) fails: Proceed without clarifications, note in errors.log
• Step 4 (Additional Context) fails: Proceed without additional context, note in errors.log
• Log all errors to workflow/jira-to-github/<JIRA-NUMBER>/errors.log

Phase 2: Consolidation Errors

• exploration-summary.md write fails: Exit with error, cannot proceed to planning
• Partial exploration data: Create summary with available agent outputs

Common errors:

• No JIRA analysis found: Run /pull first
• Figma access denied: Agent 1 returns empty Figma section, continues
• Confluence access denied: Agent 1 returns empty Confluence section, continues
• Attachment read fails: Agent 3 notes which files failed, continues with others
• User declined clarifications: Document this, exploration completes with note

Token Optimization Summary

This exploration approach optimizes tokens through:

1. Parallel exploration (saves time, not tokens directly)
2. Conditional agent spawning (saves 40-60k tokens per skipped agent):
   • Agent 1: Only spawn if Figma/Confluence links exist in current-issue.md
   • Agent 2: Always spawn (core codebase exploration)
   • Agent 3: Only spawn if attachments directory contains files
   • Pre-check with grep before spawning agents (avoids full conversation context load)
3. Targeted context gathering (saves 20-30k tokens):
   • Check CLAUDE.md first (Agent 2)
   • Targeted searches only (Agent 2)
   • Fetch external docs only when links detected (Agent 1)
   • Analyze attachments only when files present (Agent 3)
4. Context consolidation (saves 10-15k tokens in planning phase):
   • Planning agent will reference exploration-summary.md instead of re-searching
   • Single source of truth for patterns and constraints

Token budget for exploration:

• Minimum (Agent 2 only): ~15-20 KB
• Medium (Agent 2 + 1 conditional): ~30-40 KB
• Maximum (all 3 agents): ~40-50 KB
• Output: 10-20 KB exploration-summary.md

Examples

Examples section can be added after testing with real JIRA issues