GPT-5 Consultant Skill

Leverage GPT-5's advanced analytical capabilities for complex technical research and problem-solving.

Prerequisites

This skill requires the gpt5-mcp-server to be installed and running locally.

Verify the following tools are available:

• mcp__gpt5-server__gpt5_generate (single-shot analysis)
• mcp__gpt5-server__gpt5_messages (multi-turn conversations)

If not available, check your MCP configuration and ensure the server is running.

When to Use GPT-5

Recognize the signs you're stuck:

• Multiple attempts at the same problem without progress
• Going in circles with different approaches that all fail
• User expressing frustration ("this isn't working", "we're stuck", "nothing's helping")
• Solutions that should work but don't for unclear reasons
• Debugging that reveals more questions than answers

Use GPT-5 for:

• Breaking through impasses where standard approaches have failed
• Complex architectural decisions requiring expert judgment
• Debugging issues involving multiple interacting systems or obscure edge cases
• Novel technical challenges without established documentation
• Getting a fresh perspective when you're too close to the problem

Do NOT use GPT-5 for:

• Questions easily answered by existing documentation or API references
• Common patterns with established solutions
• First attempt at debugging (try standard research first)

When you notice circular debugging or lack of progress, pause and consult GPT-5. Present all context from the conversation so far.

Workflow

1. Context Gathering

When stuck in a circular debugging situation, gather everything from the conversation:

What to include:

• Original problem description and what you're trying to achieve
• Every approach attempted so far and why each failed
• All error messages encountered (include full stack traces)
• Code changes made during debugging attempts
• User's expressions of frustration or confusion (they indicate important dead ends)
• Any patterns you've noticed (intermittent failures, specific conditions)
• Current system state and constraints

How to organize it:

markdown
**Original Goal:**
[What we're trying to accomplish]

**Timeline of Attempts:**
1. First approach: [what we tried] → Result: [why it didn't work]
2. Second approach: [what we tried] → Result: [why it didn't work]
3. [etc.]

**Current Status:**
[Where we are now, what's still broken]

**Technical Details:**
[Code snippets, errors, config - the concrete facts]

**Why We're Stuck:**
[What's confusing, where the circular logic is happening]

Context management:

• Include the full debugging journey, not just the current state
• Highlight where you've gone in circles (tried similar things multiple times)
• Note what seemed promising but failed
• Prioritize: patterns of failure > error messages > code > architecture

2. Query Formulation

Craft precise, context-rich queries:

markdown
**Problem Context:**
[Brief description of the system and what you're trying to achieve]

**Current Situation:**
[What's happening vs what should happen]

**What You've Tried:**
[Previous attempts and their results]

**Technical Details:**
[Code snippets, error messages, relevant config]

**Specific Questions:**
1. [Concrete question about the problem]
2. [Alternative approaches to consider]
3. [Edge cases or implications to watch for]

Query optimization:

• Include actual error messages, not descriptions of errors
• Provide concrete code examples, not abstract patterns
• Specify desired depth: architectural overview vs implementation details
• Request multiple perspectives for architectural decisions

3. Tool Selection

Single-shot analysis (gpt5_generate):

javascript
{
  input: "Your complete context and question here",
  reasoning_effort: "high",  // high=architecture/novel, medium=debugging, low=straightforward
  instructions: "Optional system instructions"
}

Multi-turn conversation (gpt5_messages):

javascript
{
  messages: [
    {role: "user", content: "Initial context and question"},
    {role: "assistant", content: "GPT-5's previous response"},
    {role: "user", content: "Follow-up question"}
  ],
  reasoning_effort: "medium"
}

Use messages for:

• Follow-up questions on previous responses
• Iterative refinement of solutions
• Drilling into implementation details after architectural overview

4. Quality Validation

After receiving GPT-5's response, verify:

Completeness:

• Does it address all aspects of the original question?
• Are edge cases covered?
• Are assumptions stated clearly?

Feasibility:

• Can recommendations be implemented with current tech stack?
• Are time/resource constraints considered?
• Do suggestions align with stated requirements?

Confidence assessment:

• High: Specific code examples, references to docs, clear reasoning
• Medium: Multiple approaches suggested, some uncertainty noted
• Low: Speculative language, missing details, contradictions

When to iterate:

• Response seems incomplete or contradictory
• Edge cases aren't addressed
• Implementation details are vague
• Recommendations conflict with requirements

Ask follow-up questions using gpt5_messages to build on previous context.

5. Result Synthesis

Present findings with:

Summary:

• Key insights in 2-3 sentences
• Confidence level (high/medium/low)

Recommendations: Ranked by priority and impact:

1. Immediate action (what to do first)
2. Secondary improvements
3. Long-term considerations

Next Steps:

• Specific actions to take
• Time estimates where possible
• What to validate before implementing

Warnings:

• Potential pitfalls identified by GPT-5
• Assumptions that need verification
• Areas requiring additional research

Common Patterns

Architectural decisions:

bash
Query: "Should we use event sourcing or CRUD for financial transactions?"
Reasoning effort: high
Follow-up: Ask about specific implementation challenges for chosen approach

Debugging distributed systems:

bash
Query: Include full error logs, system topology, timing diagrams
Reasoning effort: medium
Follow-up: Request specific debugging steps based on diagnosis

Novel technical challenges:

bash
Query: Describe the problem, what makes it novel, what research you've done
Reasoning effort: high
Follow-up: Deep dive on the most promising approach

Error Handling

If GPT-5 is unavailable or returns errors:

• Fall back to comprehensive web search
• Consult official documentation
• Check relevant Stack Overflow discussions
• Consider if the problem actually needs GPT-5 or if simpler research suffices

Document that GPT-5 was unavailable and note when to retry.

Examples

Example 1: Circular debugging (the key use case)

Input: "We've been debugging this Next.js API route for 2 hours and getting nowhere.

Original goal: Fix 500 error on POST /api/users endpoint

Attempts:
1. Added try-catch around Prisma query → Still throwing unhandled promise rejection
2. Changed async/await to .then().catch() → Same error
3. Added error middleware → Error not being caught by middleware
4. Wrapped entire handler in try-catch → Error happens before handler executes
5. User says: 'This makes no sense, we're missing something obvious'

Current status: UnhandledPromiseRejectionWarning persists

Technical details:
- Error: UnhandledPromiseRejectionWarning: PrismaClientValidationError
- Stack trace points to line that IS wrapped in try-catch
- Using Next.js 14 App Router, TypeScript 5.3, Prisma 5.8
- Code: 
  ```typescript
  export async function POST(req: Request) {
    try {
      const body = await req.json();
      const user = await prisma.user.create({ data: body });
      return Response.json(user);
    } catch (error) {
      console.error('Caught error:', error); // This never logs
      return Response.json({ error: 'Failed' }, { status: 500 });
    }
  }
  ```
- The error happens, but catch block never executes
- Other API routes with identical pattern work fine

Why we're stuck: Try-catch should catch this. Error middleware should catch this.
Nothing is catching it. What are we fundamentally misunderstanding about Next.js error handling?"

Reasoning effort: high

Example 2: TypeScript type inference breaking

Input: "TypeScript infers the wrong type and I can't figure out why.

Context: Building a generic API client with typed responses.
Code works but types are broken:

async function apiCall<T>(endpoint: string): Promise<T> { const res = await fetch(endpoint); return res.json(); // TypeScript infers 'any' here, not 'T' }

const user = await apiCall<User>('/api/user'); // user is typed as 'any', not 'User'

Tried:
1. Explicit return type annotation → Still infers 'any'
2. Type assertion (as T) → Works but defeats the purpose
3. Generic constraints → No change
4. Different tsconfig settings → No improvement

Question: Why isn't TypeScript propagating the generic type through the promise chain?
What's the proper pattern for typed API clients?"

Reasoning effort: medium

Example 3: React hook dependency array confusion

Input: "useEffect running infinitely despite correct dependencies.

Code:

const filters, setFilters] = useState({ status: 'active', sort: 'name' });

useEffect(() => { fetchUsers(filters); }, filters]); // This causes infinite re-renders

Tried:
1. Memoizing filters with useMemo → Still infinite
2. JSON.stringify in dependency array → Works but feels wrong
3. Separate state for each filter → Messy, too many useState calls
4. Using useCallback on fetchUsers → No change

Every solution feels hacky. What's the right pattern for object dependencies?"

Reasoning effort: medium

Example 4: Follow-up iteration

Messages: [
  {role: "user", content: "[Initial question about NextAuth session type errors]"},
  {role: "assistant", content: "[GPT-5's recommendation to use module augmentation]"},
  {role: "user", content: "You suggested module augmentation for NextAuth types. 
   I added the declaration file but TypeScript still doesn't recognize the custom 
   session properties. Do I need to configure something in next-auth.d.ts or is 
   there a specific import pattern I'm missing?"}
]

Reasoning effort: medium

Input: "Choosing between GraphQL and REST for new API.
Context: Mobile app + web dashboard, 50+ endpoints, real-time updates needed.
Constraints: Team has REST experience, 3-month timeline.
Question: Which approach and why? What are the implementation risks?"

Reasoning effort: high

Example 3: Follow-up iteration

Messages: [
  {role: "user", content: "[Initial question about microservices architecture]"},
  {role: "assistant", content: "[GPT-5's architectural recommendation]"},
  {role: "user", content: "You suggested event sourcing for service communication. 
   How would we handle eventual consistency in the user profile service?"}
]

Reasoning effort: medium