# Troubleshooting Guide

> From NerdSmith Founder Track -- Module 0, Lesson 5: Session Management
> When things go wrong with Claude Code, start here.

---

## Quick Diagnosis

| Symptom | Likely Cause | Jump to Section |
|---------|-------------|-----------------|
| Claude asks too many clarifying questions | Missing context in prompt or no CLAUDE.md | Section 1 |
| Output is wrong format/tone/length | Missing constraints in prompt | Section 2 |
| Claude "forgot" earlier instructions | Context overloaded (75%+) | Section 3 |
| Claude edited the wrong file | Ambiguous file reference | Section 4 |
| Claude generated incomplete output | Context near limit, or vague prompt | Section 5 |
| Claude keeps writing code (you're non-technical) | CLAUDE.md missing role definition | Section 6 |
| Claude's responses are getting slower | Context is very high (80%+) | Section 7 |
| Claude made up facts/data | No honesty guardrails in prompt | Section 8 |
| Session feels unproductive | No session plan, tasks too broad | Section 9 |
| Can't find files Claude created | No output folder defined | Section 10 |

---

## Section 1: Claude Asks Too Many Questions

**Symptom:** You ask Claude to do something and it responds with 4-7 clarifying questions.

**Root cause:** Your prompt is missing context. Claude doesn't know enough to act.

**Fix:**

1. **Immediate:** Answer the questions, then add this to the end:
   ```
   Going forward, here's context you can assume for all my requests:
   [paste your key context: role, product, stage, customer]
   ```

2. **Permanent:** Create or update your CLAUDE.md with the 5 essential sections (Project Context, Role, How to Help, File Structure, Style Preferences). Claude reads it automatically -- no more repeated questions.

3. **Per-prompt:** Use the Founder Prompt Formula:
   ```
   [CONTEXT] + [TASK] + [CONSTRAINTS] + [FORMAT]
   ```

---

## Section 2: Wrong Format, Tone, or Length

**Symptom:** Claude writes a 5-page essay when you wanted bullet points. Or uses corporate jargon when you wanted casual tone.

**Fix:**

1. **Redirect immediately:**
   ```
   That's too long and too formal. Rewrite as:
   - Bullet points, not paragraphs
   - Under 500 words
   - Casual tone (like talking to a colleague, not a board meeting)
   ```

2. **Prevent next time:** Add FORMAT and CONSTRAINTS to every prompt:
   ```
   Format: Use bullet points under H2 headings. 500 words max.
   Tone: Conversational, plain English, no buzzwords.
   ```

3. **Prevent permanently:** Add style preferences to CLAUDE.md.

---

## Section 3: Claude Forgot Earlier Instructions

**Symptom:** 20 prompts ago you said "use casual tone" -- now Claude is writing formally. Or Claude contradicts a decision made earlier in the session.

**Root cause:** Context window is overloaded. At 75%+, Claude starts losing earlier parts of the conversation ("lost in the middle" problem).

**Fix:**

1. **Check context:** Type `/usage`
   - Over 75%: Recap immediately with `/recap`
   - Under 75%: Remind Claude: "Remember, I asked for casual tone earlier. Apply that here."

2. **If critical instruction keeps getting forgotten:**
   - Put it in CLAUDE.md (survives across sessions)
   - Or restate it at the start of each new prompt

3. **After recap:** In your new session, frontload the important constraints:
   ```
   Read my recap. Key rules for this session:
   - Casual tone always
   - Under 500 words
   - Save everything to analysis/
   Now continue with [task].
   ```

---

## Section 4: Claude Edited the Wrong File

**Symptom:** You said "update the hero section" and Claude edited the footer, or edited a different file entirely.

**Fix:**

1. **Undo:** Tell Claude to revert:
   ```
   Undo that change. You edited [wrong file]. 
   The file I need you to edit is [exact path/filename].
   The specific section is [paste the section or describe precisely].
   ```

2. **Be more specific next time:**
   - Bad: "Update the hero section"
   - Good: "In `marketing/landing-page.md`, update the ## Hero section (lines 1-10)"

3. **Use file paths, not descriptions:** Claude navigates by path. "The landing page" is ambiguous. `marketing/landing-hero-v3.md` is not.

---

## Section 5: Incomplete Output

**Symptom:** You asked for a 5-section spec, Claude only wrote 3 sections. Or Claude's response trails off mid-sentence.

**Root cause:** Either context is nearly full (Claude can't generate long output) or the prompt didn't clearly specify all sections.

**Fix:**

1. **If context is high (80%+):** Recap, start fresh, re-request.

2. **If context is fine:** Ask Claude to complete it:
   ```
   This is incomplete. You wrote sections 1-3 but missed:
   - Section 4: User Stories
   - Section 5: Success Metrics
   Add them now.
   ```

3. **Prevent next time:** Explicitly list every section you need in the FORMAT part of your prompt.

---

## Section 6: Claude Keeps Writing Code

**Symptom:** You ask for a product spec and Claude includes code snippets, API schemas, or database diagrams. You're a founder, not a developer.

**Fix:**

1. **Immediate:**
   ```
   Remove all code from this document. I'm non-technical.
   Rewrite in plain English that a business person can understand.
   ```

2. **Permanent:** Add to CLAUDE.md:
   ```markdown
   ## My Role
   - NOT a developer (never write code, never use technical jargon)
   - If a technical concept is relevant, explain it in plain English
   ```

---

## Section 7: Claude Is Getting Slow

**Symptom:** Responses take noticeably longer. Claude seems to be "thinking" more.

**Root cause:** High context usage. The more context Claude processes, the slower responses get.

**Fix:**

1. Check `/usage`
2. If over 70%: Finish current task, then `/recap`
3. Going forward: Break big tasks into sessions. Keep each under 50%.

---

## Section 8: Claude Made Up Facts

**Symptom:** Claude states a competitor's pricing as "$49/month" but it's actually $29. Or cites a study that doesn't exist.

**Root cause:** Claude generates plausible-sounding text. Without explicit honesty guardrails, it may present uncertain information as fact.

**Fix:**

1. **Flag the error:**
   ```
   That pricing information is incorrect. [Competitor] is actually $29/month.
   Going forward, mark any data you're not certain about with [UNVERIFIED].
   ```

2. **Add to every research prompt:**
   ```
   Constraints:
   - Mark anything you're uncertain about with [UNVERIFIED]
   - Do not fabricate statistics, pricing, or quotes
   - If you don't know something, say [UNKNOWN] rather than guessing
   ```

3. **Verify important claims yourself.** Claude is a drafting tool, not a fact-checking service. Always verify pricing, statistics, and quotes before using them externally.

---

## Section 9: Session Feels Unproductive

**Symptom:** You've been working for an hour and haven't produced anything useful. Lots of back-and-forth, no deliverables.

**Root cause:** No session plan. Tasks are too broad. Or you're context-switching between unrelated topics.

**Fix:**

1. **Stop and plan.** Before your next prompt, decide:
   - What is the ONE deliverable I need from this session?
   - What format should it be in?
   - Where will I save it?

2. **Use the Daily Workflow Template** to plan sessions in advance.

3. **One task per session** for heavy work. Don't combine research + spec writing + copy creation. Do them in separate, focused sessions.

4. **Start with your prompt, not a conversation.** Instead of chatting with Claude, open with a complete prompt (Context + Task + Constraints + Format).

---

## Section 10: Can't Find Files Claude Created

**Symptom:** Claude said it saved a file, but you can't find it. Or files end up in unexpected locations.

**Fix:**

1. **Ask Claude where it saved:**
   ```
   What files did you create or modify in this session? List full paths.
   ```

2. **Specify save locations in every request:**
   ```
   Save the output to analysis/customer-insights-2026-02-08.md
   ```

3. **Define output folders in CLAUDE.md:**
   ```markdown
   ## File Structure
   - `analysis/` -- Save all Claude outputs here
   ```

4. **Use a consistent naming convention:** `[type]-[topic]-[date].md`
   - `analysis/customer-insights-2026-02-08.md`
   - `specs/task-automation-spec-v1.md`
   - `marketing/landing-hero-v3.md`

---

## Universal Recovery Pattern

When anything goes wrong, this 3-step pattern works:

```
1. STATE THE PROBLEM:  "That's not right. You [what went wrong]."
2. CLARIFY THE FIX:    "What I actually need is [specific correction]."
3. PREVENT RECURRENCE: "Going forward, always [rule to follow]."
```

Claude learns from corrections within the same session. If the correction matters across sessions, add it to CLAUDE.md.

---

*NerdSmith Founder Track -- Module 0: Claude Code Bootcamp*
*Download: Troubleshooting Guide*