Requirements Refinement

Transform vague requests into clear, actionable implementation context through systematic clarification and decomposition.

When to Use This Skill

Analyzing a new feature request
Breaking down complex functionality into smaller pieces
Identifying missing information or assumptions
Creating implementation context for development agents
Scoping work for a PoC or MVP

Core Techniques

1. The 5 Whys for Clarity

Dig deeper to understand the real need:

Request: "We need caching"
Why? → To improve performance
Why? → API calls are slow
Why? → We're making repeated calls
Why? → We don't store results
Why? → We didn't know we'd need them repeatedly

Real need: Store and reuse API responses to avoid repeated calls

2. INVEST-Lite for PoC

Simplified criteria for PoC feature scoping:

Criterion	Question
Independent	Can this be implemented without other pending work?
Negotiable	What's the simplest version that provides value?
Valuable	Does this move the PoC forward?
Estimable	Can we roughly estimate the effort?
Small	Can this be done in a reasonable timeframe?
Testable	How will we know it works?

3. Scope Triangle

For every feature, identify:

         MUST HAVE
            /\
           /  \
          /    \
         /      \
        /________\
   NICE TO HAVE   OUT OF SCOPE

Template:

## Scope Definition

### Must Have (MVP)
- {Core functionality that defines success}

### Nice to Have (If Time Permits)
- {Enhancements that add polish}

### Out of Scope (Explicitly Not Included)
- {Features to defer or exclude}

Clarification Framework

Questions to Always Ask

What:

What problem does this solve?
What does success look like?
What are the inputs and outputs?

Who:

Who will use this feature?
Who needs to be consulted?

When:

When should this run/trigger?
When is this needed by?

Where:

Where does this fit in the architecture?
Where should the code live?

How:

How should errors be handled?
How will this be tested?

Why:

Why is this approach preferred?
Why now (priority)?

Structured Clarification Template

## Clarification Needed

### Understanding Check
I understand you want to: {paraphrase the request}

### Clarifying Questions

1. **{Topic}**: {Question}
   - Option A: {possibility}
   - Option B: {possibility}
   - Default assumption: {what you'll assume if no answer}

2. **{Topic}**: {Question}
   ...

### Assumptions (if no clarification provided)
- {Assumption 1}
- {Assumption 2}

Decomposition Patterns

Feature Decomposition

Break large features into implementable pieces:

Feature: Workflow Validation
├── Schema Validation
│   ├── YAML syntax validation
│   └── Required fields validation
├── Semantic Validation
│   ├── Dependency existence check
│   └── Circular dependency detection
└── Integration
    ├── CLI command integration
    └── Error message formatting

Vertical Slice Approach

Instead of building layers, build thin vertical slices:

❌ Horizontal (risky for PoC):
Layer 1: All models
Layer 2: All business logic
Layer 3: All CLI commands

✅ Vertical (better for PoC):
Slice 1: One complete flow (model → logic → CLI)
Slice 2: Another complete flow
Slice 3: ...

Dependency Mapping

Identify what must come first:

## Implementation Order

### Phase 1: Foundation
- [ ] {Task with no dependencies}
- [ ] {Another independent task}

### Phase 2: Core Features (depends on Phase 1)
- [ ] {Task} ← depends on {Phase 1 task}

### Phase 3: Integration (depends on Phase 2)
- [ ] {Final integration task}

Constraint Identification

Technical Constraints Checklist

Language/Framework: What must we use?
Dependencies: What libraries are available/allowed?
Compatibility: What versions must we support?
Performance: Any speed/memory requirements?
Security: Any sensitive data handling?

Project Constraints Checklist

Time: When is this needed?
Complexity: How complex can the solution be?
Maintenance: Who will maintain this?
Patterns: What existing patterns must we follow?

Constraint Documentation

## Constraints

### Must Follow
- Use existing Pydantic patterns from `src/orchestrator/models/`
- Follow Typer CLI conventions established in the project
- Maintain type hints and pass mypy checks

### Should Avoid
- Adding new external dependencies without justification
- Complex solutions when simple ones suffice
- Breaking existing functionality

### Cannot Do
- Change the fundamental project structure
- Modify CI/CD without team discussion

Context Document Template

Use this template when creating implementation context:

# {Feature Name} - Implementation Context

## Overview

{2-3 sentences describing what needs to be built and why}

## Goals

**Primary**: {The main thing this must accomplish}

**Secondary**:
- {Additional benefit}
- {Another benefit}

## Scope

### In Scope
- {What's included}

### Out of Scope
- {What's explicitly not included}

## Constraints

| Type | Constraint | Rationale |
|------|------------|-----------|
| Technical | {constraint} | {why} |
| Project | {constraint} | {why} |

## Recommended Approach

{Describe the recommended implementation approach}

### Why This Approach
- {Reason 1}
- {Reason 2}

### Alternatives Considered
- **{Alternative}**: {Why not chosen}

## Implementation Guidance

### Files to Create/Modify

| File | Action | Purpose |
|------|--------|---------|
| `path/to/file.py` | Create | {What it does} |
| `path/to/existing.py` | Modify | {What to change} |

### Patterns to Follow

Reference: `{path/to/example/code}`

```python
# Example pattern from codebase
{code snippet showing the pattern}

Key Considerations

{Important thing to keep in mind}
{Another consideration}

Testing Approach

{How to verify this works}
{Edge cases to test}

Open Questions

{Question that may need answering during implementation}

Created: {Date} Status: Ready for Implementation


## Anti-Patterns to Avoid

### ❌ Gold Plating
Adding features or complexity not requested:
- Stick to what's needed for the PoC
- Note nice-to-haves separately

### ❌ Analysis Paralysis
Over-analyzing before starting:
- Perfect is the enemy of good
- Start with what you know, iterate

### ❌ Assumed Requirements
Building based on assumptions without validation:
- Document assumptions explicitly
- Ask when uncertain

### ❌ Scope Creep
Gradually expanding what's included:
- Define scope upfront
- Push back on additions

## Integration with Agents

This skill is primarily used by:
- **Requirements Analyst** - For creating implementation context
- **Documentation Engineer** - For understanding what to document
- **Python Expert** - For understanding implementation scope

requirements-refinement