Mahdaad Dev Handbook

Appearance

Definition of Ready ​

Product & Requirements

  • Acceptance Criteria (AC) must be clear, testable, and unambiguous.
  • ACs must be reviewed and approved by QA and Dev during grooming sessions.

Design & User Experience

  • Final designs (Figma) include all states: Empty, Filled, Error, and Success.
  • Design review must be completed with the Dev team (meeting or async). On design phase completion, Mentioning CTO on comments in Figma is mandatory, after sprint planning and assignee determination, responsible developers should rely on provided Figma Link in Task description.
  • If designs are still WIP, an alternate path and delivery timeline must be defined.

QA & Test Readiness

  • QA must confirm that the feature is testable.
  • Common and edge test scenarios must be identified.
  • Any API or automation testing requirements should be clearly stated.

Technical & Implementation

  • Story complexity must be estimated (Story Points).
  • Backend/API requirements must be clearly listed.
  • If data model changes are involved, a migration strategy must be provided.
  • All dependencies must be documented (Dependency Table).

Documentation & Deliverables

  • Any required documentation (API behavior, functional specs) must be defined.
  • Any hand-offs or deliverables to QA or other teams should be specified.

Exceptions

For research tasks (Spikes), early stage UX stories, or market testing features, certain criteria may be skipped with explicit approval from the PM and Tech Lead.

Supporting Documents for DoR

DocumentPurposeSuggested Location
Acceptance Criteria TemplateStandardize AC formatClaytap / Google Docs
Design Review LogTrack design feedbackFigma Comments + Oktuple
QA Feasibility ChecklistEnsure test readinessGoogle Docs
Dependency TableTrack story-level dependenciesOktuple Task or Epic
Technical Readiness NoteDev-oriented technical contextMarkdown or within Task
Backend Contract NoteEarly-stage API contract definitionsOpenAPI JSON

Writing Acceptance Criteria

There are multiple ways to write ACs. The team is encouraged to use a flexible hybrid approach depending on the type of story.

Common AC Patterns:

1. Given/When/Then (BDD-style)

Given the user is logged in,

When they click "Create Task",

Then a modal opens with fields: title, description, and priority.

2. Rules-Oriented (Bullet Style)

  • The form must not be submitted without the “email” field filled.
  • Email must follow standard format.
  • On success, show message: “Submitted successfully”.

3. Checklist-Based

  • Users can upload a profile image.
  • Only PNG and JPG formats are allowed.
  • Max file size must be < 2MB.
  • Image preview must be updated immediately after upload.

Final Suggested Format

Acceptance Criteria (Given/When/Then)

  1. Given...
  2. When...
  3. Then...

Additional Rules

  • ...

Test Data / Constraints (Optional)

  • ...

Real World Example

Feature: Task Creation with Dependency Selection & Role Assignment

Acceptance Criteria (Given/When/Then)

  1. Given a user with the "Project Manager" role is logged in,
    When they click "Create Task",
    Then a form is shown with the following fields:
    • Title (required)
    • Description (optional)
    • Start/End date (must be valid and chronologically correct)
    • Dependencies (select one or more tasks from the current project)
    • Role Assignment (select users with roles: Reviewer / Contributor / Observer)
  2. Given a regular team member is logged in,
    When they click "Create Task",
    Then a message is shown: “You do not have permission to create tasks.”
  3. Given the user enters incomplete or invalid data (missing title, date mismatch),
    When they click "Submit",
    Then inline error messages are shown and no API call is made.
  4. Given the user enters valid data,
    When they submit the form,
    Then:
    • A POST request is sent to /api/v1/tasks with structured data
    • On 201 Created, the user is redirected to the task details page
    • On server error (500), show: “System error. Please try again.”

Additional Rules

  • Only tasks from the current project should be selectable as dependencies.
  • The end date must be later than the start date.
  • Only project members can be assigned roles (Reviewer/Contributor).
  • If a selected dependency is already in “Done” status, allow selection but show a warning: This task depends on a completed task.

Test Data / Constraints

  • Test with 1 dependency, 3 roles, and scenario with no role selected.
  • Test start date after end date.
  • Test with a non-manager user.
  • Test API behavior in online and offline mode.

Security Notes

  • User role must be verified via JWT or auth token on the server side.
  • Filtering of users and tasks must happen server side (not just on the client).