Product Agent

The Product Agent specializes in transforming vague feature ideas into clear, actionable requirements. It gathers requirements from stakeholders, writes user stories with acceptance criteria, and validates features before epic planning.

Capabilities

• Interview stakeholders and gather requirements using proven questioning techniques
• Create detailed user personas with goals and pain points
• Write user stories in standard "As a... I want... so that..." format
• Define acceptance criteria using Given/When/Then format
• Identify edge cases and error scenarios that developers might miss
• Define success metrics for features
• Manage scope to prevent scope creep
• Clarify fuzzy requirements before hand-off to epic planning

When to Use

Use this agent when:

• Vague feature requests - "Add user profiles" needs clarity before development
• Starting a new epic - Gather and clarify requirements first
• Complex features - Need edge case analysis and acceptance criteria
• Stakeholder interviews needed - Understand user needs and business value
• Scope debates - Determine what's in/out for this release
• User story writing - Convert requirements into testable acceptance criteria
• Feature validation - Confirm feature solves the actual user problem

How It Works

The Product Agent follows a structured workflow:

Step 1: Knowledge Loading

Before starting requirements gathering:

• Read CLAUDE.md for product strategy
• Check docs/10-research/ for user research and competitive analysis
• Check docs/03-decisions/ for product ADRs and precedents
• Check docs/08-project/roadmap.md for context

Step 2: Stakeholder Interviews

Ask key questions to understand the feature:

1. "Why do we need this feature?" → Business value and outcomes
2. "Who will use this?" → User personas and roles
3. "What problem does it solve?" → Problem statement
4. "How will success be measured?" → Success metrics
5. "What are edge cases?" → Error scenarios and boundary conditions
6. "Are there constraints?" → Technical, legal, or business constraints
7. "What's the priority?" → Must-have vs. nice-to-have

Step 3: Write User Stories

Create stories in standard format:

CopyAs a [user role],
I want [action/feature],
so that [benefit/value].

Example:

CopyAs a new user,
I want to sign up with email and password,
so that I can access my account and manage my data.

Step 4: Define Acceptance Criteria

Write testable criteria using Given/When/Then format:

CopyAcceptance Criteria:
 
- Given a new user with valid email and strong password
  When they submit the signup form
  Then their account is created and verification email sent
 
- Given a user with an already-registered email
  When they try to signup
  Then they see error "Email already in use"
 
- Given a user with weak password
  When they try to signup
  Then they see error "Password must be 8+ chars with uppercase and number"

Step 5: Identify Edge Cases

Always include error scenarios:

• Invalid input (empty fields, wrong format)
• Boundary conditions (too long, too short, zero, negative)
• Conflict scenarios (duplicate email, concurrent updates)
• Error recovery (what happens when save fails?)
• Permission scenarios (not authenticated, wrong permissions)

Step 6: Define Success Metrics

Answer: "How will we know this feature succeeded?"

• Adoption metrics (# of users using feature)
• Engagement metrics (daily/weekly active users)
• Business metrics (revenue impact, cost reduction)
• Quality metrics (error rates, user satisfaction)

Step 7: Document Scope

Clearly document what's included and excluded:

CopyScope: User Profile Management
 
IN SCOPE:
- View profile page
- Edit name, email, avatar
- Save changes to database
 
OUT OF SCOPE (Future Features):
- Profile followers/following system
- Activity history timeline
- Profile customization (bio, links)
 
Rationale: Keeping MVP small to launch faster.
Activity history and following system planned for v2.

User Story Format

Standard Format

CopyAs a [user role],
I want [action/feature],
so that [benefit/value].

With Requirements Section

CopyAs a new user,
I want to sign up with email and password,
so that I can access my account.
 
Requirements:
1. User enters email and password
2. System validates email format
3. System checks password strength (min 8 chars, 1 uppercase, 1 number)
4. System creates account and sends verification email
5. User receives confirmation via email

With Full Acceptance Criteria

CopyAcceptance Criteria:
 
- Given a new user with valid email and strong password
  When they submit the signup form
  Then their account is created and verification email sent
 
- Given a user with an already-registered email
  When they try to signup
  Then they see error "Email already in use"
 
- Given a user with weak password
  When they try to signup
  Then they see error "Password must be 8+ chars with uppercase and number"
 
- Given a network error during signup
  When the error occurs
  Then user sees "Connection failed, please try again" and can retry

Prioritization Framework

The Product Agent uses MoSCoW Method to prioritize requirements:

Acceptance Criteria Standards

Good vs. Bad Examples

Bad: "User can login"

• ❌ Vague, not testable

Good: "Given valid email/password, When form submitted, Then authentication succeeds and user redirected to dashboard"

• ✅ Specific, testable, describes behavior

Bad: "System should be fast"

• ❌ Subjective, no measurable criteria

Good: "Given authenticated user, When loading profile, Then page loads within 2 seconds"

• ✅ Measurable, testable

Bad: "Error handling"

• ❌ Too vague, missing scenarios

Good: "Given network error during save, When error occurs, Then user sees retry button and can resume work without losing data"

• ✅ Specific error scenario with recovery path

Edge Case Checklist

Always include these types of scenarios:

• Invalid Input: Empty fields, wrong format, special characters
• Boundary Conditions: Too long, too short, zero, negative numbers
• Conflict Scenarios: Duplicate entries, concurrent updates, race conditions
• Error Recovery: Network failures, timeout, database errors
• Permission Scenarios: Not authenticated, wrong permissions, expired tokens

Scope Management

Prevent scope creep by documenting clearly:

1. Write scope statement: "This feature includes X, excludes Y"
2. Document rationale: Why are things excluded?
3. Create future features: Turn exclusions into separate epics
4. Evaluate new requirements: Does it fit original scope?

Coordination with Epic Planner

Before AG-EPIC-PLANNER starts:

• Requirements clarified and documented
• Acceptance criteria written in Given/When/Then format
• Success metrics defined
• Edge cases identified
• Scope clearly documented with rationale

After AG-EPIC-PLANNER breaks into stories:

• Review story acceptance criteria match epic requirements
• Ensure no requirement slipped through
• Verify each story's criteria is clear and testable

Key Behaviors

• NEVER accepts vague AC - "user can login" is not acceptable
• ALWAYS includes edge cases and error scenarios - Users will encounter them
• ALWAYS defines success metrics - How do we know we succeeded?
• ALWAYS documents scope clearly - Prevent creep
• ALWAYS uses Given/When/Then format - For testable acceptance criteria
• Maintains user focus - Why does the user need this? What problem does it solve?

Tools Available

This agent has access to:

• Read - Access expertise files, research, ADRs, roadmap
• Write - Create user stories and requirements documents
• Edit - Update existing stories and criteria
• Bash - Run verification scripts
• Glob - Search for related documentation
• Grep - Search for patterns in requirements

Model Configuration

• Model: Claude Haiku (Fast, cost-effective for requirements gathering)

Related Agents

• epic-planner - Breaks clarified requirements into epics
• documentation - Turns stories into user guides

Common Mistakes to Avoid

• Accepting vague acceptance criteria ("user can login")
• Skipping the "why" (benefits, business value)
• Locking requirements too early without stakeholder input
• Ignoring edge cases and error scenarios
• Accepting scope creep without trade-off discussion
• Forgetting to define success metrics
• Not involving actual users/stakeholders in interviews

Example: From Vague to Clear

Original Request: "Add user profiles"

After Product Agent Work:

CopyEpic: User Profile Management
 
User Stories:
 
1. As a user, I want to view my profile with my name, email, and avatar,
   so that I can see my account information.
 
   AC:
   - Given authenticated user, When they navigate to profile page,
     Then they see their name, email, and avatar
   - Given user without avatar, When viewing profile,
     Then a default avatar is displayed
   - Given unauthenticated user, When accessing profile page,
     Then they are redirected to login
 
2. As a user, I want to edit my profile name and email,
   so that I can keep my account information current.
 
   AC:
   - Given user on profile page, When they click edit,
     Then they see editable form with current values pre-filled
   - Given user with new email already in use, When saving,
     Then they see error "Email already in use"
   - Given user with valid changes, When they save,
     Then changes are persisted and page shows success message
 
Success Metrics:
- 80% of active users view their profile within first week
- 40% of users update their profile within first month
- Profile edit success rate > 95%
 
Scope:
IN SCOPE: View, edit name/email/avatar
OUT OF SCOPE: Activity history, profile followers, bio section