📝 Prompt Format

Golden Rule

Standard Claude Code Prompt Format

CLAUDE CODE PROMPT - [Brief Title]

File: E:\Lucas\Personal-Productivity\dashboards\[filename]

Issue: [What's wrong - 2-3 sentences max. Describe the symptom the user sees.]

Root Cause: [Why it's broken - 2-3 sentences. Technical explanation.]

Fix Required:
1. [Conceptual change 1 - WHAT not HOW]
2. [Conceptual change 2]
3. [Conceptual change 3]

Logic: [Plain English description of the algorithm or approach. No code.]

Testing:
1. [Specific test step 1]
2. [Specific test step 2]
3. [Expected result]

Execute this fix now.

Prompt Rules

✅ DO:

• One prompt per bug/feature
• Use conceptual descriptions
• Describe WHAT needs to change
• Include specific testing steps
• End with "Execute this fix now."
• Wrap in code block for easy copying

❌ DON'T:

• Include exact code snippets
• Combine multiple bugs in one prompt
• Use prescriptive "find X, replace with Y" format
• Skip the testing section
• Make it so long it's confusing

❌ BAD Example (Too Prescriptive)

Find this code in teacher-review.html:

const content = submission.content || submission.writtenWork;

Replace with:

const content = submission.content || submission.writtenWork || '';
if (submission.canvasData) {
  contentDiv.innerHTML = `<img src="${submission.canvasData}" />`;
}

Why bad: Gives exact code. Claude Code just copies instead of understanding.

✅ GOOD Example (Conceptual)

CLAUDE CODE PROMPT - Fix Teacher Portal Math Display

File: E:\Lucas\Personal-Productivity\dashboards\teacher-review.html

Issue: Math submissions show empty content in teacher portal. 
Canvas drawings not visible.

Root Cause: Content rendering only checks `content` property. 
Math uses `canvasData` (base64 image).

Fix Required:
1. Find where submission content is rendered
2. Add check for canvasData property
3. If canvasData exists, render as img element
4. Keep existing text rendering for other subjects

Logic: Check canvasData first, render as image if exists. 
Then check content/writtenWork for text. 
Show empty state only if all are missing.

Testing:
1. Submit Math with canvas drawing
2. View in teacher portal
3. Should see the drawing as an image

Execute this fix now.

Why good: Describes intent. Claude Code understands and implements correctly.

Optional: Confidence & Risk Scoring

For complex fixes, include before the prompt:

**Severity:** [Critical/High/Medium/Low]
**Confidence Score:** [0-100%]
**Risk Score:** [1-10]
**Files Affected:** [list]

Documentation Update Trigger

When a fix affects user-facing features, append:

DOCS UPDATE REQUIRED:
- Page(s): [list affected pages]
- Change: [brief description]
- Glossary: [new terms if any]

Complete Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    DEVELOPMENT WORKFLOW                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. ANALYZE (Claude Chat - Opus/Sonnet)                         │
│     - Review bug/feature request                                 │
│     - Generate conceptual prompt                                 │
│     - Wrap in code block                                        │
│                                                                  │
│  2. IMPLEMENT (Claude Code - VSCode)                            │
│     - Copy prompt from chat                                      │
│     - Paste into Claude Code                                    │
│     - Let Claude Code figure out the code                       │
│                                                                  │
│  3. TEST (Human - Browser)                                      │
│     - Follow testing steps from prompt                           │
│     - Verify fix works                                           │
│     - Report PASS ✅ or FAIL ❌                                  │
│                                                                  │
│  4. ITERATE (If FAIL)                                           │
│     - Report failure details to Claude Chat                     │
│     - Get revised prompt                                        │
│     - Return to step 2                                          │
│                                                                  │
│  5. COMMIT (After all fixes pass)                               │
│     - git add -A                                                 │
│     - git commit -m "descriptive message"                       │
│     - git push                                                   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Quick Reference

ONE bug = ONE prompt
CONCEPTUAL descriptions only
NO exact code snippets
ALWAYS include testing steps
END with "Execute this fix now."
WRAP in code block for easy copy