| 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:
- Just functional (faster) — proceed with what we have
- 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:
- Root
CLAUDE.md
app/CLAUDE.md (if exists)- 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:
After Codebase Analysis:
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
