my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

my-project-public — gitlawb

#1	# Troubleshooting Guide
#2
#3	Common issues and solutions for AI agent creation and usage.
#4
#5	---
#6
#7	## Agent Behavior Issues
#8
#9	### Agent Ignores Instructions
#10
#11	Symptoms:
#12
#13	- Doesn't follow specified format
#14	- Skips important steps
#15	- Acts generically instead of specialized role
#16
#17	Solutions:
#18
#19	1. Make instructions more explicit
#20
#21	```
#22	❌ "Be professional"
#23	✅ "Use formal business tone. No contractions. Address as 'Dear [Name]'"
#24	```
#25
#26	2. Use numbered steps for processes
#27
#28	```
#29	When responding:
#30	1. First, acknowledge the request
#31	2. Then, provide analysis
#32	3. Finally, give recommendation
#33	```
#34
#35	3. Add examples of desired behavior
#36
#37	```
#38	EXAMPLE:
#39	User: "Summarize this meeting"
#40	You: "## Key Decisions
#41	- Approved Q3 budget..."
#42	```
#43
#44	4. Check prompt length
#45
#46	- If over 1000 words, model may miss details
#47	- Condense or break into clear sections
#48
#49	---
#50
#51	### Inconsistent Output Quality
#52
#53	Symptoms:
#54
#55	- Sometimes excellent, sometimes poor
#56	- Format changes between responses
#57	- Tone varies unpredictably
#58
#59	Solutions:
#60
#61	1. Lower temperature
#62
#63	- Set to 0.1-0.3 for consistent behavior
#64	- 0 = completely deterministic
#65
#66	2. Add format constraints
#67
#68	```
#69	ALWAYS format as:
#70	- Section 1: [specific content]
#71	- Section 2: [specific content]
#72	- Never deviate from this structure
#73	```
#74
#75	3. Remove ambiguous language
#76
#77	```
#78	❌ "Be helpful and creative"
#79	✅ "Provide exactly 3 options. Format as numbered list."
#80	```
#81
#82	---
#83
#84	### Agent Too Verbose
#85
#86	Symptoms:
#87
#88	- Responses too long
#89	- Unnecessary details
#90	- Rambling explanations
#91
#92	Solutions:
#93
#94	1. Set explicit length limits
#95
#96	```
#97	- Maximum 150 words per response
#98	- Use bullet points for anything over 3 items
#99	- One paragraph maximum
#100	```
#101
#102	2. Increase frequency penalty
#103
#104	- Set to 0.8-1.5
#105	- Discourages repetitive filler words
#106
#107	3. Add brevity instructions
#108
#109	```
#110	BREVITY RULES:
#111	- Get to the point immediately
#112	- No introductory phrases
#113	- Cut all unnecessary words
#114	- Active voice only
#115	```
#116
#117	---
#118
#119	### Agent Too Brief
#120
#121	Symptoms:
#122
#123	- Incomplete answers
#124	- Missing critical details
#125	- Unhelpful brevity
#126
#127	Solutions:
#128
#129	1. Request elaboration in prompt
#130
#131	```
#132	- Provide comprehensive coverage
#133	- Include examples for each point
#134	- Explain reasoning
#135	- Minimum 200 words when appropriate
#136	```
#137
#138	2. Lower frequency penalty
#139
#140	- Set to 0 or negative
#141	- Allows more natural expression
#142
#143	3. Add detail requirements
#144
#145	```
#146	For each recommendation:
#147	- Why it works
#148	- How to implement
#149	- Potential issues
#150	- Expected timeline
#151	```
#152
#153	---
#154
#155	### Repetitive Language
#156
#157	Symptoms:
#158
#159	- Same words/phrases repeated
#160	- Redundant content
#161	- Circular explanations
#162
#163	Solutions:
#164
#165	1. Increase presence penalty
#166
#167	```
#168	presence_penalty: 1.0-1.5
#169	```
#170
#171	2. Increase frequency penalty
#172
#173	```
#174	frequency_penalty: 1.0-1.5
#175	```
#176
#177	3. Add variety instructions
#178
#179	```
#180	- Use varied vocabulary
#181	- Don't repeat the same examples
#182	- Provide different angles each time
#183	```
#184
#185	---
#186
#187	## Platform-Specific Issues
#188
#189	### ChatGPT Custom GPT
#190
#191	Issue: GPT doesn't save
#192
#193	- Check if you're on ChatGPT Plus
#194	- Try different browser
#195	- Clear cache and retry
#196	- Verify all required fields filled
#197
#198	Issue: Knowledge files not working
#199
#200	- Confirm file format (PDF, TXT, DOCX supported)
#201	- Check file size (max varies by plan)
#202	- Wait a few minutes after upload
#203	- Try re-uploading
#204
#205	Issue: Can't share GPT
#206
#207	- Check privacy settings (Only me / Link / Public)
#208	- Verify you have GPT Plus
#209	- Try generating new share link
#210	- Check if workplace admin restricted sharing
#211
#212	---
#213
#214	### Clawd Projects
#215
#216	Issue: Instructions not applying
#217
#218	- Verify instructions in Project settings, not chat
#219	- Check you're in correct project
#220	- Try creating new conversation within project
#221	- Restart browser if persistent
#222
#223	Issue: Project knowledge not accessible
#224
#225	- Confirm files uploaded successfully
#226	- Check file format compatibility
#227	- Verify file size under limits
#228	- Wait for processing (large files take time)
#229
#230	Issue: Context limit reached
#231
#232	- Clawd Projects have 200K token limit
#233	- Long conversations + large docs = limit reached
#234	- Solution: Start new conversation in same project
#235	- Or: Remove some uploaded documents
#236
#237	---
#238
#239	### AI Agents Library Marketplace
#240
#241	Issue: Agent not appearing
#242
#243	- Check if PR merged
#244	- Wait 24 hours for deployment
#245	- Clear browser cache
#246	- Search by exact identifier
#247
#248	Issue: Agent translation incorrect
#249
#250	- Our i18n is automated and imperfect
#251	- You can provide manual translations
#252	- Submit PR with corrected locale files
#253	- See CONTRIBUTING.md for format
#254
#255	Issue: Can't add agent to workspace
#256
#257	- Refresh browser
#258	- Check internet connection
#259	- Try different browser
#260	- Report as bug if persistent
#261
#262	---
#263
#264	## JSON/File Issues
#265
#266	### Invalid JSON Error
#267
#268	Common mistakes:
#269
#270	1. Trailing commas
#271
#272	```json
#273	❌ {
#274	"title": "My Agent",
#275	"tags": ["tag1", "tag2",]
#276	}
#277
#278	✅ {
#279	"title": "My Agent",
#280	"tags": ["tag1", "tag2"]
#281	}
#282	```
#283
#284	2. Unescaped quotes
#285
#286	```json
#287	❌ "systemRole": "You are a "professional" agent"
#288
#289	✅ "systemRole": "You are a \"professional\" agent"
#290	```
#291
#292	3. Missing commas
#293
#294	```json
#295	❌ {
#296	"title": "Agent"
#297	"description": "Does stuff"
#298	}
#299
#300	✅ {
#301	"title": "Agent",
#302	"description": "Does stuff"
#303	}
#304	```
#305
#306	Solution:
#307
#308	- Use JSON validator: jsonlint.com
#309	- Use code editor with JSON syntax highlighting
#310	- Copy working example and modify
#311
#312	---
#313
#314	### File Not Found
#315
#316	For GitHub submissions:
#317
#318	1. Check file location
#319
#320	- Must be in `/src/` directory
#321	- Use exact filename from identifier
#322	- Extension must be `.json`
#323
#324	2. Check naming
#325
#326	```
#327	✅ src/my-agent-name.json
#328	❌ src/my_agent_name.json
#329	❌ src/MyAgentName.json
#330	❌ My-Agent-Name.json (wrong directory)
#331	```
#332
#333	3. Verify committed
#334
#335	```bash
#336	git status
#337	git add src/your-agent.json
#338	git commit -m "Add agent"
#339	```
#340
#341	---
#342
#343	## Testing Issues
#344
#345	### Can't Reproduce Results
#346
#347	Problem: Agent works in testing but fails in real use
#348
#349	Solutions:
#350
#351	1. Test with real users
#352
#353	- Have someone else try it
#354	- Use actual scenarios, not synthetic
#355	- Test edge cases and ambiguities
#356
#357	2. Document test cases
#358
#359	```
#360	Test 1: [Scenario]
#361	Input: [What you sent]
#362	Expected: [What should happen]
#363	Actual: [What happened]
#364	```
#365
#366	3. Version control your prompts
#367
#368	- Save each iteration
#369	- Note what changed and why
#370	- Can roll back if needed
#371
#372	---
#373
#374	### Agent Works Sometimes
#375
#376	Causes:
#377
#378	1. Temperature too high
#379
#380	- Randomness causes variation
#381	- Lower to 0.3 or below
#382
#383	2. Ambiguous instructions
#384
#385	- Model interprets differently each time
#386	- Be more explicit
#387
#388	3. Context matters
#389
#390	- Previous messages affect responses
#391	- Test in fresh conversations
#392
#393	---
#394
#395	## Submission Issues
#396
#397	### Pull Request Rejected
#398
#399	Common reasons:
#400
#401	1. Duplicate agent
#402
#403	- Check existing agents first
#404	- Search by function, not just name
#405	- Differentiate if similar
#406
#407	2. Low quality prompt
#408
#409	- Too vague or generic
#410	- No clear purpose
#411	- Poor formatting
#412
#413	3. Inappropriate content
#414
#415	- Violates guidelines
#416	- Offensive/harmful
#417	- Copyright issues
#418
#419	4. Technical errors
#420
#421	- Invalid JSON
#422	- Missing required fields
#423	- Wrong file location
#424
#425	Next steps:
#426
#427	- Read reviewer feedback
#428	- Make requested changes
#429	- Resubmit with explanation
#430
#431	---
#432
#433	### Merge Delayed
#434
#435	Timeline: Usually 48-72 hours
#436
#437	If longer:
#438
#439	- Check PR for reviewer comments
#440	- Verify all checks passed
#441	- Tag maintainer if urgent
#442	- Join Discord for status update
#443
#444	---
#445
#446	## Performance Issues
#447
#448	### Slow Responses
#449
#450	Causes:
#451
#452	1. Model selection
#453
#454	- GPT-4 slower than GPT-3.5
#455	- Clawd Opus slower than Sonnet
#456	- Check model in settings
#457
#458	2. Long context
#459
#460	- Large uploaded files
#461	- Long conversation history
#462	- Solution: Start fresh conversation
#463
#464	3. Complex instructions
#465
#466	- Overly detailed prompts
#467	- Multiple nested conditions
#468	- Simplify if possible
#469
#470	4. High reasoning_effort (Clawd)
#471
#472	- Set to "low" or "medium"
#473	- Reserve "high" for complex tasks
#474
#475	---
#476
#477	### Rate Limits Hit
#478
#479	ChatGPT:
#480
#481	- Plus: \~50 messages/3 hours for GPT-4
#482	- Solution: Use GPT-3.5 or wait
#483
#484	Clawd:
#485
#486	- Pro: Higher limits but still exist
#487	- Solution: Space out requests
#488
#489	AI Agents Library:
#490
#491	- Varies by plan
#492	- Contact support for limit info
#493
#494	---
#495
#496	## Getting More Help
#497
#498	### Before Opening Issue
#499
#500	1. Search existing issues
#501	2. Check FAQ.md
#502	3. Review examples in EXAMPLES.md
#503	4. Test in fresh conversation
#504
#505	### When Opening Issue
#506
#507	Include:
#508
#509	- Agent identifier or full JSON
#510	- What you expected
#511	- What actually happened
#512	- Steps to reproduce
#513	- Platform (ChatGPT/Clawd/AI Agents Library)
#514	- Screenshots if relevant
#515
#516	### Emergency Issues
#517
#518	For critical bugs or security issues:
#519
#520	- Mark as \[URGENT] in subject
#521	- Don't publicly share exploit details
#522
#523	---
#524
#525	## Quick Reference
#526
#527	Problem → Solution:
#528
#529	\| Issue \| Quick Fix \|
#530	\| -------------- \| ---------------------------------- \|
#531	\| Inconsistent \| Lower temperature to 0.3 \|
#532	\| Repetitive \| Increase penalties to 1.0 \|
#533	\| Too long \| Set word limit explicitly \|
#534	\| Too short \| Request elaboration in prompt \|
#535	\| Wrong tone \| Add tone examples \|
#536	\| Ignores format \| Use numbered structure \|
#537	\| Too creative \| Lower temperature \|
#538	\| Too boring \| Increase temperature to 0.7 \|
#539	\| Invalid JSON \| Use validator, check commas/quotes \|
#540	\| Slow \| Choose faster model or simplify \|
#541
#542	---
#543
#544	Still stuck? Join Discord or open an issue with details.
#545
#546
#547

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public