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