Requirements Gathering This skill covers a structured 5-phase requirements gathering workflow for new features. It guides you through initial setup and codebase analysis, context discovery questions, autonomous context gathering, expert requirements questions, and final requirements documentation — producing a comprehensive spec ready for implementation. Start Workflow Begin gathering requirements for a new feature using this structured 5-phase process. Phase 1: Initial Setup & Codebase Analysis Get current timestamp: date "+%Y-%m-%d-%H%M" Extract slug from the feature description (e.g., "add user profile" -> "user-profile") Create folder: requirements/[timestamp]-[slug]/ Create initial files: 00-initial-request.md with the user's request metadata.json with status tracking Create/update requirements/.current-requirement with folder name Analyze project codebase structure: apps/web-app/ - TanStack Start frontend + TRPC server packages/ - Shared packages (db, services, common, logger, agents) Identify relevant existing features and patterns Phase 2: Context Discovery Questions Generate 5 yes/no questions to understand the problem space. Focus areas for the project: User interactions and workflows Organization/project scope (org-scoped vs user-scoped) Data model requirements (new tables vs extending existing) UI requirements (new pages vs extending existing) Integration with existing features (auth, billing, integrations) Question format:

Q1: Will this feature be organization-scoped (vs user-scoped)? ** Default if unknown: ** Yes (most project features are org-scoped)

Q2: Will users interact with this through a new page/route? ** Default if unknown: ** Yes (most features have dedicated UI)

Q3: Does this require new database tables? ** Default if unknown: ** No (prefer extending existing schema)

Q4: Will this integrate with external services/APIs? ** Default if unknown: ** No (unless explicitly mentioned)

Q5: Should this be accessible to all org members or only admins? ** Default if unknown: ** All members (with appropriate role checks) Process: Write ALL questions to 01-discovery-questions.md with smart defaults Ask questions ONE at a time, proposing default Accept: yes / no / idk (use default) After ALL answered, record in 02-discovery-answers.md Update metadata.json Phase 3: Targeted Context Gathering (Autonomous) After discovery questions answered: Search relevant code using available tools: Find similar features in apps/web-app/src/ Check existing TRPC routers in apps/web-app/src/*/trpc/ Review database schema in packages/db/src/schema.ts Check existing UI patterns in apps/web-app/src/shared/ Analyze patterns from similar features: How similar TRPC routers are structured How similar pages use TanStack Router loaders Database table conventions Form handling patterns Document findings in 03-context-findings.md :

Codebase Analysis

Similar Features Found

[Feature name] at [path] - [why relevant]

Relevant Files to Modify/Extend

apps/web-app/src/[module]/trpc/[router].ts - [what to add] - packages/db/src/schema.ts - [new tables if needed]

Patterns to Follow

TRPC router pattern from [example]

TanStack route pattern from [example]

Form pattern from [example]

Technical Constraints

[Any limitations discovered]

Integration Points

[Services/modules this will interact with] Phase 4: Expert Requirements Questions Now ask questions like a senior developer who knows the project codebase. Focus on clarifying system behavior:

Q1: Should we extend the existing [Router]Router at [path]? ** Default if unknown: ** Yes (maintains consistency)

Q2: For the UI, should we follow the pattern from [similar feature]? ** Default if unknown: ** Yes (established pattern)

Q3: Should this data be cached in TanStack Query or fetched fresh? ** Default if unknown: ** Cached (standard for most data)

Q4: Should we add E2E tests for this flow? ** Default if unknown: ** Yes (if user-facing feature)

Q5: Should validation happen client-side, server-side, or both? ** Default if unknown: ** Both (Zod on frontend, TRPC input validation on backend) Process: Write questions to 04-detail-questions.md Ask ONE at a time Record answers in 05-detail-answers.md after all asked Phase 5: Requirements Documentation Generate comprehensive spec in 06-requirements-spec.md :

Requirements Specification: [Name] Generated: [timestamp] Status: Complete

Overview [Problem statement and solution summary]

Functional Requirements

User Stories

As a [role], I want to [action] so that [benefit]

Acceptance Criteria

[ ] [ Testable criterion ]

Technical Requirements

Database Changes

New table: [name] in packages/db/src/schema.ts - Fields: [list with types]

TRPC Router

Location: apps/web-app/src/[module]/trpc/[name].ts - Procedures: [list] - Use protectedMemberAccessProcedure for org-scoped operations

Frontend Routes

New route: /app/[path] - Components: [list] - Pattern to follow: [reference]

Files to Create/Modify 1. packages/db/src/schema.ts - Add table 2. apps/web-app/src/[module]/trpc/[name].ts - Add router 3. apps/web-app/src/routes/app/[path]/route.tsx - Add page

Implementation Notes

Patterns to Follow

TRPC: See trpc-patterns skill - Frontend: See tanstack-frontend skill

Testing

Unit tests in packages/services/src/__tests__/ - E2E tests in apps/web-app/e2e/

Assumptions [Any defaults used for unanswered questions] Metadata Structure { "id" : "feature-slug" , "started" : "ISO-8601-timestamp" , "lastUpdated" : "ISO-8601-timestamp" , "status" : "active" , "phase" : "discovery|context|detail|complete" , "progress" : { "discovery" : { "answered" : 0 , "total" : 5 } , "detail" : { "answered" : 0 , "total" : 5 } } , "contextFiles" : [ "paths/of/files/analyzed" ] , "relatedFeatures" : [ "similar features found" ] } Phase Transitions After each phase, announce: "Phase complete. Starting [next phase]..." Save all work before moving to next phase User can check progress anytime with /requirements-status End Workflow Finalize the current requirement gathering session. Instructions Read requirements/.current-requirement If no active requirement: No active requirement to end. Use /requirements-list to see all requirements. Show current status and ask user intent: Ending requirement: [name] Current phase: [phase] ([X/Y] complete) What would you like to do? 1. Generate spec with current information 2. Mark as incomplete for later 3. Cancel and delete Choose (1/2/3): Based on choice: Option 1: Generate Spec Create 06-requirements-spec.md Include all answered questions Add defaults for unanswered with "ASSUMED:" prefix Generate implementation hints based on project patterns Update metadata.json status to "complete" Spec format:

Requirements Specification: [Name] Generated: [timestamp] Status: Complete with [N] assumptions

Overview [Problem statement from initial request] [Solution summary based on answers]

Functional Requirements [Based on answered questions]

User Stories

As a [role], I want to [action] so that [benefit]

Acceptance Criteria

[ ] [ Criterion based on answers ]

Technical Requirements

Database Changes [If applicable based on answers]

TRPC Router

Location: apps/web-app/src/[module]/trpc/ - Procedures needed: [list]

Frontend Routes

Path: /app/[route] - Components: [list]

Files to Create/Modify [Specific paths in project codebase]

Implementation Notes

Patterns to Follow

TRPC: Load skill trpc-patterns - Frontend: Load skill tanstack-frontend

Validation

Run bun run check after implementation - Add E2E tests if user-facing

Assumptions (REVIEW THESE) [List any defaults used for unanswered questions] - ASSUMED: [Question] -> [Default used] because [reason]

Next Steps 1. Review assumptions above 2. Start implementation 3. Run /code-review before PR Option 2: Mark Incomplete Update metadata.json : { "status" : "incomplete" , "lastUpdated" : "[timestamp]" , "pausedAt" : "[phase]" , "remainingQuestions" : [ N ] } Create summary of progress Note what's still needed Output: Requirement marked as incomplete. Progress saved: - Phase: [current phase] - Questions answered: [X/Y] - Last activity: [now] To resume later: /requirements-status Option 3: Cancel Confirm deletion: Are you sure you want to delete this requirement? All gathered information will be lost. Type 'yes' to confirm: If confirmed: Remove requirement folder Clear .current-requirement Output: Requirement cancelled and deleted. Start fresh: /requirements-start [description] Post-Completion After generating spec (Option 1): Clear .current-requirement Show summary: Requirements complete! Spec saved: requirements/[folder]/06-requirements-spec.md Next steps: 1. Review the spec, especially ASSUMPTIONS section 2. Start implementation 3. Use /code-review before creating PR View spec: Read @requirements/[folder]/06-requirements-spec.md Status Workflow Show current requirement gathering progress and continue from last question. Instructions Read requirements/.current-requirement If no active requirement: No active requirement gathering session. Options: - Start new: /requirements-start [description] - List all: /requirements-list If active requirement exists: Read metadata.json for current phase and progress Show formatted status Load appropriate question/answer files Continue from last unanswered question Status Display Format Active Requirement: [name] Started: [time ago] Phase: [Discovery/Context/Detail/Complete] Progress: [X/Y] questions answered --- Recent Progress --- [Show last 3 answered questions with responses] --- Next Question --- [Show next unanswered question with default] Type 'yes', 'no', or 'idk' (uses default) Continuation Flow Read next unanswered question from file: Phase 2: 01-discovery-questions.md Phase 4: 04-detail-questions.md Present to user with default Accept response: yes / y - Affirmative no / n - Negative idk / default / d - Use default value DO NOT record answer yet - wait until ALL questions in phase are asked After ALL questions answered: Update answer file ( 02-discovery-answers.md or 05-detail-answers.md ) Update metadata.json progress Move to next question or phase Phase Transitions Discovery (Phase 2) -> Context (Phase 3): All 5 discovery questions answered Record answers in 02-discovery-answers.md Run autonomous context gathering (no user interaction) Create 03-context-findings.md Context (Phase 3) -> Detail (Phase 4): Context findings documented Generate expert questions based on findings Write to 04-detail-questions.md Begin asking detail questions Detail (Phase 4) -> Complete (Phase 5): All detail questions answered Record answers in 05-detail-answers.md Generate final spec in 06-requirements-spec.md Update status to "complete" Clear .current-requirement Quick Actions Continue: Just respond to the question Skip phase: /requirements-end (generates spec with current info) View all: /requirements-current List all: /requirements-list Current Workflow Display detailed information about the active requirement. This is view-only — it does not continue gathering. Instructions Read requirements/.current-requirement If no active requirement: No active requirement. Recent completed requirements: [Show last 3 completed with dates] Start new: /requirements-start [description] List all: /requirements-list For active requirement: Load all files from requirement folder Display comprehensive status Show codebase analysis overview Show all questions and answers so far Display context findings if available Indicate current phase and next steps File Structure requirements/[timestamp]-[slug]/ ├── 00-initial-request.md # Original user request ├── 01-discovery-questions.md # Context discovery questions ├── 02-discovery-answers.md # User's answers (after all asked) ├── 03-context-findings.md # AI's codebase analysis ├── 04-detail-questions.md # Expert requirements questions ├── 05-detail-answers.md # User's detailed answers ├── 06-requirements-spec.md # Final requirements document └── metadata.json # Status tracking Display Format =========================================== Current Requirement: [name] =========================================== Duration: [time since start] Phase: [Initial Setup/Discovery/Context/Detail/Complete] Progress: [total answered]/[total questions]

INITIAL REQUEST

[Content from 00-initial-request.md]

CODEBASE OVERVIEW (Phase 1)

Architecture: TanStack Start + TRPC + PostgreSQL + Drizzle Relevant modules identified: - [module 1]: [why relevant] - [module 2]: [why relevant]

DISCOVERY PHASE (5/5 complete)

Q1: Will this be organization-scoped? YES Q2: Will users interact through a new page? YES Q3: Does this require new database tables? NO Q4: Will this integrate with external APIs? NO (default) Q5: Should this be accessible to all members? YES

CONTEXT FINDINGS

Similar Features Found: - [Feature] at [path] - [pattern to follow] Files to Modify: - apps/web-app/src/[module]/trpc/[router].ts - packages/db/src/schema.ts (if needed) Patterns Identified: - TRPC: [pattern reference] - Frontend: [pattern reference]

EXPERT QUESTIONS (2/5 answered)

Q1: Extend existing UserRouter? YES Q2: Follow pattern from ProjectSettings? YES Q3: Cache data in TanStack Query? [PENDING] Q4: Add E2E tests? [PENDING] Q5: Validation on both client and server? [PENDING]

NEXT ACTION

Current: Answering expert question Q3 Options: - Continue: /requirements-status - End early: /requirements-end - View all: /requirements-list Important Notes This is view-only (doesn't continue gathering) Shows complete history and context Use /requirements-status to continue answering questions All file paths are relative to project root List Workflow Display all requirements with their status and summaries. Instructions Check requirements/.current-requirement for active requirement List all folders in requirements/ directory For each requirement folder: Read metadata.json Extract key information Format for display Sort by: Active first (if any) Then by status: complete, incomplete Then by date (newest first) Display Format Requirements Documentation --- ACTIVE --- [name] Phase: Discovery (3/5) | Started: 30m ago Request: [first line of 00-initial-request.md] Next: Continue with /requirements-status --- COMPLETE --- 2025-01-26-0900-dark-mode-toggle Status: Ready for implementation Questions answered: 10 Summary: [first line of spec overview] Spec: requirements/2025-01-26-0900-dark-mode-toggle/06-requirements-spec.md 2025-01-25-1400-export-reports Status: Implemented Questions answered: 10 Summary: PDF/CSV export with filtering --- INCOMPLETE --- 2025-01-24-1100-notification-system Status: Paused at Detail phase (2/5) Last activity: 2 days ago Resume: /requirements-status --- STATISTICS --- Total: 4 requirements - Complete: 2 - Active: 1 - Incomplete: 1 Stale Detection Mark if incomplete > 7 days: 2025-01-15-old-feature (STALE - 8 days) Consider: Resume or cancel with /requirements-end Linked Artifacts For complete requirements, check if there are: Related git branches Pull requests (search git log for requirement name) Implementation status Quick Actions Quick Actions: - View active detail: /requirements-current - Resume incomplete: /requirements-status - Start new: /requirements-start [description] - End/cancel active: /requirements-end Empty State If no requirements exist: No requirements found. Start gathering requirements for a new feature: /requirements-start [feature description] Example: /requirements-start add dark mode toggle to settings Remind Workflow Quick correction when deviating from requirements gathering rules. Instructions Check requirements/.current-requirement If no active requirement: Show "No active requirement gathering session" Exit Display reminder based on current context: 🔔 Requirements Gathering Reminder You are gathering requirements for: [active-requirement] Current phase: [Initial Setup/Context Discovery/Targeted Context/Expert Requirements] Progress: [X/Y questions] 📋 PHASE-SPECIFIC RULES: Phase 2 - Context Discovery: - ✅ Ask 5 yes/no questions about the problem space - ✅ Questions for product managers (no code knowledge required) - ✅ Focus on user workflows, not technical details - ✅ Write ALL questions before asking any - ✅ Record answers ONLY after all questions asked Phase 3 - Targeted Context (Autonomous): - ✅ Use RepoPrompt tools to search and read code - ✅ Analyze similar features and patterns - ✅ Document findings in context file - ❌ No user interaction during this phase Phase 4 - Expert Requirements: - ✅ Ask 5 detailed yes/no questions - ✅ Questions as if speaking to PM who knows no code - ✅ Clarify expected system behavior - ✅ Reference specific files when relevant - ✅ Record answers ONLY after all questions asked 🚫 GENERAL RULES: 1. ❌ Don't start coding or implementing 2. ❌ Don't ask open-ended questions 3. ❌ Don't record answers until ALL questions in phase are asked 4. ❌ Don't exceed 5 questions per phase 📍 CURRENT STATE: - Last question: [Show last question] - User response: [pending/answered] - Next action: [Continue with question X of 5] Please continue with the current question or read the next one from the file. Common Correction Scenarios Open-ended question asked: "Let me rephrase as a yes/no question..." Multiple questions asked: "Let me ask one question at a time..." Implementation started: "I apologize. Let me continue with requirements gathering..." No default provided: "Let me add a default for that question..." Auto-trigger Patterns Detect code blocks → remind no implementation Multiple "?" in response → remind one question Response > 100 words → remind to be concise Open-ended words ("what", "how") → remind yes/no only Important Rules These rules apply across all phases of requirements gathering: ONLY yes/no questions with smart defaults — never open-ended questions ONE question at a time — never ask multiple questions in a single message Write ALL questions to file BEFORE asking any — prepare the full set first, then ask sequentially Stay focused on requirements — no implementation, no code, no technical solutions during gathering Use actual file paths from codebase — reference real paths like apps/web-app/src/[module]/trpc/ not generic placeholders Document WHY each default makes sense — every default must have a rationale (e.g., "most project features are org-scoped") Reference similar existing features as examples — ground questions in concrete codebase patterns Do NOT record answers until ALL questions in a phase are asked — collect all responses before writing to answer files Phase 3 is fully autonomous — no user interaction during targeted context gathering Maximum 5 questions per phase — keep each phase focused and bounded