project-requirements

name	project-requirements
description	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.
metadata	{"portable":true,"compatible_with":["claude-code","codex"]}

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, [phone].

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.

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.