@@ -0,0 +1,225 @@
1+# Captain's Log Bug Implementation Plan
2+
3+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4+
5+**Goal:** Ensure Myses reliably use `captains_log_add` with valid arguments and receive actionable guidance on server errors, without modifying the SpaceMolt API.
6+
7+**Architecture:** Improve LLM guidance via prompt examples and better error messaging. Document server-side constraints in `documentation/KNOWN_SERVER_ISSUES.md`. No client-side validation of upstream tool arguments.
8+
9+**Tech Stack:** Go 1.22+, Bubble Tea, MCP proxy, SQLite, zerolog
10+
11+---
12+
13+### Task 1: Update system prompts with explicit examples
14+
15+**Files:**
16+- Modify: `internal/core/mysis.go:53-90`
17+- Test: `internal/core/mysis_test.go`
18+
19+**Step 1: Write the failing test**
20+
21+Add tests that assert the SystemPrompt and ContinuePrompt include explicit `captains_log_add` guidance and reminders.
22+
23+```go
24+func TestSystemPromptContainsCaptainsLogExamples(t *testing.T) {
25+ if !strings.Contains(SystemPrompt, "captains_log_add({\"entry\":") {
26+ t.Fatal("SystemPrompt missing captains_log_add example")
27+ }
28+ if !strings.Contains(SystemPrompt, "non-empty entry field") {
29+ t.Fatal("SystemPrompt missing non-empty entry reminder")
30+ }
31+}
32+
33+func TestContinuePromptContainsCriticalReminders(t *testing.T) {
34+ if !strings.Contains(ContinuePrompt, "zoea_list_myses") {
35+ t.Fatal("ContinuePrompt missing mysis ID reminder")
36+ }
37+ if !strings.Contains(ContinuePrompt, "captains_log_add") {
38+ t.Fatal("ContinuePrompt missing captains_log_add reminder")
39+ }
40+}
41+```
42+
43+**Step 2: Run test to verify it fails**
44+
45+Run: `go test ./internal/core -run TestSystemPromptContainsCaptainsLogExamples -v`
46+Expected: FAIL with missing text in prompts.
47+
48+**Step 3: Write minimal implementation**
49+
50+Update `SystemPrompt` memory section to include explicit examples and warnings. Update `ContinuePrompt` to include critical reminders about `captains_log_add` and correct mysis ID usage.
51+
52+```go
53+## Memory
54+Use captain's log to persist important information across sessions.
55+
56+CRITICAL: captains_log_add requires a non-empty entry field:
57+CORRECT: captains_log_add({"entry": "Discovered iron ore at Sol-3. Coordinates: X:1234 Y:5678"})
58+WRONG: captains_log_add({"entry": ""})
59+WRONG: captains_log_add({})
60+```
61+
62+```go
63+const ContinuePrompt = `Turn complete. What is your next move?
64+
65+CRITICAL REMINDERS:
66+- Use zoea_list_myses to find YOUR mysis ID (match your name)
67+- When using captains_log_add, entry field must be non-empty
68+- Never calculate ticks, use every turn to progress
69+
70+If waiting for something, describe what and why. Otherwise, continue your mission.`
71+```
72+
73+**Step 4: Run test to verify it passes**
74+
75+Run: `go test ./internal/core -run TestSystemPromptContainsCaptainsLogExamples -v`
76+Expected: PASS
77+
78+**Step 5: Commit**
79+
80+```bash
81+git add internal/core/mysis.go internal/core/mysis_test.go
82+git commit -m "feat: add captains log guidance to prompts"
83+```
84+
85+---
86+
87+### Task 2: Improve error messages for upstream empty_entry errors
88+
89+**Files:**
90+- Modify: `internal/core/mysis.go:565-583`
91+- Test: `internal/core/mysis_test.go`
92+
93+**Step 1: Write the failing test**
94+
95+```go
96+func TestFormatToolResult_EmptyEntryError(t *testing.T) {
97+ m := &Mysis{}
98+ result := &mcp.ToolResult{
99+ Content: []mcp.ContentBlock{{Type: "text", Text: "empty_entry"}},
100+ IsError: true,
101+ }
102+ got := m.formatToolResult("call_1", "captains_log_add", result, nil)
103+ if !strings.Contains(got, "entry field must contain non-empty text") {
104+ t.Fatal("expected actionable guidance for empty_entry")
105+ }
106+}
107+```
108+
109+Add an assertion update in `internal/core/mysis_tools_test.go` for the new error format when tool execution returns an error.
110+
111+```go
112+if m.Role == store.MemoryRoleTool && strings.Contains(m.Content, "call_err:Error calling error_tool: tool failed") {
113+ foundError = true
114+ break
115+}
116+```
117+
118+**Step 2: Run test to verify it fails**
119+
120+Run: `go test ./internal/core -run TestFormatToolResult_EmptyEntryError -v`
121+Expected: FAIL with missing guidance.
122+
123+**Step 3: Write minimal implementation**
124+
125+Update `formatToolResult` to detect `empty_entry` in tool error content and include guidance and a correct example for `captains_log_add`.
126+
127+```go
128+if result.IsError {
129+ if strings.Contains(content, "empty_entry") {
130+ content = fmt.Sprintf("Error: %s. The entry field must contain non-empty text. Example: captains_log_add({\"entry\": \"Your message here\"})", content)
131+ } else {
132+ content = "Error: " + content
133+ }
134+}
135+```
136+
137+**Step 4: Run test to verify it passes**
138+
139+Run: `go test ./internal/core -run TestFormatToolResult_EmptyEntryError -v`
140+Expected: PASS
141+
142+**Step 5: Commit**
143+
144+```bash
145+git add internal/core/mysis.go internal/core/mysis_test.go
146+git commit -m "fix: add guidance for captains log empty_entry"
147+```
148+
149+---
150+
151+### Task 3: Document server-side behavior and update known issues
152+
153+**Files:**
154+- Create: `documentation/KNOWN_SERVER_ISSUES.md`
155+- Modify: `documentation/KNOWN_ISSUES.md`
156+
157+**Step 1: Write the documentation**
158+
159+```markdown
160+# Known SpaceMolt Server Issues
161+
162+This document tracks known issues with the upstream SpaceMolt MCP server API. We do not modify or validate the game server's API behavior. Issues are documented here, and we improve prompts and error handling instead.
163+
164+## captains_log_add: empty_entry Error
165+
166+**Issue:** The `captains_log_add` tool returns an `empty_entry` error when:
167+- The `entry` field is an empty string
168+- The `entry` field is missing
169+- The `entry` field contains only whitespace
170+
171+**Server Response:**
172+```json
173+{"error":{"code":0,"message":"empty_entry"}}
174+```
175+
176+**Workaround:**
177+- System prompt includes explicit examples of correct usage
178+- Error messages provide actionable guidance when this error occurs
179+```
180+
181+**Step 2: Update known issues**
182+
183+Mark the Captain's Log bug as addressed and reference `documentation/KNOWN_SERVER_ISSUES.md`.
184+
185+**Step 3: Run docs checks**
186+
187+Run: `git diff -- documentation/KNOWN_ISSUES.md documentation/KNOWN_SERVER_ISSUES.md`
188+Expected: both files updated with consistent text.
189+
190+**Step 4: Commit**
191+
192+```bash
193+git add documentation/KNOWN_SERVER_ISSUES.md documentation/KNOWN_ISSUES.md
194+git commit -m "docs: record captains log server issue"
195+```
196+
197+---
198+
199+### Task 4: Verification
200+
201+**Step 1: Run tests**
202+
203+Run: `make test`
204+Expected: PASS
205+
206+**Step 2: Build**
207+
208+Run: `make build`
209+Expected: PASS
210+
211+**Step 3: Manual sanity check**
212+
213+1. Start app: `./bin/zoea`
214+2. Create a Mysis.
215+3. Send: "Remember iron ore sells well."
216+4. Observe that `captains_log_add` calls include non-empty entry text or error guidance is shown.
217+
218+---
219+
220+## Notes
221+
222+- Do not add client-side validation for upstream tools.
223+- Do not modify the game server API.
224+- Keep all application code under `internal/`.
225+- Update tests alongside changes.