02. Requirements - khalillabban/Snorting-Code GitHub Wiki

Project Backlog

All user stories for this project are managed within the GitHub Issues system. You can view the current prioritized backlog, including acceptance criteria and story points, via the link below:

Backlog Organization Strategy

The backlog is structured using a clear hierarchy:

  • Epics β†’ represent high-level features or functional areas
  • User Stories β†’ represent deliverable features from a user perspective
  • Subtasks β†’ represent implementation steps or acceptance criteria

User stories are grouped into epics and labeled with consistent identifiers to maintain traceability across the project lifecycle.

We use two main epic naming conventions:

  • EPIC-# β†’ for feature development (e.g., EPIC-1: Campus Navigation)
  • EPIC-0# Sprint # Infrastructure β†’ for process, tooling, and non-feature work

This separation ensures that feature development and infrastructure tasks are tracked independently while remaining visible.

User Story Structure

All user stories follow the standardized format:

As a [user], I want [functionality], so that [goal/benefit]

Each user story includes:

  • Clear description from a user perspective
  • Explicit acceptance criteria written as checkboxes
  • Story points for sprint planning
  • Linked subtasks when necessary

This ensures that requirements are unambiguous and testable during acceptance testing.

Identification and Naming Convention

Each epic and user story follows a consistent ID structure:

  • Epics: EPIC-1, EPIC-2, etc.

  • User Stories: US-1.1, US-1.2, etc.

    • First number β†’ Epic number
    • Second number β†’ Story index within the epic

Example:

  • EPIC-1: Explore the campus map

    • US-1.1: View both SGW and Loyola campuses
    • US-1.2: Display building shapes
    • US-1.3: Toggle between campuses
    • US-1.4: Show current building
    • US-1.5: Display building information

This convention ensures consistent traceability between requirements, implementation, and testing.

Example Breakdown

Given the requirement β€œExplore the campus map”, we decompose it into:

  1. Support both SGW and Loyola campus maps
  2. Display building shapes distinct from city structures
  3. Enable campus switching via toggle
  4. Show current building location
  5. Display additional building information

Each of these becomes a separate user story under the same epic.

Task Decomposition and Parallelization

User stories are further broken down into subtasks when needed. These subtasks:

  • Mirror acceptance criteria
  • Allow parallel development
  • Keep tasks small and manageable
  • Improve sprint predictability

Example:

  • UI implementation
  • API integration (Google Maps)
  • State management
  • Testing

This decomposition allows multiple developers to work simultaneously on a single feature while maintaining cohesion.

Integration with Branching and PR Workflow

The backlog is tightly integrated with our development workflow:

  • Branch naming format:

    • sprint#/type/usX.X-description
    • Example: sprint2/feature/us1.3-toggle-between-campuses

  • Types include:

    • feature, bugfix, hotfix, infra

  • Pull requests:

    • Linked to issues using Closes #<issue number>
    • Automatically close issues upon merge
    • Maintain clean traceability from requirement to code

This creates a full pipeline: Epic β†’ User Story β†’ Task β†’ Branch β†’ PR β†’ Merge

Acceptance Criteria and Definition of Done

Each user story includes explicit acceptance criteria to ensure clarity and alignment with the Product Owner.

A user story is considered complete only when:

  • All acceptance criteria are satisfied
  • Feature is tested and validated
  • No blocking issues remain
  • Code review is approved
  • CI checks pass

This reduces ambiguity and ensures consistent delivery quality.

Continuous Improvement and Process Maturity

Throughout the project, the backlog process evolved significantly:

  • User stories became more granular and better scoped
  • Acceptance criteria became more precise and testable
  • Tasks were broken down earlier to avoid bottlenecks
  • Infrastructure work was separated from feature work
  • Retrospective actions were directly applied to backlog structure

We also introduced:

  • Labels for better categorization
  • Stronger linkage between bugs and epics
  • Improved traceability across all development stages

Key Outcomes

This backlog structure enabled:

  • Clear requirement traceability
  • Efficient sprint planning and estimation
  • Parallel development without conflicts
  • Strong alignment between features and user needs
  • Seamless integration with CI, PRs, and testing

Overall, the backlog served as the foundation for organizing development, ensuring clarity, and maintaining consistency across the entire project lifecycle.