// Autonomously investigates REQUIRES-INVESTIGATION tasks through deep parallel research (internal and external), synthesizes findings, and either resolves with an actionable task or escalates to HUMAN-TASK when genuine human judgment is needed. Use when autonomous-development creates investigation tasks.
Reviews completed work by exploring features as a user would, finding gaps between intent and implementation, writing failing tests for real issues, and creating tickets for genuine problems. Runs automatically after all planned tasks complete.
Autonomously discovers ready tasks from Tickets, executes them with Research → Implement → Verify cycles, continuing with related work while context remains healthy - invoke directly without specifying a task
Creates new Claude Code agent skills with proper structure, frontmatter, and best practices. Use when the user wants to create a new skill, add capabilities, or extend Claude with domain-specific expertise.
Translates finalized feature plans into comprehensive tickets for autonomous development. Use after project-planning and reviewing-plans sessions are complete. Creates self-contained tickets with inlined requirements and verification commands.
Orchestrates comprehensive feature planning through autonomous research phases and map-reduce cycles. Researches codebase first to understand current state, only interviews user for human judgment questions, then runs research waves after each interview round. Produces detailed implementation plans with executable verification commands.
Captures project vision and philosophy through structured interview, producing comprehensive vision documentation and condensed summary. Use before project-planning for new projects or major architectural work requiring design alignment. Ensures blockers and autonomous development can align with project goals.
| name | investigate-blocker |
| description | Autonomously investigates REQUIRES-INVESTIGATION tasks through deep parallel research (internal and external), synthesizes findings, and either resolves with an actionable task or escalates to HUMAN-TASK when genuine human judgment is needed. Use when autonomous-development creates investigation tasks. |
Autonomously resolve blockers that require deeper investigation before implementation can proceed. This skill bridges the gap between "I'm stuck" and "wait for human" by performing thorough research to find answers.
IMPORTANT: Always run tk help first to confirm current command syntax.
Designed for headless operation within the autonomous loop:
while true; do
# Check for investigation tasks (grep tk ready output for title patterns)
if tk ready 2>/dev/null | grep -q "REQUIRES-INVESTIGATION:"; then
claude -p "Use investigate-blocker skill"
else
claude -p "Use autonomous-development skill"
fi
sleep 2
done
Key principle: This skill exists to find answers. It searches wherever answers exist—codebase, documentation, web, standards—based on what the problem requires.
Research scope is entirely determined by the nature of the problem:
| Problem Type | Research Scope |
|---|---|
| Project-internal confusion | Codebase only |
| Library/framework question | Fetch official docs |
| Browser/platform API | MDN, platform docs |
| Industry convention | Web search for standards |
| Recent feature (post-training) | Active web research required |
| Integration question | Both internal patterns + external docs |
The goal is answers. Get them from wherever they exist.
Only resolve when the answer is clear and well-supported.
Resolve if:
Escalate to HUMAN-TASK if:
Conservative default: When uncertain, escalate. Incorrect autonomous decisions are costly.
You are a COORDINATOR. You dispatch sub-agents and route information.
Your responsibilities:
You NEVER:
1. EXTRACTION
- Find REQUIRES-INVESTIGATION ticket(s)
- Extract context, dependency chain, specific questions
2. SCOPING
- Classify blocker type
- Determine research scope (internal, external, or both)
- Define specific questions to answer
3. RESEARCH FAN-OUT (parallel)
- Deploy research sub-agents based on scope
- Internal: codebase patterns, constraints, history
- External: docs, standards, web (as needed)
3.5. PRIOR ART RESEARCH (when design questions detected)
- Deploy parallel sub-agents to research how industry/community solved this
- Search specifications, academic papers, major implementations
- Determine consensus level (unanimous, majority, split, none)
- Synthesize findings with confidence assessment
4. SYNTHESIS
- Aggregate findings (including prior art if gathered)
- Identify viable options
- Evaluate against project constraints
- Rank recommendations
5. RESOLUTION
- If clear winner: create actionable task
- If still ambiguous: create HUMAN-TASK with findings
- Update dependency chain
6. EXIT
- Report outcome
- STATUS: RESOLVED or ESCALATED
tk query '.[] | select(.title | startswith("REQUIRES-INVESTIGATION:"))'
Deploy Extraction sub-agent:
Extract investigation context.
Task ID: [investigation-task-id]
Instructions:
1. Run: tk show [investigation-task-id]
2. Parse the task to extract:
- The specific question or confusion
- What was being worked on when this arose
- Any context provided in the description
3. Run: tk dep tree [investigation-task-id]
4. Identify what work is blocked waiting for resolution
5. Check if related tasks provide additional context
Return:
- Core question (1-2 sentences)
- Context summary
- Blocked work list
- Any clues about research direction
Deploy Scoping sub-agent:
Classify and scope the investigation.
Context: [extraction summary]
Instructions:
1. Classify the blocker type:
- DESIGN_DECISION: Multiple valid approaches, need to pick one
- MISSING_INFORMATION: Something unknown about requirements/constraints
- TECHNICAL_UNCERTAINTY: Unclear how to implement something
- EXTERNAL_DEPENDENCY: Question about library/API/platform behavior
- CONFLICTING_CONSTRAINTS: Requirements seem incompatible
2. Determine research scope:
- INTERNAL_ONLY: Answer exists within project codebase/docs
- EXTERNAL_ONLY: Answer requires external documentation/standards
- HYBRID: Needs both internal patterns AND external guidance
3. Define specific research questions (2-5 questions that, if answered, resolve the blocker)
Return:
- Blocker classification
- Research scope
- Specific questions to answer
- Recommended research angles
Internal Research (when scope includes INTERNAL):
Research: Internal codebase patterns for [topic]
Questions to answer:
1. [Specific question]
2. [Specific question]
Instructions:
1. Read ~/CLAUDE.md and project CLAUDE.md first
2. Search for existing implementations of similar functionality
3. Look for documented decisions or constraints
4. Check for related tests that reveal expected behavior
5. Find any prior art or historical context
Return:
- Findings organized by question
- Relevant file paths with line numbers
- Patterns discovered
- Constraints identified
- Gaps (questions that couldn't be answered internally)
External Research (when scope includes EXTERNAL):
Research: External documentation for [topic]
Questions to answer:
1. [Specific question]
2. [Specific question]
Instructions:
1. Identify the authoritative sources for this topic:
- Official library/framework documentation
- Platform docs (MDN for web APIs, etc.)
- RFCs or specifications (if standards-based)
- Reputable technical resources
2. Fetch and analyze relevant documentation
3. Look for recommended practices or patterns
4. Note any version-specific considerations
5. Find concrete examples if available
Return:
- Findings organized by question
- Source URLs
- Recommended approaches from authoritative sources
- Caveats or version considerations
- Gaps (questions that couldn't be answered externally)
Industry Standards Research (when needed):
Research: Industry standards and conventions for [topic]
Instructions:
1. Search for established patterns and best practices
2. Look for security considerations (OWASP, etc. if relevant)
3. Find performance or scalability guidance
4. Check for common pitfalls to avoid
5. Note any consensus vs. contested approaches
Return:
- Established conventions found
- Security/performance considerations
- Common pitfalls
- Sources (prioritize authoritative over blog posts)
Deploy all relevant research sub-agents in a single message with multiple Task calls.
When to use this stage: When the investigation involves architectural decisions, design patterns, or fundamental implementation approaches - especially when Stage 3 research reveals multiple valid options without a clear winner.
Key principle: Most problems have been solved before. Before escalating design questions to HUMAN-TASK, search for how the broader community/industry has tackled similar challenges.
If synthesis of Stage 3 research shows:
→ Deploy prior art research before deciding to escalate.
Fan out multiple research agents in parallel, each targeting different aspects of prior art:
Research: Prior art for [problem domain] - [specific aspect]
Context:
- Core question: [the design question]
- Domain: [e.g., "programming language semantics", "distributed systems", "authentication flows"]
- Current findings: [summary from Stage 3]
Instructions:
1. Search for how established systems/projects handle this:
- Academic papers and technical literature
- Well-known open source implementations
- Industry standards and RFCs
- Language specifications (if applicable)
- Platform documentation from major vendors
2. For each approach found:
- Document the design choice made
- Extract the rationale (why they chose this approach)
- Note trade-offs or limitations mentioned
- Identify if there's consensus or variation
3. Look specifically for:
- **Consensus patterns**: Do most implementations converge on one approach?
- **Historical evolution**: Did the community try approach A then move to B?
- **Known pitfalls**: Are there documented failures or anti-patterns?
- **Performance/security implications**: What do the experts say?
4. Evaluate source quality:
- Prioritize: specifications, academic papers, major OSS projects, authoritative docs
- De-prioritize: blog posts, tutorials, Stack Overflow (unless corroborating)
- Note publication dates (recent vs historical)
Return:
- Summary of approaches found across the ecosystem
- Level of consensus (unanimous, majority, split, no clear pattern)
- Recommended approach based on prior art with supporting evidence
- Caveats or contexts where recommendations differ
- Quality of sources (how authoritative is this finding?)
Deploy 3-5 parallel research agents, each exploring different angles:
After prior art research completes, deploy a prior art synthesis sub-agent:
Synthesize prior art research findings.
Context:
- Original question: [from extraction]
- Internal/external research: [summary from Stage 3]
- Prior art research: [file paths to all prior art reports]
Instructions:
1. Read all prior art research reports
2. Determine consensus level:
- UNANIMOUS: All major implementations agree
- STRONG_MAJORITY: >75% converge on one approach
- WEAK_MAJORITY: >50% but significant variation
- SPLIT: Multiple competing approaches, no clear winner
- NO_PATTERN: Insufficient data or highly context-specific
3. If consensus exists:
- State the consensus approach clearly
- Document the rationale from literature
- Note any contexts where it doesn't apply
- HIGH CONFIDENCE → likely can resolve autonomously
4. If split or no pattern:
- Document the competing approaches
- Extract decision criteria used by different implementations
- Identify if our project constraints favor one approach
- LOWER CONFIDENCE → may need escalation
5. Integration check:
- Does the prior art approach align with our project patterns?
- Are there constraints that make the standard approach unsuitable?
- What adaptation would be needed?
6. Vision alignment (if docs/VISION.md exists):
- Read the project vision document
- Check if prior art approach aligns with design philosophy
- Verify compatibility with stated optimization targets
- Flag if prior art contradicts anti-goals
- If consensus approach conflicts with vision, note the tension
- Consider if vision provides tiebreaker for SPLIT consensus
Return:
- Consensus level and confidence
- Recommended approach based on prior art
- Vision alignment assessment (if applicable)
- How this integrates with earlier research findings
- Updated resolution assessment (CLEAR_RESOLUTION vs NEEDS_HUMAN)
After prior art synthesis:
If consensus is UNANIMOUS or STRONG_MAJORITY:
If consensus is SPLIT or NO_PATTERN:
Key principle: Prior art doesn't remove human judgment for business decisions, but it can autonomously resolve technical questions that have established industry answers.
Deploy Synthesis sub-agent:
Synthesize research findings.
Context:
- Original question: [from extraction]
- Blocker type: [from scoping]
- Research findings: [file paths to all research reports]
- Prior art findings: [file paths if Stage 3.5 was performed]
Instructions:
1. Read all research report files (internal, external, AND prior art if available)
2. For each original question:
- What answer emerged from project research?
- What answer emerged from prior art (if researched)?
- How confident? (HIGH/MEDIUM/LOW)
- Any contradictions between sources?
- Does prior art consensus strengthen or weaken confidence?
3. Identify viable options:
- What approaches are supported by research?
- What approaches have industry consensus (from prior art)?
- What are the trade-offs of each?
4. Evaluate each option against:
- Alignment with existing project patterns
- Industry consensus (if prior art research was performed)
- Simplicity (PRIME DIRECTIVE)
- Risk and complexity
- Future flexibility
- Security implications (if relevant)
5. Produce ranked recommendations:
- #1 recommendation with rationale
- Supporting evidence (internal patterns + prior art consensus if applicable)
- Alternatives with trade-offs
- Any remaining uncertainties
6. Make resolution assessment:
- CLEAR_RESOLUTION: One option is clearly correct (especially if prior art shows unanimous consensus)
- VIABLE_OPTIONS: Multiple good options, slight preference for one
- STILL_AMBIGUOUS: Research didn't resolve the core question
- NEEDS_HUMAN: Question is subjective/business-critical
Return:
- Summary of findings (including prior art consensus level if researched)
- Ranked options with trade-offs
- Resolution assessment
- Recommended action
CLEAR_RESOLUTION or VIABLE_OPTIONS → Create Actionable Task:
# Create the resolution task
tk create "[Original feature]: [Specific implementation]" \
--type task \
--priority [same as investigation task] \
--description "$(cat <<'EOF'
## Summary
[What to implement based on research findings]
## Decision Made
[The approach chosen and why]
## Research Context
[Key findings that support this decision]
## Implementation Notes
[Specific guidance for implementation]
## Files
[Files to create/modify]
## Verification
[How to verify the implementation is correct]
EOF
)"
# Link dependencies: new task blocks what investigation was blocking
tk dep [blocked-task-id] [new-task-id]
# Close the investigation task
tk close [investigation-task-id]
STILL_AMBIGUOUS or NEEDS_HUMAN → Escalate to HUMAN-TASK:
# Create narrower HUMAN-TASK with synthesized findings
tk create "HUMAN-TASK: [Specific decision needed]" \
--type task \
--priority 0 \
--description "$(cat <<'EOF'
## Decision Needed
[Specific question for human - much narrower than original]
## Research Performed
[Summary of investigation done]
## Options Identified
### Option A: [Name]
- Description: [what this approach involves]
- Pros: [advantages]
- Cons: [disadvantages]
- Supported by: [which research]
### Option B: [Name]
- Description: [what this approach involves]
- Pros: [advantages]
- Cons: [disadvantages]
- Supported by: [which research]
## Why Escalation is Needed
[Explain why autonomous resolution wasn't possible]
## Recommendation
[If you have a slight preference, state it with caveats]
EOF
)"
# Update dependencies
tk dep [blocked-task-id] [new-human-task-id]
# Close original investigation task
tk close [investigation-task-id]
# INVESTIGATE-BLOCKER SESSION SUMMARY
## Task Investigated
- **ID:** [investigation-task-id]
- **Question:** [original question]
## Research Performed
- **Scope:** [INTERNAL_ONLY | EXTERNAL_ONLY | HYBRID]
- **Sub-agents deployed:** [count]
- **Sources consulted:** [list key sources]
## Findings Summary
[2-3 sentence summary of what was learned]
## Resolution
- **Status:** [RESOLVED | ESCALATED]
- **Action taken:** [created task X | created HUMAN-TASK Y]
- **Rationale:** [why this resolution]
## Dependency Updates
- Closed: [investigation-task-id]
- Created: [new-task-id or human-task-id]
- Now unblocked: [list of tasks that can proceed]
---
EXIT_STATUS: [RESOLVED|ESCALATED|ERROR]
Don't limit research artificially. If the answer is in MDN, fetch MDN. If it's in a library's GitHub issues, search there. The goal is resolution.
Only resolve autonomously when confident. A wrong autonomous decision creates more work than an escalation.
When escalating, the HUMAN-TASK should be more specific than the original REQUIRES-INVESTIGATION. Include:
Always update the dependency chain:
tk dep tree that structure is correctEither fully resolve (actionable task) or fully escalate (HUMAN-TASK). Don't leave investigation tasks open or create ambiguous tasks.
This skill is part of the two-tier escalation system:
autonomous-development
↓ (hits confusion)
Creates: REQUIRES-INVESTIGATION task
↓
investigate-blocker
↓
├─ RESOLVED → actionable task → autonomous-development continues
└─ ESCALATED → HUMAN-TASK → loop pauses for human input
The bash loop handles skill selection:
while true; do
INVESTIGATION_COUNT=$(tk query '[.[] | select(.title | startswith("REQUIRES-INVESTIGATION:"))] | length' 2>/dev/null || echo "0")
if [ "$INVESTIGATION_COUNT" -gt 0 ]; then
echo "Investigation task found, running investigate-blocker..."
claude -p "Use investigate-blocker skill" || break
else
claude -p "Use autonomous-development skill" || break
fi
sleep 2
done