Shep Kit:Research
Use after /shep-kit:new-feature to analyze technical approach, evaluate libraries, document decisions. Triggers include "research", "technical analysis", "evaluate options", "which library", or explicit /shep-kit:research invocation. Part of the Shep autonomous SDLC platform — https://shep.bot
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Shep Kit:Research when an AI agent needs a reusable SKILL.md workflow for this job: Use after /shep-kit:new-feature to analyze technical approach, evaluate libraries, document decisions. Triggers include "research", "technical analysis", "evaluate options", "which library", or explicit /shep-kit:research invocation. Part of the Shep autonomous SDLC platform — https://shep.bot
When not to use it
Skip Shep Kit:Research when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/shep-kitresearch # Save SKILL.md to ~/.claude/skills/shep-kitresearch/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/shep-kitresearch/SKILL.md. For a shared project, commit the folder at .claude/skills/shep-kitresearch/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Shep Kit:Research skill for this task: Use Shep Kit:Research when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 62/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Research Technical Approach
Document technical decisions, library evaluations, and architectural choices for a feature.
**Full workflow guide:** [docs/development/spec-driven-workflow.md](../../../docs/development/spec-driven-workflow.md)
## Prerequisites
- Feature spec exists at `specs/NNN-feature-name/spec.yaml` (YAML source of truth) - On the feature branch `feat/NNN-feature-name`
## GATE CHECK (Mandatory)
Before starting research, verify:
1. **Read `spec.yaml`** and check the `openQuestions` array 2. **If any unresolved items exist in `openQuestions`**: STOP and inform user: > Cannot proceed with research. Open questions in spec.yaml must be resolved first. > Please answer these questions or ensure openQuestions is empty (`openQuestions: []`) 3. **Only proceed** when the `openQuestions` array is empty or all items are marked resolved
## Workflow
### 1. Identify Current Feature
Determine which feature we're researching:
- Check current branch name - Or ask user which spec to research - Read `specs/NNN-feature-name/spec.yaml` for context
### 2. Identify Technical Decisions
From the spec, identify decisions that need research:
- Technology/library choices - Architecture patterns - Integration approaches - Performance strategies
### 3. Research Each Decision
For each technical decision:
**Analyze options:**
- List 2-4 viable approaches - Research each using web search, documentation - Consider project constraints (from `CLAUDE.md`, existing patterns)
**Evaluate trade-offs:**
- Pros and cons of each option - Compatibility with existing stack - Learning curve, maintenance burden - Performance implications
**Make recommendation:**
- Choose best option with clear rationale - Document why alternatives were rejected
### 4. Document Security & Performance
Identify and document:
- Security considerations specific to this feature - Performance implications and optimizations
### 5. Write research.yaml and Generate Markdown
Write research output to `specs/NNN-feature-name/research.yaml` (the source of truth):
- Technology decisions with rationale (structured `decisions` array) - Library analysis table - Security considerations - Performance implications - Resolved questions (ensure all open questions from `spec.yaml` are addressed)
### 6. Update Status Fields & feature.yaml
**CRITICAL:** Update status in YAML source files and feature.yaml:
```yaml # In spec.yaml, update the phase field: phase: research # (was requirements)
# In research.yaml, keep: phase: research updatedAt: '<today's date>' ```
**Update feature.yaml:**
```yaml # specs/NNN-feature-name/feature.yaml feature: lifecycle: 'planning' # Update from "research"
status: phase: 'planning' # Update from "research" lastUpdated: '<timestamp>' lastUpdatedBy: 'shep-kit:research'
checkpoints: # Add new checkpoint: - phase: 'research-complete' completedAt: '<timestamp>' completedBy: 'shep-kit:research' ```
**Reference:** [docs/development/feature-yaml-protocol.md](../../../docs/development/feature-yaml-protocol.md)
### 7. Commit
```bash git add specs/NNN-feature-name/ git commit -m "feat(specs): add NNN-feature-name research" ```
### 8. Next Steps
Inform the user:
> Research complete for `NNN-feature-name`! > Next: `/shep-kit:plan` to create implementation plan.
## Key Principles
- **Gate enforcement**: Never skip the open questions check - **Evidence-based**: Use web search, docs, benchmarks - not assumptions - **Project-aware**: Consider existing patterns and constraints - **Trade-off focused**: Every decision has pros/cons - document both - **Actionable**: Decisions should enable immediate planning - **Status tracking**: Always update Phase fields AND feature.yaml before committing - **feature.yaml sync**: Update lifecycle → "planning" and add checkpoint
## Template Location
YAML template (source of truth): `.claude/skills/shep-kit-new-feature/templates/research.yaml`
## Example
See: `.claude/skills/shep-kit-research/examples/sample-research.md`
Intended uses
- Use Shep Kit:Research when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.