ezCater Research Methodology

Investigate ezCater codebases, architectural decisions, and project histories using multiple data sources including Glean, Atlassian (Jira/Confluence), GitHub, and Git.

Overview

ezCater research requires synthesizing information from multiple internal sources. This skill provides proven methodologies for:

• Finding why architectural decisions were made
• Understanding code evolution over time
• Discovering historical context for current implementations
• Researching multi-system interactions and workflows

When to use this skill vs deep research agent:

• Use this skill: Straightforward investigations, specific PR/ticket lookups, single-source searches
• Use deep research agent: Complex multi-source synthesis, historical timelines, architectural decision investigations requiring extensive context

CRITICAL: Access Requirements

Cannot access resources directly. Must use appropriate tools:

Google Docs / Google Drive

• ❌ CANNOT access Google Docs URLs directly
• ✅ MUST use Glean MCP tools (mcp__glean__company_search, mcp__glean__chat)
• Glean indexes Google Docs and retrieves content

Atlassian (Jira / Confluence)

• ❌ CANNOT access ezcater.atlassian.net URLs directly
• ✅ MUST use atl CLI for all Jira and Confluence access
• Commands: atl jira issue view FX-123, atl confluence search "keywords"

GitHub

• ✅ Use gh CLI for PR/issue searches
• ✅ Use git commands for repository analysis
• ✅ Use Read tool for files in checked out repositories

Research Strategy by Question Type

Architectural Decisions

"Why was X chosen over Y?"

1. Search Glean for design docs, RFCs, ADRs using keywords like:
   • "[feature] decision", "[component] architecture", "why [technology]"
2. Find epics/tickets using atl jira search "project = <PROJECT> AND text ~ 'keywords'"
3. Locate PRs with gh pr list --search "keywords" --repo owner/repo
4. Review git history for implementation context using git log --grep="pattern"

See references/glean-search-guide.md for detailed Glean querying strategies. See examples/architectural-decision.md for a complete walkthrough.

Code Evolution

"How did feature X evolve over time?"

1. Trace file history with git log --follow -p -- <file>
2. Find related PRs using gh pr list --search "feature-name"
3. Search Glean for discussions using feature name keywords
4. Check Jira for feature requests: atl jira search "project = FX AND summary ~ 'feature'"

See references/github-git-analysis.md for git history techniques. See examples/code-evolution.md for a complete example.

Process Understanding

"How do I get an order to state X?" or "What triggers workflow Y?"

1. Search Glean for process documentation using keywords like "order lifecycle", "state machine"
2. Find relevant code using Grep for state transitions, workflow definitions
3. Check Confluence using atl confluence search "order process" for diagrams and specs
4. Locate test fixtures that demonstrate the process

See references/atlassian-cli-guide.md for atl CLI patterns. See examples/process-understanding.md for a workflow investigation example.

Multi-System Interactions

"How does system A interact with system B?"

1. Search Glean for integration documentation
2. Find API contracts in code using Grep for client/service definitions
3. Check Confluence for architecture diagrams: atl confluence search "architecture"
4. Review recent PRs affecting both systems using gh pr list --search "systemA systemB"

Tool Usage Patterns

Glean Search

Use Glean MCP for internal information:

Query: "order management migration decision"
Datasources: ["confluence", "slack", "gdrive"]

Effective queries:

• Be specific: "feature flag eppo provider" not just "feature flags"
• Include context: "liberty authentication refactor" not just "authentication"
• Try variations: "DM rails seeders", "delivery management backfills"

See references/glean-search-guide.md for complete search strategies.

Atlassian CLI

Search Jira tickets:

atl jira search "project = FX AND text ~ 'delivery tracking'"
atl jira issue view FX-4623

Search Confluence:

atl confluence search "order state machine"
atl confluence page view 12345678

See references/atlassian-cli-guide.md for full command reference and examples.

GitHub CLI

Search PRs:

gh pr list --repo ezcater/ez-rails --search "authentication" --limit 20
gh pr view 1234 --repo ezcater/ez-rails --json title,body,comments

Search issues:

gh issue list --repo ezcater/delivery-management-rails --search "seeder"

Git History

File evolution:

git log --follow -p -- path/to/file.rb
git blame path/to/file.rb

Commit searches:

git log --grep="feature flag"
git log --all --grep="migration"

See references/github-git-analysis.md for advanced git techniques.

Information Synthesis

After gathering information from multiple sources:

1. Create timeline - Order findings chronologically to show evolution
2. Identify stakeholders - Note who made decisions and why
3. Understand business context - Connect technical decisions to business needs
4. Recognize trade-offs - Explain what was gained and what was sacrificed
5. Cross-reference sources - Confirm findings across Glean, Jira, GitHub, git

See references/synthesis-reporting.md for detailed synthesis techniques.

Response Format

Structure research findings clearly:

Executive Summary: Direct answer (2-3 sentences)

Key Findings:

• Finding 1 with evidence
• Finding 2 with evidence
• Finding 3 with evidence

Historical Context (if relevant):

• Timeline of decisions and changes
• Stakeholders involved
• Business drivers

References:

• Jira: FX-1234
• PR: ezcater/ez-rails#5678
• Commit: abc123def
• Confluence: Title

Quality Standards

• Be specific: Include ticket numbers, PR links, commit SHAs, dates
• Cite sources: Always reference where information was found
• Acknowledge gaps: State explicitly what couldn't be found
• Distinguish facts from speculation: Make clear what's confirmed vs. inferred
• Anticipate follow-ups: Address obvious related questions

Common Research Scenarios

Finding Original Implementation

1. Use gh pr list --search "initial [feature]" to find first PR
2. Check PR description for original requirements
3. Find linked Jira ticket for business context
4. Review commit messages for implementation decisions

Understanding Recent Changes

1. Use git log --since="1 month ago" --grep="[feature]"
2. Check recent PRs with gh pr list --search "is:merged [feature]"
3. Search Glean for Slack discussions in recent timeframe
4. Check Jira for recent bugs or improvements

Investigating Production Issues

1. Search Jira for related tickets: atl jira search "project = FX AND text ~ 'error'"
2. Find relevant code with Grep
3. Check git blame for recent changes
4. Search Glean for related incidents or postmortems

Special Considerations

EngPortal Documentation

EngPortal content comes from GitHub files:

• URL: https://engportal.ezcater.com/docs/.../component/repo-name/path
• Source: https://github.com/ezcater/repo-name/blob/main/path.md

Access via:

• Read file directly if repo checked out under /Users/doughughes/code/ezcater
• Ask Glean for engportal content
• Use gh CLI to read from GitHub

Checked Out Repositories

If repository exists under /Users/doughughes/code/ezcater:

• Read files directly with Read tool
• Run git commands in repository directory
• Use grep/glob for code searches

Multiple Projects

ezCater has many interconnected projects:

• ez-rails: Main monolith
• delivery-management-rails: Delivery tracking
• omnichannel-rails: Multi-channel features
• liberty: Mobile app backend

When researching cross-project features, check all relevant repositories.

Additional Resources

Reference Files

For detailed techniques and patterns, consult:

• references/glean-search-guide.md - Glean search strategies and datasource selection
• references/atlassian-cli-guide.md - Complete atl CLI command reference
• references/github-git-analysis.md - Advanced gh CLI and git history techniques
• references/synthesis-reporting.md - Connecting dots and reporting findings

Example Files

Working examples of research investigations in examples/:

• examples/architectural-decision.md - Researching why a technology was chosen
• examples/code-evolution.md - Tracing feature implementation over time
• examples/process-understanding.md - Understanding workflows and state transitions

When to Escalate to Deep Research Agent

Use the deep research agent (by saying "do deep research" or "deep research needed") when:

• Investigation requires synthesizing 5+ sources
• Need comprehensive historical timeline
• Architectural decision investigation spanning multiple systems
• Research involves connecting dots across quarters/years
• Question requires extensive Opus-level reasoning

For straightforward searches, PR lookups, or single-system investigations, this skill provides efficient guidance without the overhead of the autonomous agent.