# Project Requirements

> Use when a guided discovery interview must produce requirements, business rules, user types, and workflows for a new SaaS project; use systems-process-requirements when formal traceability, interfaces, states, and acceptance criteria are the primary need.

- Skill: `peterbamuhigire/project-requirements-3` (Agent Skill)
- Install (CLI): `npx skillmds@latest add peterbamuhigire/project-requirements-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/peterbamuhigire/project-requirements-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: peterbamuhigire (https://skillmd.com/u/peterbamuhigire)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/peterbamuhigire/project-requirements-3

---


## Platform Notes

- Optional helper plugins may help in some environments, but they must not be treated as required for this skill.

# Project Requirements Documentation Helper
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->
## Use When

- Guided interview to create comprehensive project requirements documentation (requirements.md, business-rules.md, user-types.md, workflows.md) for a new SaaS project. Use before bootstrapping the SaaS Seeder Template.
- The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

## Do Not Use When

- The task is unrelated to `project-requirements` or would be better handled by a more specific companion skill.
- The request only needs a trivial answer and none of this skill's constraints or references materially help.


## Project Requirements Required Context
- Gather relevant project context, constraints, and the concrete problem to solve.
- Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.


## Project Requirements Core Method Notes
- Read this `SKILL.md` first, then load only the referenced deep-dive files that are necessary for the task.
- Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
- Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

## Quality Standards

- Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
- Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
- Prefer deterministic, reviewable steps over vague advice or tool-specific magic.


## Project Requirements Existing Failure Notes
- Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
- Loading every reference file by default instead of using progressive disclosure.


## Project Requirements Core Deliverables
- A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
- Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
- References used, companion skills, or follow-up actions when they materially improve execution.

## Evidence Produced

| Category | Artifact | Format | Example |
|----------|----------|--------|---------|
| Release evidence | Requirements documentation set | Markdown docs covering requirements.md, business-rules.md, and user-types.md per the guided interview | `docs/requirements/requirements.md` |


## Project Requirements Source Notes
- Use the links and companion skills already referenced in this file when deeper context is needed.
<!-- dual-compat-end -->
Create comprehensive requirements documentation for a new SaaS project through a guided AI-assisted interview process.

For any non-trivial system, load `systems-process-requirements` before finalizing requirements. This adds requirements classification, scope control, context/system boundaries, workflow/state modeling, data architecture extraction, business-rule separation, acceptance criteria, and traceability.

## When to Use

Use when starting a new SaaS project from the template:

- "Help me create project requirements for [SaaS name]"
- "I need to document requirements for my SaaS"
- "Create requirements documentation for a new project"
- "Guide me through requirements gathering"

## Purpose

This skill helps developers create the required documentation files that must be placed in `docs/project-requirements/` **BEFORE** bootstrapping the SaaS Seeder Template.

## Output Files

The skill creates four core documentation files plus optional UI mockups:

```
docs/project-requirements/
├── requirements.md       # Feature requirements & specifications
├── business-rules.md     # Business logic & validation rules
├── user-types.md         # User roles and permissions
├── workflows.md          # Key user workflows
└── ui-mockups/           # Optional UI designs (images/PDFs)

**Documentation Requirement (Mandatory):**
- Define the end-user manual scope for each core feature so manuals can be built immediately after implementation.

**Planning Index Rule:** When feature plans are created later, always update `docs/plans/INDEX.md` with status, urgency, last implementation date, and last modification date.
```

## Guided Interview Process

### Phase 1: Project Overview (requirements.md foundation)

**Questions to ask:**

1. **Project Basics**
   - What is the name of your SaaS?
   - What domain/industry? (School, Restaurant, Medical, E-commerce, etc.)
   - Who are the primary users?
   - What is the main problem you're solving?
   - Target launch date?

2. **Core Features** (iterative)
   For each feature:
   - What is the feature name?
   - Brief description (1-2 sentences)
   - User stories: "As a [user type], I want to [action] so that [benefit]"
   - Acceptance criteria (specific, testable requirements)
   - Priority: High / Medium / Low

   **Example prompts:**
   - "Let's start with your top 3 most important features"
   - "What happens when a user clicks this button?"
   - "What data needs to be collected?"
   - "What validations are needed?"

3. **Non-Functional Requirements**
   - Performance expectations (concurrent users, response times)
   - Security requirements
   - Scalability needs (how many franchises, users per franchise)
   - Usability requirements (mobile, offline, languages)
   - GIS requirements (Leaflet maps, geofencing, optional tile provider API key if needed)
   - Documentation requirements (manuals, guides, release notes, FAQs)

**Output:** Generate `docs/project-requirements/requirements.md`

### Phase 2: Business Rules (business-rules.md)

**Questions to ask:**

1. **Validation Rules**
   For each entity/form:
   - What fields are required?
   - What are the validation rules? (length, format, range)
   - Are there unique constraints?
   - Cross-field validations?

2. **Calculations**
   - What formulas/algorithms are needed? (GPA, pricing, discounts, etc.)
   - Provide examples with sample inputs and outputs
   - Edge cases to handle

3. **State Machines**
   - What statuses can entities have? (e.g., student: PENDING → ACTIVE → GRADUATED)
   - What are valid transitions?
   - What triggers each transition?
   - What transitions are not allowed and why?

4. **Business Constraints**
   - Capacity limits (e.g., max students per class)
   - Time-based rules (e.g., can't modify grades after term closes)
   - Access restrictions (e.g., teachers only see their own subjects)

**Output:** Generate `docs/project-requirements/business-rules.md`

### Phase 3: User Types (user-types.md)

**Questions to ask:**

1. **User Type Identification**
   - Beyond owner/staff, what custom user types do you need?
   - Examples: student, teacher, parent, customer, patient, waiter, chef
   - Which users are "end users" vs "franchise staff"?

2. **For Each User Type:**
   - What is their role/purpose?
   - What can they do? (capabilities)
   - What data can they access?
   - Which panel do they use? (franchise admin vs member portal)
   - Does franchise_id apply? (REQUIRED for non-super_admin)

3. **Permissions**
   - What permission codes are needed?
   - Which user types get which permissions?
   - Any special access rules?

4. **Registration Workflows**
   - How is each user type created/registered?
   - Self-registration or admin-created?
   - What information is collected?

**Output:** Generate `docs/project-requirements/user-types.md`

### Phase 4: Workflows (workflows.md)

**Questions to ask:**

1. **Key Workflows Identification**
   - What are the 3-5 most important user journeys?
   - Examples: student enrollment, grade submission, fee payment, order placement

2. **For Each Workflow:**
   - Who are the actors? (users, system, external services)
   - What triggers this workflow?
   - What are the preconditions?
   - What are the postconditions?

3. **Step-by-Step Flow**
   For each step:
   - Who does what?
   - What does the system do in response?
   - What data is collected/saved?
   - Any branching logic?

4. **Alternative Flows & Errors**
   - What can go wrong?
   - How should errors be handled?
   - What alternative paths exist?

**Output:** Generate `docs/project-requirements/workflows.md`

### Phase 5: UI Mockups (Optional)

**Questions to ask:**

1. Do you have UI mockups or wireframes?
2. If yes: Place files in `docs/project-requirements/ui-mockups/`
3. Reference them in requirements.md where relevant

## Interview Techniques

### Ask Follow-Up Questions

**When user gives vague answer:**

```
User: "I need a student management system"
AI: "Great! Let's break that down:
  - What information do you need to track about students?
  - How do students get enrolled?
  - Who can view/edit student data?
  - What reports do you need?"
```

### Use Examples

**When explaining complex concepts:**

```
AI: "For grade calculation, here's an example:
  Subject 1: Grade A (4.0), Credits 3 → 4.0 × 3 = 12
  Subject 2: Grade B (3.0), Credits 4 → 3.0 × 4 = 12
  GPA = (12 + 12) ÷ (3 + 4) = 24 ÷ 7 = 3.43

  Does this match your grading system?"
```

### Provide Templates

**Show structure to guide thinking:**

```
AI: "For each feature, let's capture:
  ✓ Feature name
  ✓ Description
  ✓ User stories
  ✓ Acceptance criteria
  ✓ Priority

  Let's start with your first feature..."
```

## Requirements Quality Standards

### Good Requirements

✅ **Specific:** "Student email must be unique within franchise" not "email must be valid"
✅ **Testable:** "GPA calculated as weighted average" with formula
✅ **Complete:** All user types, all workflows, all validations documented
✅ **Unambiguous:** Clear language, examples provided
✅ **Prioritized:** High/Medium/Low for features

### Red Flags

❌ **Too vague:** "The system should be user-friendly"
❌ **Missing details:** "User can edit data" (which data? which users?)
❌ **Assumptions:** "Obviously students can't delete grades" (document it!)
❌ **No examples:** Formula without sample calculation

## Template Usage

**Reference the template files:**

When starting the interview, tell the user:

```
I'll help you create comprehensive requirements documentation.
We have template files to guide us:
- requirements.md.template
- business-rules.md.template
- user-types.md.template
- workflows.md.template

Let's start with your project overview...
```

**Use template structure but customize content:**

- Replace example content with user's actual requirements
- Add more sections as needed
- Remove sections not applicable
- Keep examples where they help clarify

## Integration with SaaS Seeder

**After completing requirements documentation:**

1. Verify files are in `docs/project-requirements/`:

   ```
   ✓ requirements.md
   ✓ business-rules.md
   ✓ user-types.md
   ✓ workflows.md
   ```

2. Create database schema in `database/schema/core-schema.sql` based on requirements

3. Run the `saas-seeder` skill to bootstrap the template:
   ```
   "Using the saas-seeder skill, prepare this repository for [Project Name]"
   ```

## Validation Checklist

Before completing, verify:

- [ ] All four core files created
- [ ] `systems-process-requirements` gate passed for system boundary, scope, workflows, data entities, business rules, and traceability
- [ ] Each feature has acceptance criteria
- [ ] User types clearly defined
- [ ] Key workflows documented step-by-step
- [ ] Validation rules specified
- [ ] Calculations have examples
- [ ] State transitions documented
- [ ] Permission codes listed
- [ ] Multi-tenant requirements considered (franchise_id filtering)

## Output Confirmation

When complete, report to user:

```
✅ Project Requirements Documentation Complete!

Created Files:
- ✓ docs/project-requirements/requirements.md
- ✓ docs/project-requirements/business-rules.md
- ✓ docs/project-requirements/user-types.md
- ✓ docs/project-requirements/workflows.md

Summary:
- Features documented: [count]
- User types defined: [list]
- Key workflows: [list]
- Business rules: [count]

Next Steps:
1. Review the documentation files
2. Create database schema in database/schema/core-schema.sql
3. Run the saas-seeder skill to bootstrap your project
4. Start development!

Ready to bootstrap? Use:
"Using the saas-seeder skill, prepare this repository for [Your Project Name]"
```

## Best Practices

**Do:**

- Ask open-ended questions first, then drill down
- Provide examples to illustrate concepts
- Summarize what you've learned before moving to next section
- Offer to add more details if user thinks of something later
- Keep documentation practical and actionable

**Don't:**

- Assume requirements without asking
- Skip validations and edge cases
- Create generic documentation (make it specific to their SaaS)
- Overwhelm with too many questions at once
- Forget to save progress incrementally

## References

- Template files in `docs/project-requirements/*.template`
- `saas-seeder` skill for bootstrapping after requirements
- `../../CLAUDE.md` - Project-specific documentation after bootstrap
- Multi-tenant patterns: All franchise-scoped data needs franchise_id

## Cross-References to SDLC Skills

### Downstream Skills (use AFTER this skill)

| Skill | Relationship |
|-------|-------------|
| `sdlc-planning` | Takes this skill's output (requirements.md, business-rules.md, user-types.md, workflows.md) as input for Feasibility Study, Vision & Scope, SRS, and other planning documents. **This is the primary next step.** |
| `systems-process-requirements` | Formal requirements engineering, workflow/state/process modeling, data architecture, scope, and traceability discipline used inside this skill. |
| `sdlc-design` | Uses the SRS (produced via `sdlc-planning`) to generate System Design Document, Database Design, API Documentation, and Technical Specifications. |
| `sdlc-testing` | Uses the SRS and SDD to create test plans, test cases, and V&V documentation. |
| `sdlc-user-deploy` | Uses all prior SDLC outputs to create user manuals, deployment guides, training materials, and release notes. |
| `feature-planning` | For individual feature specs and implementation plans after project-level requirements are established. |
| `android-saas-planning` | For Android companion app planning (PRD, SDS, API Contract). Uses SRS as input. |
| `saas-seeder` | Bootstrap the SaaS template using requirements from this skill's output. |

### Complete SDLC Workflow

```
project-requirements (THIS SKILL)
    ↓ requirements.md, business-rules.md, user-types.md, workflows.md
sdlc-planning
    ↓ SRS, Vision & Scope, SDP, Feasibility Study, QA Plan, Risk Plan, SCMP
sdlc-design
    ↓ SDD, Database Design, Tech Spec, API Docs, ICD, Code Standards
sdlc-testing
    ↓ Test Plan, Test Cases, V&V Plan, Test Report, Peer Reviews
sdlc-user-deploy
    ↓ User Manual, Ops Guide, Training, Release Notes, Maintenance, README
```

## Inputs

| Artefact | Source or provider | Required? | If absent |
|---|---|---|---|
| Product objective, sponsor, users, constraints, and known business rules | Sponsor and discovery participants | required | Begin with bounded discovery and record every unresolved item as a gap |


## Workflow
1. Confirm sponsor, decision, scope boundary, users, constraints, and output location.
2. Interview from outcomes to workflows, data, rules, permissions, states, errors, and acceptance.
3. Stop when a decision owner is absent or conflicting rules cannot be resolved.
4. Draft and play back each section; recover by logging open questions, owners, and a resumption point.


## Outputs
| Artefact | Consumer | Acceptance |
|---|---|---|
| Requirements, business rules, user types, and workflows | Architecture, planning, and delivery teams | Scope, rules, actors, states, exceptions, and acceptance criteria are traceable and approved |


## Project Requirements Evidence Notes
| Evidence | Consumer | Acceptance |
|---|---|---|
| Discovery log, decision register, traceability matrix, and approval record | Sponsor and delivery lead | Each requirement has a source, owner, status, and acceptance test |

## Capability Contract

Default to read-only discovery and analysis. Read and search are required; editing repository requirements or creating downstream artefacts requires explicit authority.

## Degraded Mode

If stakeholders, repository access, or decision authority are unavailable, return the narrowest qualified draft with gaps and unassessed approval checks.

## Decision Rules

| Choice | Action | Failure avoided |
|---|---|---|
| Requirement changes formal scope, interface, state, or traceability | Route through `systems-process-requirements` | Informal scope hidden in notes |
| Stakeholders disagree on a business rule | Record alternatives and decision owner; stop finalisation | Invented consensus |


## Anti-Patterns
- Assuming a requirement from a familiar SaaS pattern. Fix: confirm it with a source owner.
- Asking many compound questions at once. Fix: use one decision-focused question.
- Writing vague acceptance criteria. Fix: state observable preconditions, action, and result.
- Omitting error and empty states. Fix: inspect each workflow branch.
- Treating an open question as approved scope. Fix: keep it in the gap and decision register.

## Worked Example

For an enrolment feature, identify the authorised actor, required data, validation failures, approval state, success event, and acceptance test, then link each item to the interview source.