Gap Analysis Worksheet

Gap Analysis Worksheet

Analyzes an initial requirements document for gaps, ambiguities, and missing information. Produces gap-analysis-worksheet.md — a structured worksheet for a business analyst to complete before proceeding to /business-requirements-interview.

Purpose

Initial requirements from stakeholders typically contain:

• Vague or ambiguous statements
• Missing personas or user types
• Undefined scope boundaries
• Unstated assumptions
• Missing non-functional requirements
• Undefined success criteria

This skill surfaces those gaps as targeted questions, ensuring the formal requirements interview builds on validated, complete inputs.

Prerequisites

• An initial requirements document in any format: plain text, Markdown, YAML, PDF summary, meeting notes, product brief, or similar

Usage

/gap-analysis-worksheet path/to/requirements [base-directory]

If no base directory is provided, auto-detect by looking for requirements/ folder in the current directory.

If not found, prompt the user: "Where should I create the gap analysis worksheet?"

Wait for the user to provide a path before proceeding. Store as base_directory.

Process

Step 1: Load & Read the Requirements

Read the input document in full. Identify all stated requirements, goals, personas, constraints, and assumptions.

Step 2: Analyze for Gaps by Category

For each category below, scan the document and identify gaps. A gap is any of:

• Missing — Information that should be present but isn't stated at all
• Ambiguous — A statement that could be interpreted multiple ways
• Incomplete — A requirement that is only partially specified
• Contradictory — Statements that conflict with each other
• Assumed — Something implied but never explicitly stated

Gap Categories (evaluate all eleven):

1. Problem & Goals — Is the core problem clearly defined? Are goals specific and measurable? 2. Personas & Users — Are all user types identified? Are their needs and pain points described? 3. Scope — What is explicitly in scope vs. out of scope? Where are the boundaries? 4. Functional Requirements — Are all features described with enough detail to build? Are edge cases addressed? 5. Non-Functional Requirements — Performance, security, scalability, accessibility, reliability expectations? 6. Success Criteria — How will success be measured? What does "done" look like? 7. Assumptions — What is being assumed but not stated? What dependencies are implied? 8. Constraints — Technical, timeline, budget, regulatory, or team constraints? 9. Dependencies & Integrations — External systems, APIs, third-party services, or team dependencies? 10. Risks — What could go wrong? Are any mitigation strategies needed? 11. UI/UX Implications — Does the project involve user-facing interfaces? Are all screens/pages identified? Are interaction patterns described? Are accessibility requirements stated? Is there a design system or component library? Are responsive/mobile considerations addressed? When gaps are found, add recommendation: "UI work detected — wireframe planning will be triggered after implementation planning (Step 6)."

Skip any category that has no gaps — do not include empty sections in the output.

Step 3: Write gap-analysis-worksheet.md

Write {base_directory}/requirements/gap-analysis-worksheet.md.

Create directory if it doesn't exist:

mkdir -p {base_directory}/requirements

Output Format

Write {base_directory}/requirements/gap-analysis-worksheet.md.

The output is a Markdown document with a header (document path, generated date, status, total gaps) followed by sections for each gap category. Each gap includes a requirement snippet, a specific question, and an answer field.

See [references/output-spec.md](references/output-spec.md) for the complete document specification with all categories, gap structure, and validation rules.

See [references/example.yaml](references/example.yaml) for a full example.

Writing Good Gap Questions

Be specific — Reference the exact requirement or missing area.

Good: What is the maximum file size a user can upload?

Bad: Are there any limits?

Be answerable — The business analyst should be able to respond with a concrete answer.

Good: Should unauthenticated users be able to view public workflows, or is login required for all access?

Bad: What about authentication?

One gap per question — Do not combine multiple gaps into one question.

Good: What should happen when a workflow task fails — should the entire workflow stop, or continue with remaining tasks?

Bad: What should happen with errors and timeouts and retries?

Prioritize critical gaps — Questions about core functionality, personas, and scope come before nice-to-have clarifications.

Requirement Snippet Guidelines

• Use a direct quote from the document when possible — keep it under 15 words
• If the gap is about something entirely missing, use: "Not addressed in requirements"
• If the gap applies to a whole section rather than a specific line, reference the section: "[Goals section]"

Example Output

See [references/example.yaml](references/example.yaml) for a complete sample based on the spec example input.

Self-Review

After generating the worksheet, perform the following checks and output a brief summary inline.

Checks

• [ ] All 11 categories were evaluated (skipped categories had no gaps worth capturing)
• [ ] Every question is specific and answerable by a business analyst
• [ ] No two questions address the same gap
• [ ] Critical gaps (scope, personas, core functionality) are listed first within their category
• [ ] Requirement snippets accurately reflect the source document
• [ ] No category with real gaps was omitted

Inline Summary

## Worksheet Summary

**Input:** [requirements file]
**Output:** gap-analysis-worksheet.md
**Total Gaps Found:** [n]

By Category:
  Problem & Goals:              [n gaps or "✓ no gaps"]
  Personas & Users:             [n gaps or "✓ no gaps"]
  Scope:                        [n gaps or "✓ no gaps"]
  Functional Requirements:      [n gaps or "✓ no gaps"]
  Non-Functional Requirements:  [n gaps or "✓ no gaps"]
  Success Criteria:             [n gaps or "✓ no gaps"]
  Assumptions:                  [n gaps or "✓ no gaps"]
  Constraints:                  [n gaps or "✓ no gaps"]
  Dependencies & Integrations:  [n gaps or "✓ no gaps"]
  Risks:                        [n gaps or "✓ no gaps"]
  UI/UX Implications:           [n gaps or "✓ no gaps"]

Next step → Complete the worksheet, then run:
  /business-requirements-interview

Gap Analysis Worksheet Specification

Document Overview

Purpose

The Gap Analysis Worksheet surfaces gaps, ambiguities, and missing information in an initial requirements document. It provides structured questions for a business analyst to answer before formal requirements gathering begins.

Role in Workflow

• Phase: Requirements (Step 1 of Sherpy Flow)
• Generated By: /gap-analysis-worksheet skill
• Input Dependencies: Initial requirements document (any format: MD, TXT, PDF, YAML, meeting notes)
• Output Consumers: Business analyst (manual completion) → /business-requirements-interview (uses completed worksheet as context)

When to Use

• At project start when stakeholder requirements are vague or incomplete
• When converting informal requirements into structured specifications
• Before beginning the formal business requirements interview to ensure quality inputs

---

File Format & Location

File Details

• Filename: gap-analysis-worksheet.yaml
• Format: YAML
• Location: {base_directory}/requirements/gap-analysis-worksheet.yaml
• Character Encoding: UTF-8

Directory Structure

{base_directory}/
└── requirements/
    └── gap-analysis-worksheet.yaml

Conversion Utilities

A CLI tool can be created to convert YAML to presentation formats:

• gap-analysis-worksheet.yaml → gap-analysis-worksheet.md (Markdown for review)
• gap-analysis-worksheet.yaml → gap-analysis-worksheet.pdf (PDF for stakeholders)

---

YAML Schema Definition

Root Structure

metadata:
  source_document: string           # Path to original requirements file
  generated_date: date              # YYYY-MM-DD format
  status: enum                      # "awaiting_review" | "in_progress" | "completed"
  total_gaps: integer               # Count of all gap entries
  version: string                   # Schema version (e.g., "1.0")

categories:
  - name: string                    # Category name (see standard list below)
    gaps:
      - id: integer                 # Sequential gap number
        requirement: string         # Quoted text or "not_addressed"
        question: string            # Specific, answerable question
        answer: string | null       # null when generated, filled by BA
        priority: enum              # "critical" | "high" | "medium" | "low"
        tags: array<string>         # Optional tags for filtering/grouping

Complete Example Structure

metadata:
  source_document: "docs/initial-requirements.md"
  generated_date: "2026-04-15"
  status: "awaiting_review"
  total_gaps: 22
  version: "1.0"

categories:
  - name: "problem_and_goals"
    gaps:
      - id: 1
        requirement: "Help teams stay organized"
        question: "What specific organizational problems are teams experiencing today?"
        answer: null
        priority: "critical"
        tags: ["scope", "goals"]

      - id: 2
        requirement: "Reduce missed deadlines"
        question: "How are deadlines currently being missed?"
        answer: null
        priority: "high"
        tags: ["metrics"]

---

Field Definitions

Metadata Section

Status Values:

• awaiting_review - Generated, not yet reviewed by BA
• in_progress - BA actively filling in answers
• completed - All answers provided and validated

Category Section

Standard Categories (use these exact values): 1. problem_and_goals - Core problem definition and measurable goals 2. personas_and_users - User types, needs, and pain points 3. scope - Boundaries, in-scope vs. out-of-scope 4. functional_requirements - Feature details and edge cases 5. non_functional_requirements - Performance, security, scalability, accessibility 6. success_criteria - Measurement of success and definition of "done" 7. assumptions - Implied dependencies and unstated assumptions 8. constraints - Technical, timeline, budget, regulatory constraints 9. dependencies_and_integrations - External systems, APIs, third-party services 10. risks - Potential issues and mitigation strategies

Gap Object

Priority Values:

• critical - Blocks requirements gathering if unanswered
• high - Core functionality or scope questions
• medium - Important clarifications
• low - Nice-to-have clarifications

Requirement Field Values:

• Direct quote from source (max 200 characters)
• "not_addressed" if gap is about entirely missing information
• "[section_name] section" if gap applies to entire section

---

Validation Rules

Structural Validation

• [ ] Root has metadata and categories keys
• [ ] Metadata contains all required fields
• [ ] All metadata fields match type constraints
• [ ] Status is one of the three valid enum values
• [ ] Categories is non-empty array
• [ ] Each category has name and gaps keys
• [ ] Category names match standard list exactly
• [ ] No duplicate category names
• [ ] Each category has at least one gap
• [ ] Each gap has all required fields
• [ ] Gap IDs are sequential integers starting at 1 within each category

Content Validation

• [ ] generated_date is valid ISO 8601 format
• [ ] total_gaps matches actual count of gap objects
• [ ] version follows semver format (X.Y)
• [ ] All requirement strings are non-empty
• [ ] All question strings are non-empty
• [ ] All priority values are valid enum values
• [ ] All answer values are either null or non-empty strings
• [ ] Gap IDs start at 1 in each category

Quality Validation

• [ ] Questions are specific and answerable
• [ ] No duplicate questions across all categories
• [ ] Requirement snippets accurately reference source
• [ ] Critical/high priority gaps listed first in each category
• [ ] Tags are lowercase and descriptive

---

Generation Guidelines

Analysis Process

1. Load Source Document

• Read complete initial requirements document
• Identify all stated requirements, goals, personas, constraints
• Note implicit assumptions

2. Evaluate Each Category

• Scan for 5 gap types:
• Missing: Information not stated at all → requirement: "not_addressed"
• Ambiguous: Multiple possible interpretations → quote ambiguous text
• Incomplete: Partially specified requirements → quote incomplete text
• Contradictory: Conflicting statements → quote contradiction
• Assumed: Implied but never explicit → quote assumption

3. Assign Priority

• critical: Scope boundaries, core personas, fundamental features
• high: Important functionality, key constraints, major integrations
• medium: Feature details, minor constraints, optional integrations
• low: Nice-to-have clarifications, edge cases

4. Order Gaps

• Within each category: critical → high → medium → low
• Within same priority: most impactful first

5. Write Targeted Questions

• Reference specific requirement text
• Make questions actionable
• Ensure BA can answer without technical expertise
• One question per gap (no compound questions)

Gap Detection Patterns by Category

problem_and_goals

• Vague objectives without metrics ("improve", "better", "faster")
• Missing problem statement or baseline
• Undefined success criteria
• Goals without measurable targets
• Priority: Usually critical/high (defines project purpose)

personas_and_users

• Generic "users" without types or roles
• Missing persona count/scale
• Undefined user needs or pain points
• No role-based permissions mentioned
• Priority: Critical for user-facing apps

scope

• No in-scope/out-of-scope boundary stated
• Undefined MVP vs. future phases
• Missing platform coverage (mobile, desktop, etc.)
• Data migration not addressed
• Priority: Critical (prevents scope creep)

functional_requirements

• Feature listed without behavior description
• Edge cases not addressed
• Multi-user scenarios undefined
• No error handling specified
• Missing notification strategy
• Priority: High for core features, medium for secondary

non_functional_requirements

• Vague performance terms ("fast", "scalable")
• Security mentioned without specifics
• No compliance requirements stated
• Accessibility not addressed
• Missing monitoring/observability
• Priority: High for regulated/critical systems

success_criteria

• No measurable outcomes defined
• Missing adoption targets
• Undefined rollout strategy
• No post-launch metrics
• Priority: High (defines project success)

assumptions

• Implied integrations without details
• Technical choices not questioned
• Unstated dependencies
• "Should work with X" without specifics
• Priority: Medium/high based on impact

constraints

• No timeline mentioned
• Budget not addressed
• Technology stack not specified
• Team size or skills not stated
• Priority: Critical if project has hard deadlines

dependencies_and_integrations

• Third-party services implied but not listed
• API requirements undefined
• Authentication mechanism not specified
• Data sources not identified
• Priority: High for integration-heavy projects

risks

• No risk assessment performed
• Competing priorities not addressed
• Technical feasibility not questioned
• Regulatory concerns not raised
• Priority: Medium (risk management)

---

Usage Examples

Example 1: Missing Information Gap

- id: 7
  requirement: "not_addressed"
  question: "Roughly how many users are expected to use the app — tens, hundreds, or thousands?"
  answer: null
  priority: "high"
  tags: ["scale", "personas"]

Example 2: Ambiguous Requirement Gap

- id: 11
  requirement: "Assign tasks to team members"
  question: "Can a task be assigned to multiple people simultaneously, or is each task owned by exactly one person?"
  answer: null
  priority: "high"
  tags: ["assignment", "collaboration"]

Example 3: Vague Goal Gap

- id: 1
  requirement: "Help teams stay organized"
  question: "What specific organizational problems are teams experiencing today — are tasks being tracked in spreadsheets, email threads, sticky notes, or another tool?"
  answer: null
  priority: "critical"
  tags: ["problem_statement", "baseline"]

Example 4: Incomplete Technical Requirement

- id: 20
  requirement: "We use Google Workspace so it should integrate with that somehow"
  question: "Which Google Workspace integration is required for launch — Google login (SSO), Google Calendar sync for due dates, Google Drive for attachments, or all of the above?"
  answer: null
  priority: "high"
  tags: ["integration", "authentication", "mvp"]

Example 5: Completed Gap (After BA fills in)

- id: 12
  requirement: "Mark tasks as complete"
  question: "What task statuses are needed beyond 'complete' — for example: To Do, In Progress, Blocked, In Review, Done?"
  answer: "We need 5 statuses: Backlog, In Progress, In Review, Blocked, and Done. Tasks start in Backlog and can only move to Done from In Review."
  priority: "critical"
  tags: ["workflow", "states"]

---

Self-Review Checklist

After generating, verify:

Structural Completeness

• [ ] YAML is valid and parseable
• [ ] All required fields present
• [ ] All enum values are valid
• [ ] Gap IDs are sequential within categories
• [ ] Total gaps count is accurate

Content Quality

• [ ] All 10 categories were evaluated
• [ ] Every question is specific and answerable by BA
• [ ] No two questions address the same gap
• [ ] Critical/high priority gaps listed first in each category
• [ ] Requirement snippets accurately reflect source document
• [ ] Tags are relevant and lowercase

Generation Completeness

• [ ] No real gaps were omitted
• [ ] Categories with no gaps are excluded (not included with empty gaps array)
• [ ] Priority assignments are appropriate
• [ ] Questions follow quality guidelines

---

Output Summary Format

After generation, display this inline summary:

## Worksheet Summary

**Input:** [requirements file path]
**Output:** gap-analysis-worksheet.yaml
**Total Gaps Found:** [n]

By Category:
  Problem & Goals:              [n gaps or "✓ no gaps"]
  Personas & Users:             [n gaps or "✓ no gaps"]
  Scope:                        [n gaps or "✓ no gaps"]
  Functional Requirements:      [n gaps or "✓ no gaps"]
  Non-Functional Requirements:  [n gaps or "✓ no gaps"]
  Success Criteria:             [n gaps or "✓ no gaps"]
  Assumptions:                  [n gaps or "✓ no gaps"]
  Constraints:                  [n gaps or "✓ no gaps"]
  Dependencies & Integrations:  [n gaps or "✓ no gaps"]
  Risks:                        [n gaps or "✓ no gaps"]

Priority Breakdown:
  Critical: [n]
  High: [n]
  Medium: [n]
  Low: [n]

Next step → Complete the worksheet, then run:
  /business-requirements-interview

---

Conversion to Markdown/PDF

Markdown Conversion

A CLI utility can convert the YAML to markdown format:

# Future implementation
sherpy convert gap-analysis-worksheet.yaml --to markdown

# Or using a generic tool
yaml-to-md gap-analysis-worksheet.yaml

Markdown Output Structure:

# Gap Analysis Worksheet

**Document:** {source_document}
**Generated:** {generated_date}
**Status:** {status}
**Total Gaps:** {total_gaps}

---

## {Category Name}

### Gap {id} [{priority}]

**Requirement:** "{requirement}"
**Question:** {question}
**Answer:** {answer or blank line}
**Tags:** {tags as comma-separated list}

---

PDF Conversion

Use md-to-pdf or similar tools for stakeholder distribution:

# Two-step conversion
sherpy convert gap-analysis-worksheet.yaml --to markdown
md-to-pdf gap-analysis-worksheet.md

---

Related Documents

• Input: Initial requirements document (any format)
• Output Consumer: /business-requirements-interview skill
• Downstream Impact: business-requirements.yaml quality depends on gap resolution
• Workflow Position: Step 1 of Sherpy Flow

---

Version History