windsurfrules.template

# --- gitmem:start ---
# GitMem — Persistent Memory

You have a persistent memory layer called gitmem. Every session starts from
zero — but gitmem carries forward lessons, mistakes, wins, decisions, and
open threads across sessions and projects. Search it. Test it. You might be
amazed at what's already there. If convinced, make it your own.

## Red Lines

### Credential Protection

Credential exposure in conversation history is permanent and irreversible.

1. **NEVER read credential files in full.** Files like `mcp-config.json`, `.env`, `.credentials.json`, `.netrc`, `.npmrc`, SSH keys, or `.pem`/`.key` files must not be read or dumped.
2. **NEVER print environment variable values that contain secrets.** Commands like `env | grep KEY`, `echo $API_KEY`, or `printenv TOKEN` expose credentials in output.
3. **NEVER display API keys, tokens, or secrets in conversation output.**

Safe alternatives: `env | grep -c VARNAME` (count only), `[ -n "$VARNAME" ] && echo "set"` (existence check), `grep -c '"key"' config.json` (structure check).

### Recall Before Consequential Actions

1. **NEVER parallelize `recall()` with actions that expose, modify, or transmit sensitive data.** Recall must complete first.
2. **Confirm scars before acting.** Each recalled scar requires APPLYING (past-tense evidence), N_A (explanation), or REFUTED (risk acknowledgment).
3. **Parallel recall is only safe with benign reads** — source code, docs, non-sensitive config.

## Tools

| Tool | When to use |
|------|-------------|
| `recall` | Before any task — surfaces relevant warnings from past experience |
| `confirm_scars` | After recall — acknowledge each scar as APPLYING, N_A, or REFUTED |
| `search` | Explore institutional knowledge by topic |
| `log` | Browse recent learnings chronologically |
| `session_start` | Beginning of session — loads last session context and open threads |
| `session_close` | End of session — persists what you learned |
| `create_learning` | Capture a mistake (scar), success (win), or pattern |
| `create_decision` | Log an architectural or operational decision with rationale |
| `list_threads` | See unresolved work carrying over between sessions |
| `create_thread` | Track something that needs follow-up in a future session |
| `help` | Show all available commands |

## Session Lifecycle

**Start:** Call `session_start()` at the beginning of every session.

**End:** On "closing", "done for now", or "wrapping up":

1. **Write reflection directly to payload** — do NOT display the full Q&A to the human.
   Internally answer these 9 questions and write them straight to `.gitmem/closing-payload.json`:
   - Q1: What broke that you didn't expect?
   - Q2: What took longer than it should have?
   - Q3: What would you do differently next time?
   - Q4: What pattern or approach worked well?
   - Q5: What assumption was wrong?
   - Q6: Which scars did you apply?
   - Q7: What should be captured as institutional memory?
   - Q8: How did the human prefer to work this session?
   - Q9: What collaborative dynamic worked or didn't?

   Payload schema (`.gitmem/closing-payload.json`):
   ```json
   {
     "closing_reflection": {
       "what_broke": "...",
       "what_took_longer": "...",
       "do_differently": "...",
       "what_worked": "...",
       "wrong_assumption": "...",
       "scars_applied": ["scar title 1", "scar title 2"],
       "institutional_memory_items": "...",
       "collaborative_dynamic": "...",
       "rapport_notes": "..."
     },
     "task_completion": {
       "questions_displayed_at": "ISO timestamp (when reflection started)",
       "reflection_completed_at": "ISO timestamp (when payload written)",
       "human_asked_at": "ISO timestamp (when closing prompt shown)",
       "human_response_at": "ISO timestamp (when human replied)",
       "human_response": "user's correction text or 'none'"
     },
     "human_corrections": "",
     "scars_to_record": [],
     "learnings_created": [],
     "open_threads": [],
     "decisions": []
   }
   ```

2. **Show compact summary** (3-4 lines max):
   ```
   Session close: [N] learnings captured, [M] scars applied, [K] threads open
   Key lesson: [one-sentence from Q7]
   ```

3. **Ask**: "Anything to add before I close this session?" — wait for response, then call `session_close`.

4. **Call `session_close`** with `session_id` and `close_type: "standard"`.

For short exploratory sessions (< 30 min, no real work), use `close_type: "quick"` — no questions needed.
# --- gitmem:end ---