Skip to main content
Agent skill

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 started

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?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/shep-kitresearch
# Save SKILL.md to ~/.claude/skills/shep-kitresearch/SKILL.md
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.