St Saviour's Development Workflows

Comprehensive workflow system for Next.js 16 + Payload CMS development. All workflows enforce a two-phase research approach: exploration (web search) followed by verification (official docs).

Research Approach (Mandatory for All Workflows)

Every workflow requiring research MUST execute both phases in order:

Phase A: EXPLORATION (Web Search)

Cast a wide net. Discover possible solutions, community fixes, known issues, and approaches you might not have considered.

Phase B: VERIFICATION (Context7)

Use official documentation to confirm solutions from Phase A are valid, current, and correctly implemented.

**CRITICAL**: Do NOT skip Phase A. Do NOT skip Phase B. Both are mandatory.

---

Workflow: error investigation

**Trigger**: "perform error investigation on [error/file]"

Execute ALL phases:

1. **LOCATE**: Parse error message and stack trace. Identify file(s) and line(s). Read those files completely.

2. **TRACE**: Trace ALL imports in erroring file to their source. Search for ALL files that import the erroring code (`grep -r`). Check related types, interfaces, schemas.

3. **REPRODUCE**: Understand exact trigger conditions. Identify data flow leading to error. Check edge cases (null, undefined, empty, async timing).

4. **EXPLORE** - Web Search (minimum 8 searches):

- Search exact error message

- Search error + framework/library versions

- Search GitHub issues for this error

- Search Stack Overflow for similar problems

- Search for breaking changes that might cause this

- Look for multiple possible causes/solutions

- Gather 2-3 candidate explanations

5. **VERIFY** - Context7 (for EVERY library involved):

- `resolve-library-id` then `query-docs` for each library

- Confirm which candidate solution is correct

- Verify fix uses current API patterns

- Check for deprecations or version-specific behaviour

6. **ROOT CAUSE**: Present findings with evidence. Explain WHY not just WHAT. List ALL affected files. Check if pattern exists elsewhere.

7. **SOLUTIONS**: Present 2-3 options ranked by correctness and safety. Cite sources. Wait for approval before implementing.

---

Workflow: deep research

**Trigger**: "perform deep research on [topic]"

Execute ALL phases:

1. **SCOPE**: Clarify what specifically needs researching. Identify all technologies involved.

2. **EXPLORE** - Web Search (minimum 10 searches):

- Search for current approaches (2024-2025)

- Search for comparisons between solutions

- Search for best practices

- Search framework-specific patterns

- Search GitHub for example implementations

- Search for known pitfalls and issues

- Search for performance considerations

- Identify 2-4 candidate approaches with pros/cons

3. **VERIFY** - Context7 (for EVERY library/framework):

- Fetch official docs for each candidate approach

- Confirm APIs and patterns are current

- Check for deprecation warnings

- Get correct implementation details

- Verify version compatibility

4. **SYNTHESISE**: Compare exploration findings against official docs. Reject approaches that are outdated/incorrect.

5. **PRESENT**:

- Summarise recommended approach with reasoning

- Cite web sources for why (community validation)

- Cite Context7 for how (official correctness)

- List rejected alternatives and why

- Confidence level (High/Medium/Low)

- Wait for approval before implementing

---

Workflow: file analysis

**Trigger**: "perform file analysis on [file]"

Execute ALL phases:

1. **READ**: Read the target file completely.

2. **TRACE IMPORTS**: For each import, read the source file.

3. **TRACE EXPORTS**: Search for ALL files that import this file.

4. **RELATED FILES**: Check for related type definitions and config files.

5. **MAP**: Present a dependency tree showing all relationships.

6. **EXPLORE** - Web Search (minimum 3 searches):

- Search for best practices for patterns used

- Search for known issues with these approaches

- Search for whether patterns are current or outdated

7. **VERIFY** - Context7:

- Fetch docs for libraries/APIs used

- Confirm patterns match current official recommendations

- Identify any deprecated usage

8. **ISSUES**: Identify problems, outdated patterns, or inconsistencies. Cite sources.

---

Workflow: implementation plan

**Trigger**: "perform implementation plan on [feature/change]"

Execute ALL phases:

1. **INVESTIGATE**: Read ALL files in affected area. Map dependencies. Identify components, hooks, utilities, types involved.

2. **EXPLORE** - Web Search (minimum 5 searches):

- Search for how others implement this type of feature

- Search for best practices

- Search for potential pitfalls

- Search framework-specific patterns

- Identify candidate implementation approaches

3. **VERIFY** - Context7 (for EVERY library involved):

- Fetch docs to confirm correct patterns

- Get exact API signatures

- Check for version-specific considerations

- Validate explored approaches are officially supported

4. **PLAN**:

- List every file that needs changes and what changes

- Identify risks and breaking changes

- Propose order of operations

- Note which patterns come from official docs

5. **PRESENT**: Show complete plan with file-by-file breakdown. Wait for approval before any code.

---

Workflow: commit session

**Trigger**: "perform commit session"

1. Run `git status` and `git diff --name-only`

2. Exclude markdown: `git reset HEAD "*.md" "**/*.md"`

3. Group changes by logical unit

4. Commit each group separately using conventional commits

5. Push to remote

**Commit format**: `type(scope): description`

---

Workflow: commit all

**Trigger**: "perform commit all"

Same as commit session but includes ALL local changes (staged + unstaged).

---

Workflow: code review

**Trigger**: "perform code review on [file/changes]"

1. **REVIEW**: Review changes critically. Identify potential issues, edge cases, breaking changes.

2. **EXPLORE** - Web Search (minimum 3 searches):

- Search for issues with patterns used

- Search for better alternatives

- Search for security considerations if relevant

3. **VERIFY** - Context7:

- Confirm patterns match official recommendations

- Check for deprecated usage

- Verify correct API usage

4. **CHECK**: Verify consistency with existing patterns. Check for missing error handling, loading states, types.

5. **PRESENT**: Present concerns ranked by severity. Cite sources.

---

Workflow: visual review

**Trigger**: "perform visual review on [page/component]"

UI/UX consistency check:

1. **DESIGN SYSTEM**: Check design system documentation compliance

2. **COLOURS**: Verify brand colour usage

3. **TYPOGRAPHY**: Check font families and sizing

4. **SPACING**: Verify responsive spacing patterns

5. **COMPONENTS**: Confirm utility patterns (cn(), cva())

6. **ACCESSIBILITY**: Focus states, contrast ratios, touch targets

7. **RESPONSIVE**: Test at 375px, 768px, 1024px, 1440px

8. **DARK MODE**: If applicable, verify dark theme tokens

---

Workflow: accessibility audit

**Trigger**: "perform accessibility audit on [page/component/site]"

WCAG 2.2 AA compliance check:

1. **SEMANTIC HTML**: Heading hierarchy, landmarks, lists

2. **KEYBOARD**: Tab order, focus management, escape handling

3. **SCREEN READER**: Alt text, ARIA labels, live regions

4. **CONTRAST**: 4.5:1 text, 3:1 large text/UI

5. **MOTION**: prefers-reduced-motion respected

6. **TOUCH TARGETS**: Minimum 24x24px (AA), ideally 44x44px (AAA)

7. **FORMS**: Labels, error messages, required states

---

Workflow: performance audit

**Trigger**: "perform performance audit on [page/component/site]"

Core Web Vitals optimisation:

1. **LCP**: Largest Contentful Paint analysis

2. **INP**: Interaction to Next Paint

3. **CLS**: Cumulative Layout Shift

4. **IMAGES**: Image optimisation, sizes attribute, priority

5. **FONTS**: Font loading strategy, display swap

6. **BUNDLE**: Code splitting, dynamic imports

7. **CACHING**: Server component caching patterns

---

Context7 Usage Pattern

```

1. resolve-library-id("library name")

2. query-docs(library-id, query="specific topic")

```

**Common Library IDs:**

---

Core Rules

1. **No code without research**: Complete BOTH exploration AND verification before writing ANY code.

2. **Explore then verify**: Web search finds candidates, Context7 confirms correctness. Never skip either.

3. **No isolated file changes**: Always trace imports/exports before modifying.

4. **Version verification**: Confirm solutions match your project versions.

5. **Responsive by default**: ALL UI changes must work across mobile, tablet, and desktop.

6. **Approval gates**: Present findings/plan and wait for approval before implementing.

7. **British English**: All comments, commits, and written content. No em dashes.

8. **No build without permission**: Ask user to run build commands and confirm results.

---

Verification Checklist (Before Completing Any Task)