feed-the-machine 1.7.11 → 1.7.13

package/ftm-mind/references/decide-act-protocol.md

@@ -107,6 +107,34 @@ Act is clean, decisive execution — but execution of **approved** work only.
 
 **This applies to ALL execution methods** — Bash commands, MCP calls, Python scripts, curl, direct API calls. The plan-gate hook catches Edit/Write/MCP, but Bash API calls bypass it. This checkpoint is the only thing that catches those. Do not skip it.
 
+### Compare Before You Loop (MANDATORY for external system operations)
+
+When working with external systems (Freshservice, Okta, Jira, Trelica, any API), **never trial-and-error your way to a solution.** Instead:
+
+**Step 1: Find a working reference.**
+Before making any changes, find an existing resource that already works the way you want the target to work. Examples:
+- Updating a catalog item's roles table? GET the working one (HR Acuity #630) AND the broken one. Diff them field by field.
+- Fixing an Okta group mapping? GET a group that works correctly and compare its config to the broken one.
+- Updating a Jira automation? Read a working rule's config before touching the broken one.
+
+**Step 2: Diff, don't guess.**
+Compare the working reference against the target. The fix is almost always a small, specific difference — a missing field option, a different encoding, a wrong position value. Find that diff. Don't hypothesize about what might be wrong.
+
+**Step 3: Make targeted changes.**
+Change ONLY what the diff revealed. One field at a time if needed. Verify after each change.
+
+**The trial-and-error trap**: When an API call fails, your instinct is to try a different endpoint, different payload, different method. After 3 failed attempts you're in a loop — guessing at combinations. STOP. Go back to Step 1. The answer is in the working reference, not in your next guess.
+
+**Red flags that you're in a loop:**
+- You've made 3+ API calls to the same system without a success
+- You're trying different URL path formats (underscore vs hyphen, internal ID vs display ID)
+- You're adding/removing fields from the payload hoping one combination works
+- You're reading API docs or source code to figure out the endpoint (the playbook should have this)
+
+**When you detect a loop:** STOP executing. Tell the user: "I've tried N approaches and none worked. Let me compare against a working reference before continuing." Then do Step 1.
+
+**The April 2026 lesson**: A one-field-option diff (`requester_can_edit: "true"`) was the entire fix for the Freshservice roles table not rendering. It took 15+ API calls, accidental field duplication, and destructive deletion of two catalog items to discover what a 30-second field-by-field comparison against the working HR Acuity item would have revealed immediately.
+
 ### 1. Direct action
 
 For micro tasks:

package/ftm-mind/references/orient-protocol.md

@@ -290,6 +290,47 @@ Skip this step if:
 - The session context already contains recently loaded task state (within 15 minutes)
 - The request is purely local with no operational relevance (e.g., pure code edits)
 
+## Playbook Lookup (MANDATORY before any external system operation)
+
+**Before executing any operation on an external system (Freshservice, Okta, Jira, Trelica, S3, etc.), check for an existing playbook.** This is not optional. Playbooks encode hard-won lessons — API quirks, encoding requirements, field types that can't be updated, correct endpoint paths. Skipping this step means repeating every mistake the playbook was written to prevent.
+
+**Step 1: Check brain.py playbooks.**
+
+```
+python3 ~/.claude/skills/ftm/bin/brain.py --playbook-match "[describe the operation]" --playbook-match-source freshservice
+```
+
+If a match returns with confidence > 0.2, read the full playbook before proceeding.
+
+```
+python3 ~/.claude/skills/ftm/bin/brain.py --playbook-list
+```
+
+Also list all playbooks and scan names — sometimes the match query misses a relevant one.
+
+**Step 2: Check repo-local playbooks.**
+
+```
+ls docs/playbooks/ 2>/dev/null
+```
+
+If the current repo has a `docs/playbooks/` directory, scan it for files matching the target system. Read any relevant playbook before writing a single line of code.
+
+**Step 3: Check blackboard experiences.**
+
+Read `experiences/index.json` and filter by tags matching the target system. Load matching experience files and check for `code_patterns` and `api_gotchas` fields.
+
+**What playbooks prevent:**
+- Using raw HTML when Freshservice requires entity-encoded HTML (`html.escape()`)
+- Trying to PUT on `service_catalog/items/{internal_id}` when the correct path is `service-catalog/items/{display_id}`
+- Including `custom_lookup_bigint` fields in API updates (they're admin-UI-only)
+- Deleting and recreating resources when an in-place update works
+- Repeating 10+ failed API calls to discover what the playbook already documents
+
+**The April 2026 Braintrust incident**: A playbook existed (`docs/playbooks/freshservice-service-catalog-item.md`), the blackboard had the lesson ("FS rich text tables require html.escape()"), and a brain.py playbook (`fs-hide-catalog-el`) was available. None were consulted. The result: 15+ failed API attempts, accidental creation of duplicate fields, then destructive deletion of two catalog items breaking S3 workflow automation.
+
+**If no playbook exists** and the operation succeeds after trial-and-error, the auto-playbook hook should trigger. If it doesn't, proactively invoke ftm-capture to save the working pattern.
+
 ## Orient Synthesis
 
 Before leaving Orient, silently synthesize all signals into one internal picture:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feed-the-machine",
-  "version": "1.7.11",
+  "version": "1.7.13",
   "description": "A brain upgrade for Claude Code — 26 skills that teach it how to think before acting, remember across conversations, debug like a war room, run plans on autopilot with agent teams, and get second opinions from GPT & Gemini. Plus 15 hooks that automate the boring stuff.",
   "license": "MIT",
   "author": "kkudumu",