Research Technical Approach

Document technical decisions, library evaluations, and architectural choices for a feature.

Full workflow guide: 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

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