define-requirements

name	define-requirements
description	Guides users through Jobs-to-be-Done discovery to define feature requirements before implementation. Use when user wants to define, document, or plan a new feature or enhancement. Interviews for problem and jobs, analyzes codebase, produces TDD-focused implementation plan ready for GitHub issue creation.

Define Requirements

Purpose

This skill guides agentic coders through a structured Jobs-to-be-Done (JTBD) discovery process to ensure features are well-defined before implementation. It interviews the user to understand the problem and jobs, analyzes the codebase for implementation impact, and prepares everything needed for GitHub issue creation.

Core Principles

1. Problem First, Always

Never jump to solutions. Understand what problem exists and why it matters before discussing how to solve it.

2. Jobs-to-be-Done Framework

Features exist to help users accomplish jobs. Map every feature to the specific jobs it satisfies.

3. Engineering Excellence

Recommendations follow best practices: TDD, security-first, existing patterns, and project conventions.

4. No Blind Spots

Systematically cover all aspects: problem, jobs, functionality, codebase impact, security, testing.

5. Efficient for the User

Ask smart questions, build on answers, don't repeat. Do the heavy lifting of analysis.

When to Use

Activate when user:

• Wants to define or document a new feature
• Says "let's plan this feature" or "help me define requirements"
• Needs to think through what a feature should do
• Wants to create a well-structured GitHub issue for a feature

Don't use for:

• Quick bug fixes with obvious solutions
• Pure research or exploration tasks
• Implementation (use after requirements are defined)

Workflow Overview

1. Problem Definition
   ↓
2. JTBD Interview (functional jobs + optional depth)
   ↓
3. CHECKPOINT: Confirm understanding
   ↓
4. Read CLAUDE.md for project conventions
   ↓
5. Codebase Analysis (deep, comprehensive)
   ↓
6. Implementation Recommendations (TDD-focused)
   ↓
7. CHECKPOINT: Summary + ready for GitHub issue?
   ↓
8. Handoff to github-issue-creator skill

Phase 1: Problem Definition

Start every session by understanding the problem. Ask ONE question at a time.

Opening Question

"What problem are you trying to solve? Describe what's not working or what's missing today."

Follow-up Probes (as needed)

• "Who experiences this problem?"
• "How often does this occur?"
• "What's the impact when this problem isn't solved?"
• "What triggered you to address this now?"

Red Flags to Challenge

If user jumps to solutions:

"I hear you want to build [feature]. Before we go there—what problem does this solve? What's painful today without it?"

If problem is vague:

"Can you give me a specific example of when this problem occurred?"

Phase 2: Jobs-to-be-Done Interview

Once the problem is clear, map the jobs users need to accomplish.

Core Question

"When users encounter this problem, what are they trying to accomplish? What job are they hiring this feature to do?"

Functional Jobs (Always Ask)

• "What specific task does the user need to complete?"
• "What does success look like when that job is done?"
• "Are there multiple jobs, or variations of the same job?"

Offer Depth Choice

After capturing functional jobs:

"I have a good understanding of the functional jobs. Would you like to explore:

1. Just functional (faster) — proceed with what we have
2. Include emotional/social (fuller picture) — how users want to feel, how they want to be perceived"

If User Chooses Deeper Exploration

• "How do users want to feel when doing this? (Confident? In control? Relieved?)"
• "Is there a social dimension? (Looking competent to others? Meeting expectations?)"

Map Functionality to Jobs

For each job identified:

"What specific functionality would satisfy this job? Let's map it out."

Build a table:

Job	Functionality Required	Success Criteria
[Job 1]	[Feature/capability]	[How we know it's done]

Phase 3: Checkpoint — Confirm Understanding

Before investing in codebase analysis, confirm alignment.

Present Summary

## Summary: Jobs to be Done

**Problem**: [Concise problem statement]

**Target User**: [Who has this problem]

**Jobs Identified**:
1. **[Job 1]**: [Description]
   - Functionality: [What's needed]
   - Success: [Criteria]

2. **[Job 2]**: [Description]
   - Functionality: [What's needed]
   - Success: [Criteria]

[Continue for all jobs]

Confirm

"Does this accurately capture what we're trying to accomplish? Any jobs missing or misunderstood? Once confirmed, I'll analyze the codebase to understand implementation impact."

Wait for explicit confirmation before proceeding.

Phase 4: Read Project Conventions

Before analyzing code, read the project's CLAUDE.md to understand:

• Architecture patterns (DAL, tenant isolation, etc.)
• Testing requirements
• Security considerations
• Code organization conventions

Use the Read tool on:

1. Root CLAUDE.md
2. app/CLAUDE.md (if exists)
3. Any referenced architecture docs

Phase 5: Codebase Analysis

Perform a comprehensive, deep analysis. Use Explore agent or direct tools.

What to Analyze

1. Existing Patterns

• How does the codebase handle similar features?
• What patterns should this feature follow?
• Are there utilities or helpers to leverage?

2. Files to Modify

• Which existing files need changes?
• Specific line numbers where changes occur
• Code snippets showing current state

3. New Files Needed

• Components, pages, actions, types
• Where they should live (follow conventions)

4. Database Impact

• Schema changes needed?
• New tables, columns, relationships?
• Migration requirements
• RLS policies needed

5. API/Actions

• Server actions to create/modify
• API endpoints affected
• Data flow changes

6. Test Files

• Existing tests that need updates
• New test files needed
• Test patterns to follow

Security Review

CRITICAL: Flag any security concerns:

• Does this expose sensitive data?
• Are there tenant isolation implications?
• Input validation requirements?
• Authentication/authorization impacts?

If security risk detected:

"Security Warning: This requirement could [specific risk]. I recommend [mitigation]. Do you want to proceed with these safeguards in place?"

Anti-Pattern Detection

Check requirements against known anti-patterns:

• Bypassing DAL for direct DB access
• Client-side data fetching for sensitive data
• Missing tenant_id enforcement
• Skipping input validation

If anti-pattern detected:

"Warning: The approach you're describing would [anti-pattern]. Best practice is to [correct approach]. Should we adjust the requirement?"

Phase 6: Implementation Recommendations

Generate TDD-focused, best-practice recommendations.

Structure

## Implementation Plan

### TDD Approach
This feature should be implemented using strict Test-Driven Development:

**Phase 1: [Component/Feature]**
1. Write failing test for [specific behavior]
2. Implement minimal code to pass
3. Refactor while green

**Phase 2: [Next Component]**
[Continue pattern]

### Files to Create
| File | Purpose | Tests |
|------|---------|-------|
| `path/to/file.tsx` | [Purpose] | `__tests__/path/file.test.ts` |

### Files to Modify
| File | Changes | Line References |
|------|---------|-----------------|
| `path/to/existing.tsx` | [What changes] | Lines 45-67 |

### Database Changes
[Migration details if needed]

### Security Considerations
[Any security notes]

### Dependencies
[Prerequisites or related changes]

Phase 7: Checkpoint — Ready for GitHub Issue

Present complete summary before handoff.

Final Summary

# Feature Requirements Summary

## Problem
[Problem statement]

## Jobs to be Done
[Job summary with functionality mapping]

## Implementation Overview
- **Files to create**: [count]
- **Files to modify**: [count]
- **Database changes**: [yes/no + summary]
- **Estimated test files**: [count]

## Key Recommendations
1. [Top recommendation]
2. [Second recommendation]
3. [Third recommendation]

## Security Notes
[Any security considerations]

## TDD Workflow
[High-level TDD phases]

Prompt for Handoff

"This captures the full requirements and implementation plan. Ready to create the GitHub issue? I'll invoke the github-issue-creator skill which will format this for the next developer and include the mandatory TDD workflow."

Phase 8: Handoff

When user confirms, invoke the github-issue-creator skill with all gathered context.

The handoff should include:

• Problem statement
• Jobs-to-be-Done mapping
• All codebase analysis findings
• Specific file references with line numbers
• TDD implementation plan
• Security considerations
• Testing requirements

The github-issue-creator will structure this into a comprehensive issue.

Interview Style Guidelines

Do

• Ask one question at a time
• Build on previous answers
• Use the user's language back to them
• Offer choices when appropriate (e.g., depth level)
• Confirm understanding before major transitions

Don't

• Dump multiple questions at once
• Assume you know what they mean
• Skip the problem to jump to solutions
• Proceed without explicit confirmation at checkpoints
• Ignore security or anti-pattern concerns

Quality Checklist

Before each checkpoint, verify:

After JTBD Interview:

• Problem is clearly articulated
• Target user identified
• All functional jobs captured
• Functionality mapped to each job
• Success criteria defined

After Codebase Analysis:

• CLAUDE.md conventions reviewed
• Existing patterns identified
• All affected files listed with line references
• Database impact assessed
• Security review completed
• Anti-patterns checked
• TDD approach defined
• Test files identified

Remember

• You're the expert guide: Users have basic PM knowledge—provide structure and guardrails
• Efficiency matters: Don't ask questions you can answer from context
• Security is non-negotiable: Always flag risks, never proceed blindly
• TDD is mandatory: Every recommendation should have tests-first approach
• The goal is clarity: A developer should be able to implement from the GitHub issue without asking questions