Business Requirements Interview
- 92 installs
- 1 repo stars
- Updated June 17, 2026
- validkeys/sherpy
Helps with ai & agent building tasks.
About
business-requirements-interview is a Claude Code skill in the AI & Agent Building category.
- business-requirements-interview
- AI & Agent Building
- AI-coding skill
Business Requirements Interview by the numbers
- 92 all-time installs (skills.sh)
- +2 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #4,749 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/validkeys/sherpy --skill business-requirements-interviewAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 92 |
|---|---|
| repo stars | ★ 1 |
| Last updated | June 17, 2026 |
| Repository | validkeys/sherpy ↗ |
What it does
Helps with ai & agent building tasks.
Files
Business Requirements Interview
Analyzes your project idea, identifies gaps, asks context-specific questions.
Process
1. Understand the Idea
Ask user for project description:
"Describe your project: the problem, who it's for, what you want to achieve."
Analyze their response:
- Domain (CLI, web app, API, etc.)
- What's clear vs unclear
- Missing pieces (users, scope, constraints)
- Questions to ask
2. Ask Context-Aware Questions
Generate questions specific to their project, not generic forms.
Example - CLI Validator:
User: "Build YAML validator for CI/CD"
Questions: 1. "What schema format? JSON Schema, custom DSL, code-based?" 2. "Who uses it? CI/CD only, or local dev too?" 3. "Error output format? JSON, prose, both?" 4. "Performance needs? Thousands of files or dozens?"
Example - Web Dashboard:
User: "Analytics dashboard for metrics"
Questions: 1. "Who views it? Execs, PMs, analysts, mixed?" 2. "What metrics? Revenue, usage, engagement?" 3. "Real-time or batch? How fresh?" 4. "Data sources? DB, APIs, warehouse?"
3. Adapt Based on Answers
Each answer shapes next question:
- CI/CD → exit codes, automation
- Local dev → UX, error messages
- Multiple users → access control
Question Types
Clarification: "By 'validate', do you mean schema, business rules, or both?"
Scope: "Which are in v1: [specific list], or is that v2?"
Priority: "Speed, detailed errors, or extensibility - which is critical?"
Constraints: "Any limits on tech, timeline, team that shape this?"
Success: "How will you know it's working? What metrics matter?"
Structure Template
BEFORE generating, review: references/structure-template.yaml
This shows the exact YAML structure required. Use it as your template.
Critical structural rules:
overview.scope→ OBJECT within_scopeandout_of_scopearrays (NOT a string with|)timeline→ OBJECT withphase,duration,milestones(NOT a string)functional_requirements[].id→ Sequential: FR-1, FR-2, FR-3 (no gaps, no FR-001)use_cases[].actor→ Must match apersonas[].nameexactly or be "System"
Required Coverage
Gather detail for:
- Problem: What, who, why it matters
- Value: Measurable impact
- Scope: In/out v1
- Users: Who, goals, pain points
- Use Cases: Top 3-5 scenarios
- Requirements: 5-10 specific, testable
- Success: Quantifiable targets
- Constraints: Tech, business, timeline
- Risks: What could go wrong
Avoid
❌ Generic: "What problem are you solving?" ✅ Specific: "Should errors be JSON (machine), prose (human), or both?"
❌ Broad: "1. Developers 2. Teams 3. Enterprise" ✅ Contextual: "1. Devs validating configs 2. Platform enforcing standards 3. Both"
Progress Tracking
Save to {base_directory}/artifacts/business-interview.jsonl:
{"category":"analysis","question":"initial_idea","answer":"CLI YAML validator","timestamp":"2024-05-14T10:30:00Z"}
{"category":"schema","question":"Schema format?","answer":"JSON Schema","rationale":"Industry standard","timestamp":"2024-05-14T10:32:15Z"}Output
Generate {base_directory}/requirements/business-requirements.yaml when complete.
CRITICAL: Follow the exact YAML structure in [references/structure-template.yaml](references/structure-template.yaml).
For detailed schema documentation, see [references/output-spec.md](references/output-spec.md).
The output MUST include:
project,version,generated(root fields)overview(problem, value_proposition, scope)personas(name, description, goals, pain_points)use_cases(name, actor, description, outcome)functional_requirements(id: FR-1, FR-2..., category, description, priority, rationale)non_functional_requirementssuccess_criteriaconstraintsdependenciestimelineassumptionsrisks
ID Format: FR-1, FR-2, FR-3 (sequential, no gaps)
See [references/example.yaml](references/example.yaml) for a complete example.
Confirm before generating:
"Ready to draft requirements doc with:
- Problem and value prop
- 3 personas with use cases
- 8 functional requirements
- Success criteria and constraints
>
Proceed?"
Validation
sherpy validate -t business-requirements -f {base_directory}/requirements/business-requirements.yaml --strictFix errors immediately.
Gap Analysis
Check for:
- ✅ Specific, testable requirements
- ✅ Clear personas with distinct goals
- ✅ Measurable success criteria
- ✅ Explicit scope boundaries
- ✅ Identified risks with mitigation
If gaps: "Noticed [gap]. Address now or proceed?"
Next Steps
1. Validate with sherpy validate 2. Review gaps 3. /technical-requirements-interview 4. /implementation-planner
Key Difference
Old: Canned questions, generic options, same for all projects New: Analyze first, context-aware questions, adaptive, intelligent conversation
project: TaskFlow Pro
version: "1.0.0"
generated: "2026-04-15T14:30:00Z"
overview:
problem: |
Small to medium-sized development teams (5-25 people) struggle with fragmented
project management workflows. Teams currently juggle multiple tools: Jira for
tickets, Slack for updates, Google Sheets for capacity planning, and email for
stakeholder reporting. This fragmentation leads to:
- 2-3 hours per week per developer lost to status updates and context switching
- Critical blockers discovered 24-48 hours late due to poor visibility
- Product managers spending 30% of their time manually aggregating data for reports
- Misaligned priorities between engineering and business stakeholders
value_proposition: |
TaskFlow Pro consolidates task tracking, team communication, capacity planning,
and automated reporting into a single, AI-assisted workspace. By eliminating
tool fragmentation and providing real-time insights, teams reduce coordination
overhead by 40% and improve delivery predictability by identifying risks 3-5 days
earlier than current workflows allow.
scope:
in_scope:
- Task and project tracking with customizable workflows
- Real-time team capacity dashboard with workload balancing
- Automated daily standup summaries and weekly stakeholder reports
- AI-powered blocker detection and priority recommendations
- Slack and GitHub integration for status updates
- Mobile app for iOS and Android
- Team collaboration features (comments, mentions, file attachments)
- Basic time tracking and velocity metrics
out_of_scope:
- Advanced resource management (cross-project portfolio planning)
- Financial budgeting and cost tracking
- Client billing and invoicing
- Custom field builder (v1 uses predefined fields only)
- White-label or multi-tenant enterprise features
- Video conferencing integration
- Advanced analytics and custom reporting (beyond preset reports)
personas:
- name: Sarah (Product Manager)
description: |
Mid-level product manager at a 50-person SaaS startup, managing 2 engineering
teams (15 developers total). Reports to VP of Product and stakeholders in
leadership. Tech-savvy but not technical. Juggles feature prioritization,
stakeholder communication, and roadmap planning.
goals:
- Track engineering progress across multiple sprints without constant check-ins
- Generate executive-ready status reports in under 10 minutes
- Identify blockers and bottlenecks before they delay releases
- Make data-driven prioritization decisions based on team capacity
- Maintain alignment between engineering work and business goals
pain_points:
- Spends 6+ hours weekly in status meetings and creating manual reports
- Discovers critical blockers too late to adjust sprint plans
- Struggles to explain technical work to non-technical stakeholders
- Cannot accurately predict delivery dates due to poor visibility into capacity
- Constantly interrupted by "what's the status of X?" questions
- name: Marcus (Engineering Lead)
description: |
Senior engineering lead managing a team of 8 developers (3 senior, 5 mid-level).
10 years experience, responsible for technical delivery, code quality, and team
velocity. Balances hands-on coding (30%) with leadership responsibilities.
goals:
- Protect team from constant context switching and interruptions
- Maintain clear visibility into who's working on what and their workload
- Surface blockers early so they can be resolved quickly
- Track technical debt and quality metrics alongside feature work
- Enable autonomous decision-making by empowering senior engineers
pain_points:
- Team members overcommit and burn out due to invisible workload
- Junior developers get stuck for hours before asking for help
- Priorities shift without clear communication, causing thrash
- Difficult to balance feature velocity with code quality and tech debt
- Stakeholders bypass process and add "quick wins" that destabilize sprints
- name: Jordan (Software Developer)
description: |
Mid-level full-stack developer with 4 years experience. Works on feature
development, bug fixes, and code reviews. Prefers focused work time with
minimal meetings. Active in Slack and GitHub but avoids heavy PM tools.
goals:
- Understand priorities clearly without attending multiple meetings
- Get unblocked quickly when waiting on teammates or external dependencies
- See the impact of their work on overall product goals
- Minimize time spent on status updates and administrative overhead
- Collaborate effectively with designers and product managers
pain_points:
- Unclear priorities lead to starting wrong tasks or switching frequently
- Blocked on other work but unsure who to ask or when it will be ready
- Status meetings feel like wasted time repeating what's in tickets
- PM tools feel heavyweight and slow down workflow vs coding
- Hard to say no to new requests when current workload isn't visible
- name: Alex (Executive Stakeholder)
description: |
VP of Engineering or CTO at the company. Oversees 3-5 engineering teams,
reports to CEO and board. Focuses on strategic planning, hiring, and ensuring
engineering delivers business outcomes. Limited time for operational details.
goals:
- Understand cross-team progress and risks at a glance
- Make informed decisions about resource allocation and priorities
- Communicate engineering progress to CEO and board with confidence
- Identify systemic issues (team health, process bottlenecks) early
- Ensure engineering work aligns with quarterly company OKRs
pain_points:
- Requires manual report compilation from multiple teams to get full picture
- Learns about delays or issues too late to course-correct
- Difficult to compare team performance and identify patterns
- Cannot easily answer "when will X ship?" without deep investigation
- Lacks visibility into technical debt accumulation and quality trends
use_cases:
- name: Daily Standup Summary
actor: Sarah (Product Manager)
description: |
Each morning at 9 AM, Sarah opens TaskFlow Pro and sees an AI-generated
standup summary showing what each team member accomplished yesterday, their
plan for today, and any blockers flagged. She reviews the summary in 3 minutes
and posts it to the team Slack channel, replacing the need for a synchronous
standup meeting.
outcome: |
Team stays aligned without meeting overhead. Sarah identifies blockers early
and can intervene before they cause delays. Developers appreciate async updates
and uninterrupted focus time.
- name: Capacity-Based Sprint Planning
actor: Marcus (Engineering Lead)
description: |
During sprint planning, Marcus opens the capacity dashboard showing each
developer's committed hours, PTO, and existing carryover work. He drags tasks
from the backlog into the sprint, and the system warns when individual or
team capacity is exceeded. He adjusts scope based on real-time workload data.
outcome: |
Sprint commitments are realistic and achievable. Team avoids overcommitment
and burnout. Velocity becomes predictable, improving trust with stakeholders.
- name: Blocker Detection and Resolution
actor: Jordan (Software Developer)
description: |
Jordan marks a task as blocked because it depends on an API endpoint another
team is building. TaskFlow Pro automatically notifies the blocking team's lead
and adds the dependency to the blockers dashboard. Marcus sees it during his
morning review and escalates to unblock Jordan within 4 hours.
outcome: |
Jordan loses only 4 hours instead of 2 days to being blocked. Explicit
dependency tracking prevents silent bottlenecks and finger-pointing.
- name: Weekly Stakeholder Report
actor: Sarah (Product Manager)
description: |
Every Friday afternoon, Sarah clicks "Generate Report" and TaskFlow Pro creates
an executive summary showing completed features, in-progress work, upcoming
milestones, risks, and velocity trends. She reviews and edits for 5 minutes,
then sends to stakeholders.
outcome: |
Sarah reduces report creation time from 90 minutes to 10 minutes. Stakeholders
receive consistent, data-driven updates. Sarah focuses energy on strategic
decisions instead of manual aggregation.
- name: Cross-Team Dependency Tracking
actor: Alex (Executive Stakeholder)
description: |
Alex opens the cross-team dashboard showing all active projects, their
dependencies, and health status (green/yellow/red). A critical mobile app
release is flagged yellow due to backend API delay. Alex clicks through to
see the dependency chain and allocates additional resources to unblock.
outcome: |
Alex identifies risks 1 week before they would have delayed release. Proactive
intervention prevents escalation and maintains customer trust.
functional_requirements:
- id: FR-1
category: Task Management
description: |
Users can create, edit, and delete tasks with title, description, assignee,
status, priority, estimated hours, and due date. Tasks support custom workflow
states (To Do, In Progress, In Review, Blocked, Done).
priority: high
rationale: |
Core functionality required for any task tracking system. Custom workflow states
allow teams to model their actual processes instead of rigid predefined states.
- id: FR-2
category: Task Management
description: |
Users can create parent-child task relationships (epics, stories, subtasks)
with up to 3 levels of nesting. Child tasks automatically roll up progress
to parent tasks.
priority: high
rationale: |
Teams need hierarchical organization to break down large features into
manageable work. Automatic progress rollup provides accurate big-picture status.
- id: FR-3
category: Task Management
description: |
Users can link tasks with dependency relationships (blocks, blocked by). System
displays dependency graph and automatically notifies assignees when dependencies
are resolved.
priority: high
rationale: |
Explicit dependency tracking prevents silent blockers that delay projects.
Automatic notifications reduce manual coordination overhead.
- id: FR-4
category: Capacity Planning
description: |
System displays team capacity dashboard showing each member's committed hours,
available hours (accounting for PTO), and utilization percentage. Updates
in real-time as tasks are assigned or completed.
priority: high
rationale: |
Prevents overcommitment and burnout by making workload visible. Essential for
realistic sprint planning and sustainable team velocity.
- id: FR-5
category: Capacity Planning
description: |
System warns when assigning tasks would exceed individual capacity (>40 hours/week)
or team capacity for the current sprint. Warnings are visual but not blocking.
priority: medium
rationale: |
Provides guardrails against overcommitment while allowing flexibility for
urgent work. Reduces risk of missed commitments and team burnout.
- id: FR-6
category: AI Features
description: |
System automatically detects potential blockers by analyzing task dependencies,
age of tasks in "Blocked" status, and comment sentiment. Surfaces detected
blockers in daily summary and dedicated blockers dashboard.
priority: high
rationale: |
Proactive blocker detection is key differentiator from existing tools. Reduces
mean time to resolution by 50% based on user research insights.
- id: FR-7
category: AI Features
description: |
System generates daily standup summaries showing completed work, planned work,
and blockers for each team member. Summary uses natural language and highlights
items requiring attention.
priority: high
rationale: |
Replaces synchronous standup meetings with async summaries, saving 30-60
minutes daily. Maintains alignment without interrupting focus time.
- id: FR-8
category: Reporting
description: |
Users can generate weekly stakeholder reports with one click. Reports include
completed features, in-progress work, upcoming milestones, velocity trends,
and identified risks. Output format is Markdown and PDF.
priority: high
rationale: |
Reduces report creation time from 90 minutes to 10 minutes per Sarah's pain
point. Critical for executive communication and stakeholder management.
- id: FR-9
category: Reporting
description: |
System tracks velocity metrics (story points or hours completed per sprint)
and displays trends over time. Shows velocity by team member and team aggregate.
priority: medium
rationale: |
Enables data-driven planning and identifies productivity trends early. Supports
continuous improvement and realistic forecasting.
- id: FR-10
category: Collaboration
description: |
Users can comment on tasks, mention other users (@mentions), attach files
(up to 10MB), and react with emoji. Comments support Markdown formatting.
priority: medium
rationale: |
Essential for async collaboration and reducing Slack noise. Keeps discussion
context attached to relevant tasks.
- id: FR-11
category: Collaboration
description: |
Users receive in-app and email notifications for mentions, task assignments,
dependency resolutions, and blocker alerts. Notification preferences are
customizable per user.
priority: high
rationale: |
Ensures critical updates reach team members without requiring constant app
monitoring. Customization prevents notification fatigue.
- id: FR-12
category: Integration
description: |
System integrates with Slack to post daily summaries, blocker alerts, and
allow task status updates via slash commands (/taskflow status <task-id>).
priority: high
rationale: |
Teams live in Slack. Bringing TaskFlow updates into Slack reduces tool-switching
and increases adoption by meeting users where they are.
- id: FR-13
category: Integration
description: |
System integrates with GitHub to automatically link pull requests to tasks,
update task status when PRs are merged, and display PR status in task view.
priority: medium
rationale: |
Automates status updates and reduces manual busywork for developers. Provides
single source of truth for feature delivery status.
- id: FR-14
category: Authentication & Authorization
description: |
System supports email/password authentication and OAuth2 via Google Workspace
and Microsoft 365. Implements role-based access control with roles: Admin,
Team Lead, Developer, Viewer.
priority: high
rationale: |
OAuth reduces friction for enterprise users requiring SSO. RBAC ensures
sensitive operations (deleting projects, managing teams) are properly secured.
- id: FR-15
category: Mobile Access
description: |
Native mobile apps for iOS and Android support core workflows: viewing tasks,
updating status, commenting, and receiving notifications. Does not support
admin features or complex sprint planning.
priority: medium
rationale: |
Enables on-the-go updates and quick status checks. Supports remote teams and
async workflows without requiring laptop access.
non_functional_requirements:
performance:
- Task list views must load within 500ms for up to 1000 tasks
- AI blocker detection must process daily within 60 seconds per team
- Report generation must complete within 10 seconds for 4-week data range
- Mobile app must function offline with sync on reconnect
- API response time must be < 200ms at p95 under 1000 concurrent users
security:
- All data encrypted in transit (TLS 1.3) and at rest (AES-256)
- OWASP Top 10 compliance verified via annual penetration testing
- Session tokens expire after 24 hours of inactivity
- Support for SOC 2 Type II compliance requirements
- Password policies enforce minimum 12 characters with complexity requirements
- Multi-factor authentication (MFA) available for all users
usability:
- WCAG 2.1 Level AA accessibility compliance
- Onboarding flow allows new users to create first task within 3 minutes
- Critical workflows (create task, update status) require ≤3 clicks
- Mobile app supports standard gestures (swipe to archive, pull to refresh)
- "Keyboard shortcuts available for power users (create task: 'c', search: '/')"
reliability:
- 99.5% uptime SLA (excluding planned maintenance)
- Maximum 4 hours monthly planned maintenance window
- Data backup every 6 hours with 30-day retention
- Mean time to recovery (MTTR) < 1 hour for critical failures
- Graceful degradation when AI features unavailable (show last known data)
maintainability:
- Code follows established architectural patterns (service-command architecture)
- All public APIs have comprehensive JSDoc/TSDoc documentation
- Unit test coverage >80% for critical business logic
- Integration tests for all major workflows
- Clear separation of concerns (presentation, business logic, data access)
- Consistent naming conventions and code style enforced by linters
observability:
- Structured logging for all critical operations (task CRUD, capacity updates, AI calls)
- Metrics tracked - API latency (p50/p95/p99), error rates, queue depth, AI call duration
- Distributed tracing for cross-service requests
- Health check endpoints for all services (/health, /ready)
- Alerts configured for SLA violations, error spikes, and queue backlog
success_criteria:
- criterion: User adoption and engagement
metric: Weekly active users (WAU) as percentage of total team
target: 85%+ WAU within 60 days of team onboarding
- criterion: Time savings for status reporting
metric: Self-reported time spent on status updates and reports per week
target: "50% reduction from baseline (Sarah: 6 hours → 3 hours)"
- criterion: Blocker detection speed
metric: Average time between blocker occurring and being flagged
target: < 4 hours (vs 24-48 hours baseline)
- criterion: Sprint predictability
metric: Percentage of sprint commitments delivered on time
target: 80%+ completion rate (vs 60% baseline)
- criterion: User satisfaction
metric: Net Promoter Score (NPS)
target: NPS > 40 within 6 months
- criterion: Tool consolidation impact
metric: Number of tools replaced per team
target: Average 2.5 tools replaced (typically Jira + Google Sheets + email)
- criterion: Revenue target
metric: Annual recurring revenue (ARR)
target: $1M ARR by end of year 1 ($83/team/month, 1000 teams)
constraints:
technical:
- Must support modern browsers (Chrome, Firefox, Safari, Edge - last 2 versions)
- Backend must be built on cloud-native architecture (AWS or GCP)
- Must integrate with Slack API v2 and GitHub REST API v3
- Database must support ACID transactions for critical operations
- Must support up to 100 teams (2500 users) in MVP deployment
- "API rate limits: 1000 requests per user per hour"
business:
- MVP must be shippable within 16 weeks from project kickoff
- Development team is 4 engineers (2 frontend, 2 backend) + 1 designer
- Total MVP budget is $400K (loaded cost, including infrastructure)
- Cannot require on-premise deployment for MVP (cloud-only)
- Must comply with GDPR for European customers
timeline:
- Beta launch to 10 pilot customers by Week 14
- Public launch by Week 16
- Must hit $100K ARR within 6 months to secure Series A funding
budget:
- Infrastructure costs must remain under $5K/month at 1000-team scale
- Third-party API costs (OpenAI, Slack, etc.) budgeted at $2K/month
- No budget for custom machine learning model training (use OpenAI API)
operational:
- Must deploy to AWS us-east-1 region for production
- Must support zero-downtime deployments with rolling updates
- Database migrations must be backward-compatible for 1 release cycle
- Must integrate with existing CI/CD pipeline (GitHub Actions)
- Production deployments require approval from technical lead
- Must maintain separate staging environment for pre-production testing
dependencies:
internal:
- Design system and component library from UX team (due Week 2)
- OAuth integration testing environment from IT team (due Week 4)
- Legal review of data privacy policy (due Week 10)
- Customer success team trained on product for beta support (due Week 12)
external:
- OpenAI API access for GPT-4 (for AI blocker detection and summaries)
- Slack App Directory approval process (6-8 weeks lead time)
- GitHub OAuth app approval (2-3 weeks lead time)
- AWS infrastructure provisioned and configured
- Stripe payment processing integration for billing
timeline:
phase: MVP / Beta Launch
duration: 16 weeks
milestones:
- "Week 4: Core task management and authentication complete"
- "Week 8: Capacity planning and dependency tracking functional"
- "Week 11: AI features (blocker detection, summaries) in private beta"
- "Week 13: Slack and GitHub integrations tested and deployed"
- "Week 14: Beta launch to 10 pilot teams"
- "Week 16: Public launch with full feature set"
assumptions:
- Target customers (50-200 person companies) are willing to pay $50-100/month per team
- Teams currently spend 10-15 hours per week on coordination overhead
- OpenAI API pricing and availability will remain stable through MVP development
- Slack and GitHub integrations will be approved without major changes
- Pilot customers will provide weekly feedback during beta period
- Existing tools (Jira, Asana) have high enough friction that switching costs are acceptable
- Product manager and engineering lead personas are common across target market
- Teams prefer async communication and are comfortable with AI-assisted workflows
- Mobile app can launch 4-6 weeks after web app without blocking adoption
- 80% of value can be delivered with web app; mobile is enhancement not requirement
risks:
- risk: AI blocker detection accuracy is insufficient, creating false positives/negatives
probability: medium
impact: high
mitigation: |
Implement confidence scoring and allow users to provide feedback on AI
suggestions. Start with rule-based detection (task age, dependency chains)
and layer in ML progressively. Set clear expectations that AI is assistive,
not authoritative. Include manual blocker flagging as backup workflow.
- risk: Slack/GitHub integration approvals delayed beyond 6-8 week estimates
probability: medium
impact: medium
mitigation: |
Submit integration applications in Week 1 to maximize buffer. Develop integrations
against beta APIs in parallel. Prepare fallback using webhooks and manual setup
if directory approval is delayed. Communicate integration status clearly to beta
customers.
- risk: Team capacity planning requires too much manual data entry, reducing adoption
probability: medium
impact: high
mitigation: |
Integrate with calendar APIs (Google Calendar, Outlook) to auto-import PTO.
Start with simple hours-based estimation before introducing story points.
Provide bulk import from existing tools. Track setup time during beta and
optimize onboarding flow.
- risk: OpenAI API costs exceed $2K/month budget at scale
probability: low
impact: medium
mitigation: |
Monitor token usage closely during beta. Implement aggressive caching for
summaries (regenerate daily, not per view). Explore OpenAI batching API for
non-real-time features. Consider fallback to rule-based system if costs prohibitive.
- risk: Pilot customers churn during beta due to missing critical features
probability: medium
impact: high
mitigation: |
Conduct detailed customer interviews before beta to identify must-have features.
Provide white-glove support during beta including weekly check-ins. Set clear
expectations that beta is limited feature set. Offer extended trial period to
maintain engagement through feedback cycles.
- risk: Team of 4 engineers cannot deliver all MVP features in 16 weeks
probability: high
impact: high
mitigation: |
Ruthlessly prioritize features using MoSCoW method (Must/Should/Could/Won't).
Identify scope reduction options at each milestone. Consider extending timeline
to 20 weeks if funding allows. Leverage open-source libraries for non-differentiating
features (auth, UI components). Track velocity weekly and adjust scope proactively.
future_enhancements:
- Webhooks API for real-time task updates to external systems
- Custom field builder allowing teams to define their own task attributes
- Advanced analytics dashboard with burndown charts and velocity forecasting
- Time tracking with detailed per-task time logs and reporting
- Portfolio view for cross-team project management
- Advanced permissions model with project-level and task-level access control
- White-label customization for enterprise customers
- Gantt chart view for timeline-based project planning
- Resource management across multiple projects
- Budget tracking and financial reporting per project
- Integration marketplace for third-party tool connections
- AI-powered work breakdown structure generation from high-level descriptions
documentation_references:
architecture_diagram: docs/architecture/system-overview.md
architecture_diagram_description: |
High-level system architecture showing API layer, worker services, Kafka queue,
database schema, and integration points with Slack/GitHub
api_schema: docs/api/openapi-spec.yaml
api_schema_description: |
OpenAPI 3.0 specification for REST API endpoints including authentication,
task management, capacity planning, and reporting endpoints
data_model: docs/database/schema.sql
data_model_description: |
PostgreSQL schema definitions for tasks, users, teams, comments, attachments,
and capacity tracking tables with indexes and constraints
notes: |
This project follows a phased rollout strategy:
**Phase 1 (MVP - 16 weeks):**
- Core task management and capacity planning
- Single template AI features (blocker detection, summaries)
- Basic Slack/GitHub integrations
- Web application only
**Phase 2 (Post-MVP - 8 weeks):**
- Mobile applications (iOS/Android)
- Advanced AI features (priority recommendations, work estimation)
- Enhanced integrations (bi-directional sync, deeper GitHub integration)
**Phase 3 (6 months post-launch):**
- Portfolio management and cross-team views
- Advanced analytics and custom reporting
- Enterprise features (SSO, advanced permissions, white-label)
**Architectural Patterns:**
- API follows RESTful conventions with consistent error handling
- Worker services use event-driven architecture via Kafka
- Database uses row-level security for multi-tenancy
- AI features designed for graceful degradation when OpenAI unavailable
- Mobile apps use optimistic UI updates with background sync
**Key Technical Decisions:**
- React for frontend (team expertise, rich ecosystem)
- Node.js for backend (isomorphic JavaScript, Lambda compatibility)
- PostgreSQL for data (ACID compliance, rich query capabilities)
- Kafka for async processing (reliability, scalability, existing infra)
- OpenAI API for AI features (rapid iteration, no ML expertise needed)
**Success Metrics Tracking:**
- Weekly active users tracked via Mixpanel
- Time savings measured via user surveys at onboarding, 30 days, 90 days
- Blocker detection accuracy tracked via user feedback (helpful/not helpful)
- Sprint completion tracked automatically from task status changes
- NPS surveys sent quarterly to active users
Business Interview JSONL Specification
Document Overview
Purpose
The Business Interview JSONL file tracks question-answer pairs during the interactive /business-requirements-interview skill. Each line represents one completed interview exchange, enabling resume capability and preserving the interview transcript.
Role in Workflow
- Phase: Requirements (Step 2 of Sherpy Flow)
- Generated By:
/business-requirements-interviewskill (incremental, line-by-line) - Input Dependencies: None (created fresh or resumed from existing file)
- Output Consumers:
/business-requirements-interview(resume logic), business-requirements.yaml (generated from completed interview)
When to Use
- Automatically created when business interview begins
- Appended to after each question is answered
- Read on resume to determine last completed question
- Archived as interview transcript after business-requirements.yaml generation
---
File Format & Location
File Details
- Filename:
business-interview.jsonl - Format: JSONL (JSON Lines - newline-delimited JSON objects)
- Location:
{base_directory}/artifacts/business-interview.jsonl - Character Encoding: UTF-8
- Line Endings: LF (
\n) - each JSON object on exactly one line
Directory Structure
{base_directory}/
└── artifacts/
└── business-interview.jsonlJSONL Format Rules
- One complete JSON object per line
- No trailing commas in objects
- No line breaks within JSON objects
- Each line ends with
\n - Empty lines are not allowed
- File may be empty (0 bytes) initially
---
JSONL Schema Definition
Line Format
Each line is a JSON object with these fields:
{
"id": integer, // Sequential question number (1-based)
"category": string, // Interview category name
"question": string, // Question text presented to user
"answer": string, // User's answer (may be multi-line)
"timestamp": string // ISO 8601 timestamp (with timezone)
}Complete Example
{"id":1,"category":"Problem Definition","question":"What is the primary problem your project aims to solve?","answer":"Automate manual workflow - Replace time-consuming manual processes with automated workflows","timestamp":"2025-01-27T10:00:00Z"}
{"id":2,"category":"User Personas","question":"Who are your primary target users?","answer":"Individual developers - Solo developers working on personal or small projects","timestamp":"2025-01-27T10:05:00Z"}
{"id":3,"category":"Scope Definition","question":"What is the initial scope for this project?","answer":"MVP/Proof of concept - Minimal viable product to validate core assumptions","timestamp":"2025-01-27T10:12:00Z"}---
Field Definitions
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| id | integer | Yes | >= 1, sequential | Sequential question number starting at 1 |
| category | string | Yes | Non-empty | Interview category (see Standard Categories) |
| question | string | Yes | Non-empty | Question text as presented to user |
| answer | string | Yes | Non-empty | User's complete answer |
| timestamp | string | Yes | ISO 8601 with timezone | When answer was recorded |
Standard Categories
These match the business-requirements-interview skill structure:
1. Problem Definition - Core problem, value proposition 2. Scope Definition - In-scope vs out-of-scope boundaries 3. User Personas - Primary users, secondary users, user goals 4. Use Cases - Key scenarios and workflows 5. Functional Requirements - Feature requirements by category 6. Non-Functional Requirements - Performance, security, usability, reliability 7. Success Criteria - Metrics and targets 8. Constraints - Technical, business, timeline, budget 9. Dependencies - Internal and external dependencies 10. Timeline - Project phases and milestones 11. Assumptions - Implicit assumptions to document 12. Risks - Potential issues and mitigation
Timestamp Format
- Must be ISO 8601 format:
YYYY-MM-DDTHH:MM:SSZorYYYY-MM-DDTHH:MM:SS±HH:MM - Examples:
2025-01-27T10:00:00Z(UTC)2025-01-27T10:00:00-05:00(EST)2025-01-27T15:30:45.123Z(UTC with milliseconds)
Answer Field Rules
- Multi-line answers must use JSON string escaping (
\nfor newlines) - Quotes within answers must be escaped (
\") - May contain markdown formatting if user provided it
- Typically includes option number prefix if user selected a numbered option
- Example:
"Option 2 - Improve existing solution. We currently use Trello but it lacks automation capabilities we need."
---
Validation Rules
File-Level Validation
- [ ] File is valid JSONL (one JSON object per line)
- [ ] No empty lines
- [ ] All lines end with
\n(including last line) - [ ] File uses UTF-8 encoding
- [ ] Each line parses as valid JSON object
Structural Validation
- [ ] Each object has all 5 required fields
- [ ] No extra fields present
- [ ] All field types match schema
- [ ] IDs are sequential integers starting at 1
- [ ] No duplicate IDs
Content Validation
- [ ] All strings are non-empty
- [ ] IDs start at 1 and increment by 1
- [ ] No gaps in ID sequence
- [ ] Timestamps are valid ISO 8601 format
- [ ] Timestamps are in chronological order (later IDs have later timestamps)
- [ ] Category names match standard list
- [ ] Questions are unique (no exact duplicates)
Resume Validation
When resuming an interview:
- [ ] Last line has valid JSON with all required fields
- [ ] Next question ID should be
max_id + 1 - [ ] File integrity check: all IDs from 1 to max_id exist
---
Generation Guidelines
Initial Creation
When starting a new interview: 1. Check if {base_directory}/artifacts/business-interview.jsonl exists 2. If not, create empty file (0 bytes) or create on first append 3. Ensure parent directory exists: mkdir -p {base_directory}/artifacts
Appending Q&A Pairs
After each user answer: 1. Create JSON object with all 5 required fields 2. Generate ISO 8601 timestamp at answer recording time 3. Serialize to single-line JSON (no pretty-printing) 4. Append line + \n to file 5. Do not add blank lines or comments
Example Append Sequence
// After user answers question 1
const qa1 = {
id: 1,
category: "Problem Definition",
question: "What is the primary problem your project aims to solve?",
answer: "Automate manual workflow - Replace time-consuming manual processes",
timestamp: new Date().toISOString()
};
fs.appendFileSync(path, JSON.stringify(qa1) + '\n');
// After user answers question 2
const qa2 = {
id: 2,
category: "User Personas",
question: "Who are your primary target users?",
answer: "Individual developers - Solo developers working on personal projects",
timestamp: new Date().toISOString()
};
fs.appendFileSync(path, JSON.stringify(qa2) + '\n');Resume Logic
When resuming an interrupted interview:
1. Read Existing File
const lines = fs.readFileSync(path, 'utf-8').trim().split('\n').filter(Boolean);
const completed = lines.map(line => JSON.parse(line));2. Determine Last Completed Question
const lastId = completed.length > 0 ? Math.max(...completed.map(q => q.id)) : 0;
const nextId = lastId + 1;3. Validate Sequence
// Ensure no gaps in IDs
for (let i = 1; i <= lastId; i++) {
if (!completed.find(q => q.id === i)) {
throw new Error(`Gap detected: Question ${i} is missing`);
}
}4. Display Resume Message
Found existing interview with 5 completed questions.
Resuming from question 6...5. Continue Interview
- Skip questions with IDs 1-5
- Start with question ID 6
- Continue appending as normal
Multi-Line Answer Handling
If user provides multi-line answer:
const userAnswer = `This is a detailed answer
that spans multiple lines
and includes various details.`;
const qa = {
id: 3,
category: "Problem Definition",
question: "Please describe the problem in detail",
answer: userAnswer, // JSON.stringify handles newlines automatically
timestamp: new Date().toISOString()
};
// JSON.stringify converts \n to \\n in the JSON string
fs.appendFileSync(path, JSON.stringify(qa) + '\n');Result in file:
{"id":3,"category":"Problem Definition","question":"Please describe the problem in detail","answer":"This is a detailed answer\nthat spans multiple lines\nand includes various details.","timestamp":"2025-01-27T10:15:00Z"}---
Usage Examples
Example 1: First Three Questions
{"id":1,"category":"Problem Definition","question":"What is the primary problem your project aims to solve?","answer":"Automate manual workflow - Replace time-consuming manual processes with automated workflows","timestamp":"2025-01-27T10:00:00Z"}
{"id":2,"category":"Problem Definition","question":"What is the core value proposition of your solution?","answer":"Save developers time by automating repetitive tasks. Current manual process takes 2 hours per day, we want to reduce this to 15 minutes.","timestamp":"2025-01-27T10:05:32Z"}
{"id":3,"category":"Scope Definition","question":"What is included in the initial scope?","answer":"MVP - Core task automation features: workflow definition in YAML, task execution with dependencies, built-in tasks for file/shell/git operations. No cloud features or web UI in v1.","timestamp":"2025-01-27T10:11:45Z"}Example 2: Answer with Special Characters
{"id":7,"category":"Functional Requirements","question":"What are the key functional requirements?","answer":"Option 4 - Custom answer: We need 3 core features:\n1. Workflow parser that reads YAML files\n2. Task executor with dependency resolution\n3. CLI interface with commands: run, init, validate\n\nEach workflow must support environment variables using ${VAR} syntax.","timestamp":"2025-01-27T10:25:18Z"}Example 3: Complete Interview Session
{"id":1,"category":"Problem Definition","question":"What is the primary problem your project aims to solve?","answer":"Automate manual workflow","timestamp":"2025-01-27T10:00:00Z"}
{"id":2,"category":"User Personas","question":"Who are your primary target users?","answer":"Individual developers","timestamp":"2025-01-27T10:05:00Z"}
{"id":3,"category":"Scope Definition","question":"What is the initial scope?","answer":"MVP with core automation features","timestamp":"2025-01-27T10:10:00Z"}
{"id":4,"category":"Success Criteria","question":"How will you measure success?","answer":"50% reduction in time spent on manual tasks","timestamp":"2025-01-27T10:15:00Z"}
{"id":5,"category":"Timeline","question":"What is your target timeline?","answer":"3 months to MVP, 6 months to stable release","timestamp":"2025-01-27T10:20:00Z"}---
Error Handling
Common Errors and Recovery
Corrupted File
Error: Last line is invalid JSON Recovery: 1. Read file up to last valid line 2. Truncate file to remove corrupted line 3. Resume from last valid ID 4. Log warning about data loss
Duplicate IDs
Error: Two lines have same ID Recovery: 1. Keep first occurrence 2. Renumber subsequent lines sequentially 3. Log warning about duplicates removed
Missing IDs
Error: Gap in sequence (e.g., 1, 2, 4, 5) Recovery: 1. If gap is at end: continue from max_id + 1 2. If gap is in middle: data corruption, cannot auto-fix 3. Prompt user to either restart interview or manually fix file
Empty Answer
Error: Answer field is empty string Recovery:
- Do not append line to file
- Re-ask the same question
- Explain that answers cannot be empty
---
Integration Points
With business-requirements-interview Skill
Start of Interview:
// Check for existing interview
const interviewPath = path.join(baseDir, 'artifacts', 'business-interview.jsonl');
if (fs.existsSync(interviewPath)) {
const completed = readCompletedQuestions(interviewPath);
console.log(`Found ${completed.length} completed questions. Resuming...`);
startFromQuestionId = completed.length + 1;
} else {
startFromQuestionId = 1;
}After Each Answer:
const qa = {
id: currentQuestionId,
category: currentCategory,
question: questionText,
answer: userAnswer,
timestamp: new Date().toISOString()
};
appendToJSONL(interviewPath, qa);Interview Completion:
// Generate business-requirements.yaml from JSONL
const allAnswers = readAllAnswers(interviewPath);
const requirements = transformToBusinessRequirements(allAnswers);
writeYAML(requirementsPath, requirements);
console.log(`Interview complete. Transcript saved to ${interviewPath}`);
console.log(`Generated ${requirementsPath}`);With business-requirements.yaml
The completed JSONL file is the source for generating business-requirements.yaml:
Transformation Logic: 1. Read all Q&A pairs from JSONL 2. Group by category 3. Transform answers into structured YAML sections 4. Apply business logic (e.g., parse "Option X" prefixes) 5. Generate complete business-requirements.yaml
---
Archival and Cleanup
Archival Strategy
After business-requirements.yaml is generated:
- Keep
business-interview.jsonlinartifacts/as interview transcript - Useful for audit trail and understanding requirement origins
- Can be referenced if requirements are questioned later
Retention:
- Permanent (part of project documentation)
- Include in version control for full history
- Compress if file size is concern (gzip reduces 70-80%)
Cleanup Guidelines
Do NOT delete if:
- Interview is incomplete
- Resume capability is needed
- Generated business-requirements.yaml hasn't been reviewed
Safe to archive/compress if:
- business-requirements.yaml is complete and reviewed
- Project is in later phases (implementation, deployment)
- Need to reduce repo size
---
Conversion Utilities
Convert to Markdown
# Future CLI utility
sherpy convert business-interview.jsonl --to markdownOutput Format:
# Business Requirements Interview Transcript
**Completed:** 2025-01-27
**Questions:** 12
---
## Problem Definition
### Question 1
**Q:** What is the primary problem your project aims to solve?
**A:** Automate manual workflow - Replace time-consuming manual processes
**Timestamp:** 2025-01-27T10:00:00Z
---
## User Personas
### Question 2
**Q:** Who are your primary target users?
**A:** Individual developers - Solo developers working on personal projects
**Timestamp:** 2025-01-27T10:05:00ZConvert to CSV
# For data analysis
sherpy convert business-interview.jsonl --to csvOutput:
id,category,question,answer,timestamp
1,"Problem Definition","What is the primary problem...","Automate manual workflow","2025-01-27T10:00:00Z"
2,"User Personas","Who are your primary target users?","Individual developers","2025-01-27T10:05:00Z"---
Testing and Validation Script
Validation Script
function validateJSONL(filePath) {
const lines = fs.readFileSync(filePath, 'utf-8').trim().split('\n');
const errors = [];
const ids = new Set();
lines.forEach((line, idx) => {
const lineNum = idx + 1;
// Parse check
let obj;
try {
obj = JSON.parse(line);
} catch (e) {
errors.push(`Line ${lineNum}: Invalid JSON`);
return;
}
// Required fields
const required = ['id', 'category', 'question', 'answer', 'timestamp'];
for (const field of required) {
if (!(field in obj)) {
errors.push(`Line ${lineNum}: Missing field '${field}'`);
}
}
// Type checks
if (typeof obj.id !== 'number' || obj.id < 1) {
errors.push(`Line ${lineNum}: 'id' must be positive integer`);
}
if (typeof obj.category !== 'string' || !obj.category) {
errors.push(`Line ${lineNum}: 'category' must be non-empty string`);
}
if (typeof obj.question !== 'string' || !obj.question) {
errors.push(`Line ${lineNum}: 'question' must be non-empty string`);
}
if (typeof obj.answer !== 'string' || !obj.answer) {
errors.push(`Line ${lineNum}: 'answer' must be non-empty string`);
}
// Timestamp validation
if (typeof obj.timestamp === 'string') {
const date = new Date(obj.timestamp);
if (isNaN(date.getTime())) {
errors.push(`Line ${lineNum}: Invalid ISO 8601 timestamp`);
}
} else {
errors.push(`Line ${lineNum}: 'timestamp' must be string`);
}
// Duplicate ID check
if (ids.has(obj.id)) {
errors.push(`Line ${lineNum}: Duplicate ID ${obj.id}`);
}
ids.add(obj.id);
});
// Sequential ID check
const sortedIds = Array.from(ids).sort((a, b) => a - b);
for (let i = 0; i < sortedIds.length; i++) {
if (sortedIds[i] !== i + 1) {
errors.push(`ID sequence gap: expected ${i + 1}, found ${sortedIds[i]}`);
break;
}
}
return errors;
}
// Usage
const errors = validateJSONL('artifacts/business-interview.jsonl');
if (errors.length === 0) {
console.log('✓ JSONL file is valid');
} else {
console.error('✗ Validation errors:');
errors.forEach(err => console.error(` - ${err}`));
process.exit(1);
}---
Related Documents
- Generated By:
/business-requirements-interviewskill - Output Consumer: business-requirements.yaml (via interview skill)
- Related Artifact: Same pattern used for technical-interview.jsonl
- Workflow Position: Step 2 of Sherpy Flow (after gap analysis, before technical requirements)
---
Version History
| Version | Date | Changes |
|---|---|---|
| 1.0 | 2026-04-16 | Initial specification - JSONL format tracking |
Business Requirements YAML Specification
Document Type: business-requirements.yaml Version: 1.0.0 Generated By: business-requirements-interview skill Purpose: Comprehensive business requirements document capturing problem definition, user personas, functional/non-functional requirements, success criteria, constraints, and timeline.
---
Document Structure
Root Level
project: string # Project name (required)
version: string # Semantic version (required, format: "X.Y.Z")
generated: string # ISO 8601 timestamp (required)Overview Section
overview:
problem: string # Multi-line problem statement (required)
value_proposition: string # Core value being delivered (required)
scope:
in_scope: array<string> # Items included in project scope (required, min: 1)
out_of_scope: array<string> # Items explicitly excluded (optional)Validation Rules:
problem: Must be at least 50 charactersvalue_proposition: Must be at least 30 charactersin_scope: At least 1 item required- Each scope item should be specific and measurable
Personas Section
personas:
- name: string # Persona name (required)
description: string # Who they are (required)
goals: array<string> # User goals (required, min: 1)
pain_points: array<string> # Current pain points (required, min: 1)Validation Rules:
- At least 1 persona required
name: 2-50 charactersdescription: 20-500 charactersgoals: 1-10 items, each 10-200 characterspain_points: 1-10 items, each 10-200 characters
Use Cases Section
use_cases:
- name: string # Use case name (required)
actor: string # Who performs it (required)
description: string # What they do (required)
outcome: string # What they achieve (required)Validation Rules:
- At least 1 use case required
name: 5-100 charactersactor: Must match a persona name or be "System"description: 20-500 charactersoutcome: 10-200 characters
Functional Requirements Section
functional_requirements:
- id: string # Requirement ID (required, format: FR-NNN)
category: string # Requirement category (required)
description: string # Requirement description (required)
priority: enum # Priority level (required)
rationale: string # Why this is needed (required)Enums:
priority:high|medium|low
Validation Rules:
id: Must match patternFR-\d{1,4}(e.g., FR-1, FR-42, FR-123)- IDs must be sequential starting from FR-1
category: 3-50 charactersdescription: Must be specific and testable, 20-500 charactersrationale: 10-300 characters- At least 3 functional requirements recommended
Common Categories:
- Authentication & Authorization
- Data Management
- User Interface
- Reporting & Analytics
- Integration
- Workflow & Automation
- Configuration & Settings
Non-Functional Requirements Section
non_functional_requirements:
performance: array<string> # Performance requirements (optional)
security: array<string> # Security requirements (optional)
usability: array<string> # Usability requirements (optional)
reliability: array<string> # Reliability requirements (optional)
maintainability: array<string> # Maintainability requirements (optional)
observability: array<string> # Observability requirements (optional)Validation Rules:
- At least one category should have 1+ items
- Each requirement must be measurable and testable
- Performance targets should include specific metrics (e.g., "< 200ms response time")
- Security requirements should reference standards (e.g., "OWASP Top 10 compliance")
Best Practices:
- Performance: Include load, response time, throughput targets
- Security: Cover authentication, authorization, data protection, compliance
- Usability: Define accessibility standards, user experience goals
- Reliability: Specify uptime, error rates, recovery targets
- Maintainability: Code quality, documentation, architectural patterns, testability
- Observability: Metrics, logging, tracing, monitoring, alerting requirements
Success Criteria Section
success_criteria:
- criterion: string # Success criterion (required)
metric: string # How to measure (required)
target: string # Target value (required)Validation Rules:
- At least 3 success criteria recommended
criterion: 10-200 characters, should be specific and measurablemetric: Must define clear measurement methodtarget: Must include specific numeric target or measurable outcome
Example Patterns:
- User adoption: "Active users per month" → "500+ MAU by Q2"
- Performance: "API response time" → "< 200ms p95"
- Quality: "User satisfaction score" → "4.5+ / 5.0"
Constraints Section
constraints:
technical: array<string> # Technical constraints (optional)
business: array<string> # Business constraints (optional)
timeline: array<string> # Timeline constraints (optional)
budget: array<string> # Budget constraints (optional)
operational: array<string> # Operational constraints (optional)Validation Rules:
- Each constraint must be specific and actionable
- Technical constraints should specify technologies, platforms, or limitations
- Timeline constraints should reference specific dates or durations
- Budget constraints should be explicit (even if "TBD")
- Operational constraints should specify runtime, deployment, or infrastructure requirements
Dependencies Section
dependencies:
internal: array<string> # Internal dependencies (optional)
external: array<string> # External dependencies (optional)Validation Rules:
- Each dependency should specify what is needed and why
- Internal: Other teams, systems, or projects within the organization
- External: Third-party services, APIs, or external systems
- Include version requirements where applicable
Timeline Section
timeline:
phase: string # Phase name (required)
duration: string # Duration (required)
milestones: array<string> # Key milestones (required, min: 1)Validation Rules:
phase: Common values: "MVP", "Beta", "v1.0", "Phase 1"duration: Format examples: "8 weeks", "3 months", "Q2 2026"milestones: At least 1 milestone required, each should be specific and measurable
Assumptions Section
assumptions: array<string> # Project assumptions (required, min: 1)Validation Rules:
- At least 3 assumptions recommended
- Each assumption should be explicit and testable
- Document what you're assuming to be true
- Include technical, business, and user assumptions
Common Assumption Categories:
- User behavior and capabilities
- Technology availability and stability
- Resource availability
- Market conditions
- Regulatory environment
Risks Section
risks:
- risk: string # Risk description (required)
probability: enum # Likelihood (required)
impact: enum # Impact severity (required)
mitigation: string # Mitigation strategy (required)Enums:
probability:high|medium|lowimpact:high|medium|low
Validation Rules:
- At least 3 risks recommended
risk: 20-300 characters, should be specificmitigation: Must include actionable steps, 20-500 characters- High-probability + high-impact risks require detailed mitigation
Risk Priority Matrix:
- Critical: High probability + High impact
- Important: High/Medium probability + Medium/High impact
- Monitor: Low probability or Low impact
Future Enhancements Section
future_enhancements: array<string> # Planned post-MVP features (optional)Validation Rules:
- Each enhancement should be a specific feature or capability
- Distinguish from out_of_scope: out_of_scope = "not doing", future_enhancements = "want but not in MVP"
- Use for roadmap planning and stakeholder communication
- Keep descriptions concise (one line per enhancement)
Best Practices:
- Prioritize or categorize enhancements if list is long
- Reference which milestone/version they might target
- Explain why deferred (e.g., "after MVP validation", "requires Phase 2 infrastructure")
Documentation References Section
documentation_references: # Links to related documents (optional)
[key]: string # Document path or identifier
[key]_description: string # What the document containsValidation Rules:
- Keys should be descriptive and snake_case
- Each reference should have a corresponding _description field
- Paths should be relative to project root or absolute URLs
- Use for linking to detailed specs, API schemas, diagrams, etc.
Common Reference Types:
- field_mapping: Database or API field mapping documents
- api_schema: API specification or schema files
- openapi_spec: OpenAPI/Swagger specifications
- architecture_diagram: Architecture diagrams or decision records
- data_model: Detailed data model specifications
Example:
documentation_references:
field_mapping: planning/006-feature/database-field-mapping.md
field_mapping_description: Complete field-by-field mapping from API to database
api_schema: planning/006-feature/api-spec.yaml
api_schema_description: OpenAPI 3.0 specification for external APINotes Section
notes: string # General implementation notes (optional)Validation Rules:
- Multi-line string using YAML pipe syntax (|)
- Should contain contextual information that doesn't fit other sections
- Keep focused and relevant (not a catch-all dumping ground)
Best Practices:
- Use for patterns, conventions, or integration notes
- Reference established architectural patterns in the codebase
- Document cross-cutting concerns not covered elsewhere
- Explain "why" decisions were made if not obvious
Common Uses:
- Integration patterns being followed
- Links to similar implementations for reference
- Critical context for future maintainers
- Clarifications on ambiguous requirements
---
Field Type Reference
| Type | Description | Example |
|---|---|---|
string | Text value | "User authentication system" |
array<string> | List of text values | ["Item 1", "Item 2"] |
enum | One of specified values | high, medium, low |
object | Nested structure | See section schemas above |
---
Validation Summary
Required Sections
- ✓
project,version,generated - ✓
overview(with problem, value_proposition, scope.in_scope) - ✓
personas(at least 1) - ✓
use_cases(at least 1) - ✓
functional_requirements(at least 1) - ✓
success_criteria(at least 1) - ✓
timeline(with phase, duration, milestones) - ✓
assumptions(at least 1)
Optional Sections
overview.scope.out_of_scopenon_functional_requirements(recommended)- Includes: performance, security, usability, reliability, maintainability, observability
constraints(recommended)- Includes: technical, business, timeline, budget, operational
dependencies(if applicable)risks(recommended)future_enhancements(optional, for roadmap planning)documentation_references(optional, links to detailed specs)notes(optional, contextual information)
Quality Gates
1. All functional requirements have rationale 2. Success criteria are measurable with targets 3. At least one persona with goals and pain points 4. Timeline includes specific milestones 5. Assumptions are explicit and testable
---
Markdown/PDF Conversion Strategy
Document Title
# Business Requirements: [project]
Version: [version] | Generated: [generated]Section Rendering
Overview Section:
## Problem Statement
[overview.problem]
## Value Proposition
[overview.value_proposition]
## Scope
**In Scope:**
- [scope.in_scope items as bullets]
**Out of Scope:**
- [scope.out_of_scope items as bullets]Personas Section:
## User Personas
### [persona.name]
[persona.description]
**Goals:**
- [persona.goals as bullets]
**Pain Points:**
- [persona.pain_points as bullets]Use Cases Section:
## Use Cases
### [use_case.name]
**Actor:** [use_case.actor]
[use_case.description]
**Expected Outcome:** [use_case.outcome]Functional Requirements:
## Functional Requirements
### [category] Requirements
| ID | Description | Priority | Rationale |
|----|-------------|----------|-----------|
| [id] | [description] | [priority] | [rationale] |Non-Functional Requirements:
## Non-Functional Requirements
### Performance
- [performance items as bullets]
### Security
- [security items as bullets]
### Usability
- [usability items as bullets]
### Reliability
- [reliability items as bullets]
### Maintainability
- [maintainability items as bullets]
### Observability
- [observability items as bullets]Success Criteria:
## Success Criteria
| Criterion | Metric | Target |
|-----------|--------|--------|
| [criterion] | [metric] | [target] |Constraints:
## Constraints
### Technical
- [technical constraints as bullets]
### Business
- [business constraints as bullets]
### Timeline
- [timeline constraints as bullets]
### Budget
- [budget constraints as bullets]
### Operational
- [operational constraints as bullets]Dependencies:
## Dependencies
### Internal
- [internal dependencies as bullets]
### External
- [external dependencies as bullets]Timeline:
## Timeline
**Phase:** [timeline.phase]
**Duration:** [timeline.duration]
**Milestones:**
- [milestones as bullets]Assumptions:
## Assumptions
- [assumptions as bullets]Risks:
## Risks
| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| [risk] | [probability] | [impact] | [mitigation] |Future Enhancements:
## Future Enhancements
- [enhancements as bullets]Documentation References:
## Documentation References
- **[key]**: [path/url]
- [key_description]Notes:
## Notes
[notes as multi-line text block]PDF Styling Recommendations
- Use hierarchical heading sizes (H1 → H2 → H3)
- Apply color coding to priority levels (high=red, medium=yellow, low=green)
- Use tables for structured data (requirements, success criteria, risks)
- Include page numbers and table of contents for documents >5 pages
- Add visual separators between major sections
- Highlight high-priority and high-impact items
---
Integration with Other Documents
Input Documents
gap-analysis-worksheet.yaml→ Informs completeness and quality
Output Documents
technical-requirements.yaml→ Derives from functional requirementsqa-test-plan.yaml→ Maps to functional requirements and personasdefinition-of-done.yaml→ References success criteriaarchitecture-decision-record/*.md→ Informed by constraints and non-functional requirements
Workflow Position
gap-analysis → business-requirements → technical-requirements → implementation-plan---
CLI Tool Support
Validation Command
sherpy validate business-requirements.yamlChecks:
- Schema compliance
- Required sections present
- ID sequencing (FR-1, FR-2, etc.)
- Enum values valid
- Field length constraints
- Referential integrity (use_case.actor matches persona.name)
Conversion Command
sherpy convert business-requirements.yaml --to markdown
sherpy convert business-requirements.yaml --to pdfGap Analysis Command
sherpy analyze business-requirements.yaml --gapsOutput:
- Completeness score (0-100)
- Missing recommended sections
- Weak or generic descriptions
- Untestable requirements
- Missing rationales
---
Best Practices
Writing Effective Requirements
DO:
- Use clear, specific language
- Make requirements testable
- Include rationale for every functional requirement
- Link requirements to personas and use cases
- Prioritize ruthlessly
DON'T:
- Use vague terms like "user-friendly" or "fast"
- Mix functional and non-functional requirements
- Create requirements without clear success criteria
- Assume implicit understanding
- Over-specify implementation details
Common Pitfalls
1. Vague Problem Statements
- ❌ "Users need a better experience"
- ✓ "Users spend 15+ minutes manually entering data that could be imported from CSV, causing frustration and data entry errors"
2. Untestable Requirements
- ❌ "System should be fast"
- ✓ "API responses must complete within 200ms at p95 under 1000 concurrent users"
3. Missing Rationale
- ❌ "FR-5: Support OAuth authentication"
- ✓ "FR-5: Support OAuth authentication - Reduces friction for enterprise users who require SSO integration per security policy"
4. Generic Personas
- ❌ "Users who want to use the system"
- ✓ "Sarah, Product Manager: Needs daily reports to track team velocity and unblock dependencies during standups"
5. Unmeasurable Success Criteria
- ❌ "Users are happy"
- ✓ "NPS score > 40 and < 10% support ticket rate within 3 months of launch"
---
Schema Version History
- 1.0.0 (2026-04-15): Initial specification
- Complete YAML schema definition
- Validation rules and constraints
- Markdown/PDF conversion strategy
- Integration with Sherpy workflow
---
Examples
See example.yaml for a complete, realistic business requirements document.
# Business Requirements Structure Template
# Copy this structure and replace placeholders with your content
#
# CRITICAL RULES:
# - Fields marked "OBJECT" must have nested keys, NOT pipe (|) syntax
# - Fields marked "ARRAY" must use dash (-) list format
# - Multiline strings use pipe (|) syntax
# - Sequential IDs: FR-1, FR-2, FR-3 (no gaps, no leading zeros)
project: "[Project Name]"
version: "1.0.0"
generated: "[ISO 8601 timestamp - YYYY-MM-DDTHH:MM:SSZ]"
overview:
# Multiline strings use pipe (|) syntax - minimum 50 characters
problem: |
[Multi-line problem statement describing the issue being solved.
Must be at least 50 characters. Include specific pain points and context.]
# Multiline string - minimum 30 characters
value_proposition: |
[Multi-line value proposition explaining what value this delivers.
Must be at least 30 characters.]
# CRITICAL: scope is an OBJECT with arrays, NOT a string
# ❌ WRONG: scope: | "MVP focused on..."
# ✅ CORRECT: scope: (with nested keys below)
scope:
in_scope: # Array of strings - minimum 1 item required
- "[In scope item 1]"
- "[In scope item 2]"
- "[In scope item 3]"
out_of_scope: # Optional array
- "[Out of scope item 1]"
- "[Out of scope item 2]"
# Array of persona objects - minimum 1 required
personas:
- name: "[Persona Name]" # 2-50 characters
description: |
[Multi-line persona description. Minimum 20 characters.
Who they are, their role, responsibilities, and context.]
goals: # Array - minimum 1 item required
- "[Goal 1 - what they want to achieve]"
- "[Goal 2 - another goal]"
pain_points: # Array - minimum 1 item required
- "[Pain point 1 - current frustration or blocker]"
- "[Pain point 2 - another pain point]"
# Add more personas as needed
- name: "[Second Persona Name]"
description: |
[Description of second persona]
goals:
- "[Goal 1]"
pain_points:
- "[Pain point 1]"
# Array of use case objects - minimum 1 required
use_cases:
- name: "[Use Case Name]" # 5-100 characters
actor: "[Persona Name]" # MUST match a persona name exactly or be "System"
description: |
[Multi-line description of what the actor does in this scenario.
Minimum 20 characters. Describe the actions step by step.]
outcome: "[Expected outcome - minimum 10 characters]"
- name: "[Second Use Case]"
actor: "[Second Persona Name]"
description: |
[Description of second use case - minimum 20 characters]
outcome: "[What they achieve]"
# Array of functional requirement objects - minimum 1 required
functional_requirements:
# CRITICAL: IDs must be sequential starting from FR-1
# ❌ WRONG: FR-001, FR-01, FR-1.1
# ✅ CORRECT: FR-1, FR-2, FR-3
- id: FR-1
category: "[Category Name]" # e.g., "Authentication", "Data Management", "User Interface"
description: |
[Detailed requirement description. Minimum 20 characters.
Must be specific, testable, and implementable.]
priority: high # Enum: high, medium, low (lowercase only)
rationale: |
[Why this requirement is needed. Minimum 10 characters.
Explain the business or technical reason.]
- id: FR-2 # Next sequential ID
category: "[Category Name]"
description: |
[Description of second requirement]
priority: medium
rationale: |
[Rationale for second requirement]
- id: FR-3
category: "[Category Name]"
description: |
[Description of third requirement - minimum 20 characters]
priority: low
rationale: |
[Rationale for third requirement]
# Optional - but recommended
non_functional_requirements:
performance: # Optional array - include if you have performance requirements
- "[Performance requirement 1 - e.g., 'API response time < 200ms at p95']"
- "[Performance requirement 2]"
security: # Optional array
- "[Security requirement 1 - e.g., 'OWASP Top 10 compliance']"
- "[Security requirement 2]"
usability: # Optional array
- "[Usability requirement 1 - e.g., 'WCAG 2.1 Level AA compliance']"
reliability: # Optional array
- "[Reliability requirement 1 - e.g., '99.5% uptime SLA']"
maintainability: # Optional array
- "[Maintainability requirement 1 - e.g., 'Code coverage >80%']"
observability: # Optional array
- "[Observability requirement 1 - e.g., 'Structured logging for all operations']"
# Array of success criterion objects - minimum 1 required (3 recommended)
success_criteria:
- criterion: "[Success criterion description - what defines success]"
metric: "[How to measure it - the measurement method]"
target: "[Specific target value - e.g., '85%+ WAU' or '$1M ARR']"
- criterion: "[Second criterion]"
metric: "[Measurement method]"
target: "[Target value]"
- criterion: "[Third criterion]"
metric: "[Measurement method]"
target: "[Target value]"
# Optional - but recommended
constraints:
technical: # Optional array
- "[Technical constraint 1 - e.g., 'Must use PostgreSQL', 'Cloud-native architecture']"
- "[Technical constraint 2]"
business: # Optional array
- "[Business constraint 1 - e.g., 'Ship within 16 weeks', 'Team of 4 engineers']"
timeline: # Optional array
- "[Timeline constraint 1 - e.g., 'Beta by Week 14']"
budget: # Optional array
- "[Budget constraint 1 - e.g., 'Total MVP budget $400K']"
operational: # Optional array
- "[Operational constraint 1 - e.g., 'Deploy to AWS us-east-1']"
# Optional
dependencies:
internal: # Optional array
- "[Internal dependency 1 - e.g., 'Design system from UX team (due Week 2)']"
- "[Internal dependency 2]"
external: # Optional array
- "[External dependency 1 - e.g., 'OpenAI API access for GPT-4']"
- "[External dependency 2]"
# CRITICAL: timeline is an OBJECT, NOT a string
# ❌ WRONG: timeline: | "16 weeks"
# ✅ CORRECT: timeline: (with nested keys below)
timeline:
phase: "[Phase name - e.g., MVP, Beta, v1.0, Phase 1]"
duration: "[Duration - e.g., 8 weeks, 3 months, Q2 2026]"
milestones: # Array - minimum 1 item required
- "[Milestone 1 - e.g., 'Week 4: Core features complete']"
- "[Milestone 2 - e.g., 'Week 8: Integration testing']"
- "[Milestone 3 - e.g., 'Week 16: Public launch']"
# Array of strings - minimum 1 required (3 recommended)
assumptions:
- "[Assumption 1 - what you're assuming to be true]"
- "[Assumption 2 - another assumption]"
- "[Assumption 3 - a third assumption]"
# Optional array - 3 recommended
risks:
- risk: "[Risk description - 20-300 characters. What could go wrong?]"
probability: high # Enum: high, medium, low (lowercase only)
impact: high # Enum: high, medium, low (lowercase only)
mitigation: |
[Mitigation strategy - actionable steps to prevent or reduce the risk.
Minimum 20 characters, maximum 500 characters.]
- risk: "[Second risk description]"
probability: medium
impact: medium
mitigation: |
[Mitigation for second risk]
- risk: "[Third risk description - 20-300 characters]"
probability: low
impact: medium
mitigation: |
[Mitigation for third risk]
# Optional array - for future roadmap planning
future_enhancements:
- "[Future enhancement 1 - feature deferred until after MVP]"
- "[Future enhancement 2]"
# Optional map of key-value pairs for linking to other documents
documentation_references:
field_mapping: "[path/to/field-mapping.md]"
field_mapping_description: "[What this document contains - e.g., 'Database field mapping']"
api_schema: "[path/to/api-schema.yaml]"
api_schema_description: "[What this document contains - e.g., 'OpenAPI 3.0 spec']"
# Optional multiline string for additional context
notes: |
[Additional notes, context, or implementation guidance.
Use this for patterns, conventions, or cross-cutting concerns that don't
fit in other sections. Keep focused and relevant.]
Related skills
Setup Matt Pocock SkillsScaffold the per-repo configuration that Matt Pocock’s engineering agent skills rely on so they understand the issue tracker, triage labels, and domain documentation la495k196k
Lark AppsConnect Claude, Cursor or custom agents directly to Lark (Feishu) for messaging, document automation, approval workflows and enterprise data access.402k
CavemanSlash token usage by roughly 75% while keeping every technical detail intact when working with Claude Code, Cursor or similar agents.391k94.7k
Lark Skill MakerQuickly turn any Lark/Feishu OpenAPI call or multi-step workflow into a reusable agent skill with its own SKILL.md.386k16k
Running Claude Code Via Litellm CopilotRun Claude Code at a fraction of the cost by routing requests through LiteLLM to the GitHub Copilot Chat API.270k72
Codex PetGenerate a complete Codex Pet spritesheet and metadata from one reference image without needing an OpenAI key or Codex Pro.246k10AI & Agent Buildingagents