Clean up debugging docs and investigation logs

Author: cameroncooke

docs/DAP_BACKEND_IMPLEMENTATION_PLAN.md

@@ -1,5 +1,3 @@
-<chatName="DAP backend plan"/>
-
 ## Goal & constraints (grounded in current code)
 
 Implement a real **`lldb-dap` Debug Adapter Protocol backend** that plugs into the existing debugger architecture without changing MCP tool names/schemas. The DAP backend remains **opt-in only** via `XCODEBUILDMCP_DEBUGGER_BACKEND=dap` (current selection logic in `src/utils/debugger/debugger-manager.ts`).
@@ -185,7 +183,7 @@ export class DapTransport {
 - Backend may still serialize higher-level operations if stateful.
 
 **Side effects**
-- Adds a long-lived child process per session.
+- Add a long-lived child process per session.
 - Requires careful memory management in the framing buffer (ensure you slice consumed bytes).
 
 ---
@@ -273,12 +271,12 @@ export async function createDapBackend(opts?: {
   4) `configurationDone` if required by lldb-dap behavior (plan for it even if no-op)
   5) mark attached
 
-- `detach()`:
+- `detach()`
   - send `disconnect` with `terminateDebuggee: false` (do not kill app)
   - dispose transport / kill process
 
-- `dispose()`:
-  - best-effort cleanup; **must not throw** (important because `DebuggerManager.createSession` calls dispose on attach failure)
+- `dispose()`
+  - best-effort cleanup; **must not throw** (important because `DebuggerManager.createSession` calls dispose to clean up on attach failure)
 
 **Method mappings (MCP tools → DebuggerManager → DapBackend)**
 
@@ -439,8 +437,8 @@ private enqueue<T>(work: () => Promise<T>): Promise<T> { ... }
 ```
 
 **Reasoning**
-- Prevent races like:
-  - addBreakpoint + removeBreakpoint in parallel reissuing `setBreakpoints` inconsistently.
+- Prevent races such as:
+  - addBreakpoint + removeBreakpoint in parallel, reissuing `setBreakpoints` inconsistently.
 
 ---
 
@@ -453,7 +451,7 @@ private enqueue<T>(work: () => Promise<T>): Promise<T> { ... }
 ### Where to log
 - `DapTransport`:
   - `log('debug', ...)` for raw events (optionally gated by env)
-  - `log('error', ...)` on process exit while requests pending
+  - `log('error', ...)` on process exit while requests are pending
 - `DapBackend`:
   - minimal `info` logs on attach/detach
   - `debug` logs for request mapping (command names, not full payloads unless opted in)
@@ -514,7 +512,7 @@ New: `src/utils/debugger/__tests__/debugger-manager-dap.test.ts`
 ## Docs updates (grounded in existing docs)
 
 ### 1) Update `docs/DAP_BACKEND_IMPLEMENTATION_PLAN.md`
-Replace/extend the existing outline with:
+Replace/extend the existing outline with the following:
 - finalized module list (`dap/types.ts`, `dap/transport.ts`, discovery helper)
 - breakpoint strategy (stateful re-issue `setBreakpoints`)
 - explicit mapping table per MCP tool
@@ -568,6 +566,6 @@ Add a section “DAP Backend (lldb-dap)”:
 ---
 
 ## Critical “don’t miss” requirements
-- `dispose()` in DAP backend and transport must be **best-effort and never throw**, because `DebuggerManager.createSession()` will call dispose on attach failure.
+- `dispose()` in DAP backend and transport must be **best-effort and never throw** because `DebuggerManager.createSession()` will call dispose on attach failure.
 - Avoid any use of default executors/spawners in tests; ensure `createDapBackend()` accepts injected `executor` + `spawner`.
 - Breakpoint removal requires stateful re-application with `setBreakpoints` / `setFunctionBreakpoints`; plan for breakpoint registries from day one.

docs/DEBUGGING_ARCHITECTURE.md

@@ -190,13 +190,13 @@ Annotated example (simplified):
    - `XCODEBUILDMCP_LLDB> `
 3. Parser behavior:
    - Sentinel marks the end of the command output payload.
-   - Prompt is used to trim the buffer so the next command starts cleanly.
+   - Prompt is used to trim the buffer, so the next command starts cleanly.
 
 ### Output parsing and sanitization
 
 - `handleData()` appends to an internal buffer, and `checkPending()` scans for the sentinel regex
   `/(^|\\r?\\n)__XCODEBUILDMCP_DONE__(\\r?\\n)/`.
-- Output is the buffer up to the sentinel. The remainder is trimmed to the next prompt if present.
+- Output is the buffer up to the sentinel. The remainder is trimmed to the next prompt, if present.
 - `sanitizeOutput()` removes prompt echoes, sentinel lines, the `script print(...)` lines, and empty
   lines, then `runCommand()` returns `trimEnd()` output.
 
@@ -253,7 +253,7 @@ processes. Tests should inject a mock `InteractiveSpawner` into `createLldbCliBa
 ### xcodebuild (Build/Launch Context)
 
 - Debugging assumes a running simulator app.
-- The typical flow is build and launch via simulator tools (for example `build_sim`),
+- The typical flow is to build and launch via simulator tools (for example `build_sim`),
   which uses `executeXcodeBuildCommand` to invoke `xcodebuild` (or `xcodemake` when enabled).
 - After launch, `debug_attach_sim` attaches LLDB to the simulator process.
 

docs/investigations/issue-154-screenshot-downscaling.md

@@ -9,25 +9,25 @@ Investigation started; initial context gathered from the issue description. Cont
 
 ## Investigation Log
 
-### 2025-01-XX - Initial assessment
+### 2026-01-04 - Initial assessment
 **Hypothesis:** Screenshot pipeline always emits full-resolution images and lacks an opt-in scaling path.
 **Findings:** Issue describes full-res screenshots and requests optional downscaling. No code inspected yet.
 **Evidence:** GitHub issue #154 body.
 **Conclusion:** Needs codebase investigation.
 
-### 2025-01-XX - Context builder attempt
+### 2026-01-04 - Context builder attempt
 **Hypothesis:** Use automated context discovery to map screenshot capture flow.
 **Findings:** `context_builder` failed due to Gemini CLI usage error in this environment.
 **Evidence:** Tool error output in session (Gemini CLI usage/help text).
 **Conclusion:** Proceeding with manual code inspection.
 
-### 2025-01-XX - Screenshot capture implementation
+### 2026-01-04 - Screenshot capture implementation
 **Hypothesis:** Screenshot tool stores and returns full-resolution PNGs.
 **Findings:** The `screenshot` tool captures a PNG, then immediately downscales/optimizes via `sips` to max 800px width, JPEG format, quality 75%, and returns the JPEG. Optimization is always attempted; on failure it falls back to original PNG.
 **Evidence:** `src/mcp/tools/ui-testing/screenshot.ts` (sips `-Z 800`, `format jpeg`, `formatOptions 75`).
 **Conclusion:** The current implementation already downscales by default; the gap is configurability (opt-in/out, size/quality controls) and documentation.
 
-### 2025-01-XX - Git history check
+### 2026-01-04 - Git history check
 **Hypothesis:** Recent commits might have added/changed screenshot optimization behavior.
 **Findings:** Recent history shows tool annotations and session-awareness changes, but no indication of configurable screenshot scaling.
 **Evidence:** `git log -n 5 -- src/mcp/tools/ui-testing/screenshot.ts`.

docs/investigations/issue-describe-ui-empty-after-debugger-resume.md

@@ -1,7 +1,7 @@
 # RCA: describe_ui returns empty tree after debugger resume
 
 ## Summary
-When the app is stopped under LLDB (breakpoints hit), the `describe_ui` tool frequently returns an empty accessibility tree (0x0 frame, no children). This is not caused by a short timing gap after resume. The root cause is that the process is still stopped (or immediately re-stopped) due to active breakpoints, so AX snapshotting cannot retrieve a live hierarchy.
+When the app is stopped under LLDB (breakpoints hit), the `describe_ui` tool frequently returns an empty accessibility tree (0x0 frame, no children). This is not because of a short timing gap after resume. The root cause is that the process is still stopped (or immediately re-stopped) due to active breakpoints, so AX snapshotting cannot retrieve a live hierarchy.
 
 ## Impact
 - UI automation appears "broken" after resuming from breakpoints.