Backend API verification protocol for GraphQL-dependent features

backend-verification.mdc

---
description: Backend API verification protocol for GraphQL-dependent features
globs:
alwaysApply: true
---

# Backend Verification Protocol

## Activation Protocol

**This protocol activates in TWO ways for maximum reliability:**

### 1. AUTOMATIC (Proactive - Smart Detection):
- After reading Jira ticket with GraphQL/API mentions in acceptance criteria
- When PLAN reveals new or modified GraphQL operations needed
- When analyzing dependencies reveals undefined backend fields/types
- When component implementation expects API data not yet verified
- When acceptance criteria explicitly require backend functionality
- Before creating new GraphQL operation files in `src/graphql/operations/`
- When error indicates missing/incorrect API parameters or return types

### 2. USER-TRIGGERED (Reactive - Explicit Requests):
- Any mention of "backend verification", "check backend", "API ready"
- Questions about GraphQL mutations/queries ("does the mutation exist?")
- Questions about API endpoints or parameters ("what parameters does it take?")
- Requests to verify backend implementation status
- Questions about backend blockers or dependencies
- Mentions of backend repository or backend tickets

**Both paths execute the same verification process below - ensuring no implementation proceeds without backend validation.**

---

## When Backend Verification is REQUIRED

Backend verification MUST be performed when:
1. Task involves **new or modified GraphQL queries/mutations**
2. Task depends on **backend API changes** mentioned in Jira ticket
3. Task is **blocked by prerequisite backend tickets**
4. Acceptance criteria explicitly mention **backend functionality** that must exist
5. Task requires **new API endpoints or parameters**

## When Backend Verification is NOT Required

Skip backend verification when:
1. Task is **pure UI changes** (styling, layout, responsive design)
2. Task is **frontend-only refactoring** (component reorganization, hook extraction)
3. Task uses **existing, already-verified GraphQL operations** (no new queries/mutations)
4. Task is **documentation updates** only
5. Task is **configuration changes** (environment variables, build settings)
6. Task is **testing or tooling** improvements

## Backend Verification Process

### Step 1: Determine if Verification is Needed
1. Read Jira ticket acceptance criteria
2. Identify if task mentions GraphQL operations, API changes, or backend work
3. **Explicitly state your reasoning**: "Backend verification required because..." OR "Backend verification not required because this is a frontend-only task"
4. If required, proceed to Step 2. If not required, document decision in plan and skip to frontend implementation.

### Step 2: Search for Related Backend Work
1. **Search Jira** for related backend tickets:
   - Same epic number
   - Related ticket numbers mentioned in ticket
   - Backend team members assigned
   - Use MCP Jira tools: `mcp__mcp-atlassian__jira_get` and `mcp__mcp-atlassian__jira_ls_issues`

2. **Search Backend Repository** (e.g., GitHub/GitLab):
   - Use **feature-related search terms** (e.g., "presell", "SeasonPass", "listing mutation")
   - DO NOT assume mutation/query names - discover organically
   - Search patterns:
     - `repo:[org/backend-repo] [feature-keyword]`
     - `repo:[org/backend-repo] [entity-name] mutation`
     - `repo:[org/backend-repo] [entity-name] query`

### Step 3: Locate Backend Implementation
1. **Find GraphQL schema definition**:
   - Search for schema files (common locations: `schema/`, `graphql/`, or main handler files)
   - Look for mutation/query registration patterns in your backend framework
   - Extract mutation/query name and constants

2. **Find resolver implementation**:
   - Search for resolver files (common patterns: `resolvers/`, `handlers/`, `gqlresolver/`)
   - Find the resolver function implementation
   - Document parameter types and validation logic

3. **Find API layer logic** (optional):
   - Search for business logic files (common patterns: `api/`, `services/`, `controllers/`)
   - Understand business logic and constraints

### Step 4: Document Backend Verification Report

**Required Information:**
- **Discovery Process**: Search terms used, files examined, methodology
- **Mutation/Query Name**: Exact name from backend code
- **Parameters**: Complete list with types and required/optional status
- **Return Type**: What the mutation/query returns
- **Implementation Status**: ✅ Complete / ⏳ In Progress / ❌ Not Started
- **GraphQL Endpoint**: URL (e.g., `https://api.example.com/graphql`)
- **Backend Files**: Links to schema, resolver, and API files
- **Key Findings**: Parameter naming conventions, special behaviors, constraints, validation rules

**Report Template:**
```markdown
## Backend Verification Report

**Verification Required:** [Yes/No - with reasoning]

**Discovery Process:**
- Searched Jira: [ticket numbers found]
- Searched backend repository using terms: "[search-terms]"
- Located schema: `[path/to/schema]:[line]`
- Located resolver: `[path/to/resolver]:[line]`

**Mutation/Query Name:** `[exactName]`

**Parameters:**
- `param1: Type!` (required) - Description
- `param2: Type` (optional) - Description

**Return Type:**
```graphql
type ReturnType {
  field1: String
  field2: Int
}
```

**Implementation Status:** ✅ Complete and deployed to [environment]

**GraphQL Endpoint:** `[your-graphql-endpoint-url]`

**Backend Repository:** [Link to backend repository]
- Schema: `[path/to/schema]:[line]`
- Resolver: `[path/to/resolver]:[line]`
- API Layer: `[path/to/api-logic]:[line]` (if applicable)

**Key Findings:**
- [Important discovery 1]
- [Important discovery 2]
- [Constraint or special behavior]

**Blockers:** [None / List any issues found]
```

### Step 5: Block Implementation if Backend Not Ready

**CRITICAL:** If backend implementation is NOT complete:
1. Mark plan status as "⏳ BLOCKED - Awaiting Backend"
2. List specific backend tickets that must be completed first
3. Document what frontend work can proceed (if any)
4. DO NOT generate frontend GraphQL operations until backend is verified
5. Notify user of blocker and provide backend ticket status

## Integration with Planning Process

This backend verification step integrates into the planning workflow:

1. **Task Initiation** → Restate request, clarify ambiguities
2. **Pre-Planning Analysis** → Gather requirements, analyze codebase
3. **⭐ Backend Verification** → [THIS STEP - if applicable]
4. **Plan Generation** → Include backend verification report in plan
5. **User Approval** → Get confirmation before implementation
6. **Execution** → Implement using verified backend details

## Examples

### Example 1: Backend Verification Required
**Task:** "Add ability to edit SeasonPass presell times"
**Reasoning:** Requires GraphQL mutation to update database → Backend verification REQUIRED
**Action:** Search for backend mutation, verify parameters, document findings

### Example 2: Backend Verification NOT Required
**Task:** "Change SeasonPass table button colors from blue to green"
**Reasoning:** Pure CSS/styling change, no API interaction → Backend verification NOT required
**Action:** Document "Backend verification skipped - frontend-only styling task" in plan

### Example 3: Backend Verification BLOCKS Implementation
**Task:** "Display new refund status field in EventPass table"
**Discovery:** GraphQL query doesn't include `refundStatus` field yet
**Action:** Mark as BLOCKED, document prerequisite backend ticket PV-1234, wait for completion

## Checklist for Plans with Backend Dependencies

- [ ] Determined if backend verification is required (with reasoning)
- [ ] If required: Searched Jira for related backend tickets
- [ ] If required: Searched backend repository using feature-related terms
- [ ] If required: Located and examined GraphQL schema definition
- [ ] If required: Located and examined resolver implementation
- [ ] If required: Documented complete backend verification report
- [ ] If required: Verified backend implementation status
- [ ] If blocked: Documented blocking backend tickets
- [ ] Included backend verification section in implementation plan
- [ ] Got user approval before proceeding with implementation