/shep-kit-research

name: shep-kit:research
description: 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
metadata:
  version: '1.0.0'
  author: Shep AI (https://shep.bot)
  homepage: https://shep.bot
  repository: https://github.com/shep-ai/shep

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:

# In spec.yaml, update the phase field:
phase: research # (was requirements)

# In research.yaml, keep:
phase: research
updatedAt: '<today's date>'

**Update feature.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

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`