gpt5-consultant by nicknisi

---
name: gpt5-consultant
description: Use this skill when stuck in circular debugging, when solutions aren't working despite multiple attempts, or when the user expresses frustration with lack of progress. Bring in GPT-5 as a third-party consultant to provide fresh perspective on complex technical problems, architectural decisions, or multi-system debugging issues. Ideal when you've tried multiple approaches without success, when the problem involves obscure edge cases or novel challenges, or when a second expert opinion would help break through an impasse. Gather all context from the conversation so far and present it comprehensively to GPT-5.
---

# 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:

```typescript
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:
```typescript
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
```